WordPress.org

Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

UNIX Shell Skills

Note: This article covers an advanced topic.

If you have recently moved to WordPress from a hosted blogging solution like Blogger or TypePad, you may be unfamiliar with the tasks of managing a webspace as well as a blog. WordPress is based on PHP; many hosting services use servers running Linux and Apache; many web hosts offer not only web-based control interfaces to their customers but also shell access or command-line interfaces. Many WordPress users may not be familiar with using the shell to manage their file systems. This article explains the more commonly-used UNIX commands and demonstrates how a routine administrative task, namely a minor WordPress upgrade, is carried out in the shell.

wp-cli

wp-cli is "a command line interface for WordPress". It's a great tool that can save you a lot of time if you know more about using shells.

The bash shell

The shell offered by your web host is likely to be bash, which stands for "Bourne Again Shell" after Stephen Bourne who wrote the original modern Unix shell. bash is distributed by the Free Software Foundation. There are a number of different Unix shells. The commands briefly described below apply to almost all of them.

ssh, the secure shell

The Secure Shell (ssh) is a complete set of tools for remote administration of your website. It includes SFTP (Secure File Transfer Protocol) for the uploading of files to your host. The main benefit of using ssh to interface with a remote server is increased security. With other server access tools, your login password may be transferred over the Internet in plain text, which may be intercepted.

To use ssh under Windows, use PuTTY or Cygwin, a UNIX-like environment for Windows. The FileZilla ftp client also supports sftp via ssh-2.

To use ssh on a Mac running OS X, use the Terminal-based SSH program supplied with Mac OS X or download Fugu.

On Linux or UNIX-based operating systems, you can use the text-based SSH and SFTP clients from terminals such as Konsole, Gnome Terminal or xterm. Graphical FTP clients such as KBear and gFTP also support sftp.

Your hosting company will provide the username and host details (the "shell account") necessary to use these. They may be different from the ones you use with your control panel. To use, at the Terminal prompt type
ssh username@host
or
sftp username@host
If the SSH server you're connecting to is running on a non standard port, use the -p argument, followed by the port number. So, for example, if the remote server SSH was running on port 1000 you would type
 ssh username@host -p 1000 
To use sftp to connect to a remote server on a non-standard port use the -oPort= argument. So, for example, to connect to a remote server using sftp on port 1000 you would type
sftp -oPort=1000 user@host

Terminology

Before we get started with some UNIX commands, let's review some terminology.

Directories? Folders?
A Directory is the same thing as a folder. Directories can contain subdirectories.
  • A dot (period or full stop) refers to the current directory; two dots represent the directory above the current directory.
  • The tilde character (~) refers to your home directory.
  • The tilde followed by a user's name (as in ~username) refers to that user's home directory.
Both the dot symbols and the tilde can be treated as directory names. For example, ../config.php refers to the file config.php in the directory above the current one. The directory ./functions.php refers to functions.php in the current directory. And ~/public_html or ~/htdocs are (usually) the names of your main web directory, which is likely to be a subdirectory of your home directory. The domain URI shown in your web browser's address bar refers to the main web directory, not to the site owner's home directory.
The forward slash (/)
The forward slash fulfils the same role it does in a website URI: it shows the item after to be in a subdirectory or the directory before it. A forward slash on its own refers to the root directory, which is at the top of the file system.
Directory Name Character Rules and Spaces
A file or directory name can contain any standard character except a forward slash — including white spaces. However, when entering shell commands, you separate commands, parameters, and files with spaces. If you have a space in a file or directory name, you need to use a backslash in front of it or put quotation marks round the name. A directory called My Pictures would be entered as
"My Pictures"
or as
My\ Pictures


The * and ? Symbols: The * and ? symbols are called wildcards and can be used in any command which deals with files. The * represents any number of characters. The ? represents just one. Note that Linux filenames are case-sensitive — the norm is lowercase. All commands are lowercase.

Command Options: Commands usually accept options or parameters, which are given in a sequence beginning with a hyphen (-). If you would want to set options b, r and f for a command, type
command -brf
Other specifications, like file names, go after the options.

Shell Commands

Here's a brief introduction to some useful UNIX shell commands.

ls

This command displays a listing of a directory's contents. Unmodified, the command displays the contents of the current directory; you can also specify another directory's content to list. Some useful options are:

  • ls -l
If the list is long, you can display the list in pages. To do this, type
ls -l |less
(Note: The vertical bar | is also known as a UNIX pipe). The pipe bar means that the output from ls -l is submitted to the program less, which displays pages of whatever input it receives. You can press space to view the next page, or the arrow keys to go up and down.
  • ls -la
Includes hidden files (i.e. files that begin with a dot, like .htaccess)in the directory listing.
  • ls -l g*
Specifies any other directory or file group to list after the options, and in this example would list all the files beginning with g, while ls public_html would list the contents of public_html.

cd

The cd command changes the current directory. To switch from the current directory into a sub-directory, put the sub-directory's name after the command. To change into a sub-directory wp-content, you'd type

cd wp-content

To move up into the directory above the current directory, type

cd ..

To change from the current directory to your home directory, type

cd

mkdir

The mkdir command creates a new directory inside the current one. To create a directory named audio inside the current directory, type

mkdir audio

To remove an empty directory, type rmdir directoryname for example:

rmdir audio

If you want to create a directory, and one or more sub-directories within it, with a single command you can use the '-p' argument with the mkdir command.

For example, to create the directory 'maindir' and 3 sub-directories named 'sub1', 'sub2' and 'sub3' within it use the following command:

mkdir -p maindir/sub1 maindir/sub2 maindir/sub3

rm

The rm command deletes ('removes') a file, a group of files, or a directory. When using this command, use extreme caution, as once you remove the file there is no good or consistent way to recover it.

To remove a single file use:

rm filename

You can remove multiple files by naming them one after another on the line:

rm filename.php filename.html

You can also a group of files that have similar names with the use of a well place '*', and it will prompt you to type 'yes' to confirm each deletion:

rm filename*

To remove files without it prompting for confirmation, use the '-f' flag:

rm -f filename*

To remove an entire directory and its contents in one go, type:

rm -rf /path/to/directoryname. 

Beware — once something is removed in this way, it is gone forever.

exit

The exit command ends your shell session.

mv

The mv command moves files from one place to a another; it is also used to rename files. Type

mv file new-location

If the new-location parameter is a (valid) directory in the current filesystem, the file is moved into that directory; if it isn't (and if it doesn't clash with an existing filename), the file will be renamed as new-location. You can also move and rename a file with one command:

mv file ~/path/to/new-file-name

cp

The cp command copies files or directories. To copy a directory and its entire contents, use

cp -rf source-file destination

ln

The ln command creates links. The links relevant to our purposes are "symbolic links" or symlinks — files which "point" to other files or directories in the filesystem. When you access a symlink, you are actually accessing the original file. If you want to change the location of your WordPress directory from, say, /wordpress/ to /blog/, you could create a symlink as follows:

ln -s wordpress blog

Access will then be through either the file or directory's actual name — wordpress — or through the link name — blog. In the Options panel in the Wordpress Administration Panels, set the "Blog address (URI)" field to show the symlink rather than the name of the directory.

tar and unzip

The tar and unzip commands are used to compress and decompress "archive" files. Archives are files or folders that have been "compressed" — i.e. reduced in file-size — and are commonly used for distribution and backup purposes. The unzip command is used for files ending with .zip; the tar command is used for files ending with .tgz or .tar.gz.

Unzipping files: If the file is a .tar.gz archive, type
tar -zxvf file.tar.gz

If it's a zip archive, you may need to create a temporary directory into which you'd unzip its contents (its files might be unzipped into the current directory otherwise).

If the file is a .tar.bz2 (bzip2) archive, use the following command to extract its contents
 tar -xjvf file.tar.bz2 

chmod and file permissions

The chmod command changes the permissions on a given file. UNIX file permissions specify who can do what with a given file. The ls -l command will tell you what permissions a file or directory has:

 -rw-r--r--      1 domain60 vweb     840   Feb 21 06:38 wp-config-sample.php
 -rw-r--r--      1 domain60 vweb     826   Jun 29 20:31 wp-config.php
 drwxr-xr-x      4 domain60 vweb     4096  Jun 29 20:30 wp-content
 -rw-r--r--      1 domain60 vweb     762   Mar 29 16:05 wp-feed.php
 drwxr-xr-x      3 domain60 vweb     4096  Jun 29 18:46 wp-images
 drwxr-xr-x      2 domain60 vweb     4096  Jun 29 18:46 wp-includes

The permissions are displayed in the string of letters in the first column. The very first letter of that column indicates whether it is a file, a link, or a directory. A d denotes a directory, a l denotes a link, a hyphen denotes a file.

The permissions are declared with the following nine letters, which are shown in groups of three. The first group of three concerns the owner, the second the group he belongs to (this is unlikely to concern you as a web host user), and the third concerns everyone else. Note that people with root access (administrators) have access to all files on the system.

The letters r, w and x stand for read, write and execute; if the file is a directory, executable means traversible, that is, that you can move into that directory with the cd command. Where a hyphen is shown in the permissions list, the permission is absent.

You change permissions with the chmod command. You may, in fact, not have to change the permissions at all; some hosts automatically set certain permissions on any file in the web directory. Your host may also tell you what permissions need to be set on your server.

The chmod command can be used to set permissions in two ways: with letters or with numbers. If you use letters, you could type
chmod o+w filename

This grants write privileges to everyone with access to the system. The first letter can be u (user), g (group) or o (other), or a combination; the + (grant) can also be - (withhold), and the third can also be r or x (read or execute).

If you use numbers, all permissions for a file are set in one go. An example:

chmod 755 wp-images

sets the permssions of the wp-images directory to 755, whereby the first number (the "hundreds") is for the user, the second (the "tens") is for the group and the third (the "units") is for everyone else.

More about numerical permissions settings: To add 4 in any of the fields grants read privileges; to add 2 grants write and to add 1 grants executability; each combination has a unique number. The directories in the example above have the permission set 755, which is common for web-available directories, in which the user has full privileges while others have read and execute only; the files in the example have the permission set 644, in which the user can read and write while others can only read.

   6  4  4
  420400400
 -rw-r--r--  1 domain60 vweb  840  Feb 21 06:38 wp-config-sample.php

   7  5  5
  421401401
 drwxr-xr-x  2 domain60 vweb  4096 Jun 29 18:46 wp-includes

wget

The wget command downloads a file if you put a web location (URI) after it. To download the latest WordPress release type
wget http://wordpress.org/latest.tar.gz

GNU screen

The screen command allows you run multiple console-based applications with in a single Terminal session. If GNU screen is installed on your server, you can use the following command to start it:

screen

When screen starts, a welcome message should be displayed. Just press Return to get rid of this message and you should now see a shell prompt. This will be the first session window and is numbered 0. Each subsequent new session you open will be given a number, starting from 1 for the second session window.

To create a new session window press CTRL-a then C

To switch between currently open session windows press: CTRL-a followed by the number corresponing to the session window you want to access.

To get a list of all the session windows that are currently open press: CTRL-a

To exit screen altogether, stop all running programs and type exit at the shell prompts in all the session windows you have opened (including window '0'). screen will terminate when there are no more programs running in any open session windows.

Upgrading WordPress from the Shell

Let's use the example of upgrading WordPress using the command line. First, establish the location of your WordPress on your web server's filesystem. This example assumes it is located at ~/public_html/blog.

  1. Download the current version of WordPress to your shell account's home directory and unzip it:
    wget http://wordpress.org/latest.tar.gz
    tar -zxvf latest.tar.gz
    The WordPress archive will be unpacked into a new directory named /wordpress.
  2. Enter the new directory with the following command:
    cd wordpress
  3. Remove wp-config-sample.php:
    rm wp-config-sample.php
    (We will use our current wp-config.php instead)
  4. Remove the entire /wp-content directory from the new directory (we will replace it with the one from our WordPress blog directory):
    rm -rf wp-content
  5. Copy the blog's wp-config.php and .htaccess file to the new directory:
    cp ~/public_html/blog/wp-config.php .
    cp ~/public_html/blog/.htaccess .
    Note: Don't forget the dot at the end of both commands!
  6. Copy the wp-content directory to the new directory (it contains all our themes and plugins):
    cp -rf ~/public_html/blog/wp-content/ .
    Again, note the dot at the end of the command.
  7. Remove the entire contents of your WordPress blog directory:
    rm -rf ~/public_html/blog/*
  8. Finally, copy the entire contents of the new directory to your main blog directory:
    cp -rf * ~/public_html/blog

SFTP Shell Commands

SFTP stands for Secure File Transfer Protocol. It is an encrypted replacement for FTP, and as with FTP, you may use a shell-based client or one of the graphical clients mentioned at the top of this article. If your host supports SSH, it also supports SFTP.

Shell-identical commands

Shell-type SFTP clients support commands similar to those used in bash. These include cd, ls, mkdir, rm and rmdir. It also supports ln, with the difference that you do not need to use the -s option to create symlinks; in sftp, the ln command makes symlinks by default. All of these work on files on your host's system.

put and mput

These two commands transfer to your host (i.e. upload) a single file (put) or any files that match the pattern you supply (mput); the wildcards * and ? described above can be used here.

get and mget

These two commands transfer from your host to your local computer (i.e. download) a single file (get) or any files that match the supplied pattern (mget). As with mput, * and ? can be used.

cd, mkdir, ls

These commands are identical to their bash shell counterparts: change the current directory, make a new directory, and list the contents of the current directory. To do the same things within SFTP on your own machine, add an l to the front of the commands: lcd, lmkdir, lls.

See also

Changing File Permissions

htaccess for subdirectories

This article is marked as in need of editing. You can help Codex by editing it.