I’ll just write about two things that I’ve worked out recently.

Lesson #1: Read the README file.

Well duh, you say. The story is, I’ve had the bash_completion script for some time (a really useful extension that makes typing on the command line that much easier), but I’ve never quite worked out why it didn’t work. Now I know why. It’s because I naively assumed that the bash_completion.sh script was the meat of it, and simply called it from .bashrc, expecting it to just work. It would, ordinarily, but I don’t have it installed in /etc which is where it expects to be (it’s in my home directory). If you have somewhere else like me, you will need to set the $BASH_COMPLETION variable and modify the bash_completion.sh script to reflect where you’ve actually put it.

Lesson #2: If you didn’t set up the system yourself, things might not be as you expect them to be.

SUITS has a bunch of useful scripts that you can use to improve your command line experience on the undergraduate IT servers, and I copied them over to my account on nointrigue.com because I like them so much. One of these scripts sets nice colours for the command line. It was all working fine until I realised TortoiseSVN could no longer access the Subversion repositories via svn+ssh, failing with the error “connection closed unexpectedly”. I figured something I added recently was injecting garbage into the stream. It turns out it was the colour-adding script! But why? It was protected like this:

if [ -n "$PS1" ]; then
        . ~/.bash/colors
fi

That means that it should only have been run if it was running in an “interactive” terminal, and the colour-adding script should not have been called if I was using svn+ssh. After some more poking around, I found this in /etc/bashrc (which was being called from .bashrc):

# For some unknown reason bash refuses to inherit
# PS1 in some circumstances that I can't figure out.
# Putting PS1 here ensures that it gets loaded every time.

Uhh, ok, nice work, Bluehost. I guess not many of their customers actually use ssh. At least there was a comment.

But even if it was called, why the colour-adding script was failing in the first place? It turns out that tput colors fails if $TERM is not set, which happens to be so when using svn+ssh. (Actually, this would not normally prevent me from accessing my Subversion repositories. The command line svn seems to ignore errors; however, TortoiseSVN dies the moment it sees anything untoward.) My ultimate solution was to simply pipe error to /dev/null.

Getting started

Typically, you will have FTP access to your shared host, but not all shared hosts allow shell access to your server. To follow this tutorial, you will need to have shell (SSH) access to your host (which, by the way, I am assuming is a Linux box, which is the usual case). Even if your hosting package has this feature, you may have to file a support request to enable it, as is the case with Bluehost (see the SSH link in cPanel). (Actually, I lie. You can still do the installing software part, but it may prove far more difficult - see below for details.)

To connect to your server, you will need an SSH client on your computer. If you are using Mac OS X or some version of Linux, you will probably have OpenSSH installed already. If you are using Windows, you can either install Cygwin (make sure you select the OpenSSH package) or use PuTTY. If you don’t have a need for a Unix-like environment on your Windows machine, and you just want SSH, the latter is probably a simpler choice.

• If you are using OpenSSH, open up a command prompt or terminal, and type ssh username@yourdomain.com filling in the username and your domain name as required.
• If you are using PuTTY, run putty.exe, enter your host name and press Open.

For both, if you are prompted about storing the server’s fingerprint, just type or click yes.

You should now be presented with a shell prompt, where you can type in commands (which you issue by pressing Enter after typing them in). It may seem like a regression back to the 1980s days of MS-DOS, but it’s quite a convenient way of controlling a server that’s far away from you.

To avoid having to enter your password every time, you can use an SSH agent.

Getting to know your shell commands

This is not intended to be an exhaustive list of commands that you can type; instead, my aim is to write down a number of commands that inexperienced users can just quote verbatim to do what they need to do. Parts in italics are to be replaced as appropriate.

• cd directory: this is how you enter into a directory. Commands are always executed relative to the current directory. ~ is your home directory. Just type cd to return to your home directory.
• ls: display the contents of the current directory. Type la -la to make it display hidden files and detailed information about your files.
• mkdir directory: create a directory.
• rmdir directory: remove a directory. The directory must be empty.
• rm file: delete a file. Use rm * to delete all files in the current directory, or use rm -rf * to delete all files and subdirectories in the current directory (use with caution!).
• cp oldname newname: copy a file.
• mv oldname newname: move a file. This command is also used to rename files, since the act of renaming is just the same as moving. You can move a file up a directory by using mv file .., and a file into a subdirectory using mv file subdirectory.
• pwd: display the full path to the current directory.
• less file: view a file. Use the arrow keys or page up and page down to move around the document. Press q to exit.
• find -name wildcard: use this to search the current directory and its subdirectories for a file with a name that matches the wildcard expression.
• ln -s linkname filename: a symbolic link is like a shortcut that allows a file to appear in two different places - but both the existing name and the new link name refer to the same file.

To find out more about these commands, type man command, and press q to exit. If something screws up, pressing Ctrl+C should kill whatever command you’ve just issued.

Editing on the go

Another activity that I use SSH for quite a bit is editing configuration files directory on the server. That saves me having to download the file to my computer, making the changes, and then uploading it back up again. A good text-based editor is vim, and here are just a few commands to get you started.

• To start vim with a file open, use vim file.
• To move around, the arrow keys, home, end, page down and page up work as expected.
• To go into editing mode, press i, and then any keys that you press will be added to the document itself. To get out of this mode, press Esc.
• When you’re not in editing mode, you can issue commands to the editor. For example: :q to exit, :q! to exit without saving changes, :w to save, :wq to save then exit.
• That should be enough to edit a file, but if you want to know more, type :help and there are links to on-line tutorials.

Installing software on your shared host

If your server is a shared host, you can be pretty sure that you can’t install or modify the software installation on the server on a global level. You can, however, install additional software just for yourself in your home directory (which you can definitely write to!). If you don’t have SSH access to your server, you could try and recreate a similar environment to that on your server, compile the programs (using, perhaps, cross compilation), and then upload the resulting executables like you would normally — let me know if you can get that to work!

Why would you want to install additional software? There are plenty of reasons for that. For example, you might want to run Ruby scripts, but your host hasn’t updated the software installed since the dark ages. Alternatively, you might want to run software that isn’t typical for a shared web server; for example, I have Subversion (a version control system) and Privoxy (a proxy server) installed. I also have a LaTeX installation so I can get maths rendering in MediaWiki.

1. Create a directory for downloading and compiling files: I call mine src, and it’s a subdirectory of my home directory ~. This is useful in case you make a mess; that way, you can use rm -rf * (see above) to obliterate everything in that directory and start again.
2. Download the source files: you will need to download the source files, and create the executable (binary file) yourself, instead of downloading the compiled executable. This will ensure that there are no problems installing or using the program. Open source projects will have the source code available. To download something to the current directory, use wget url.
3. Unpack the source files: typically, the source file will have one of several extensions. If it ends in .tgz or .tar.gz, use tar -xzvf file. If it ends in .bz2, use tar -xjvf file. If it ends in .zip, use unzip file.
4. Read the installation instructions: there’s often a README or INSTALL file amongst the files that were unpacked. Read it using less (see above).
5. Compile it: if there are installation instructions, follow those. However, if there’s a part where it asks you type in ./configure (which is almost always), then you should type ./configure --prefix=$HOME instead. This will make sure that your software is installed in your home directory. If there are no installation instructions, a typical sequence of commands is: ./configure --prefix=$HOME, make, make install.
6. Test it out: your program will probably have been installed into ~/bin ~/sbin, where ~ is your home directory. Now, you’ll notice that you can only type the name of the program when your current directory (which you change using cd) is the directory where that executable resides. In order for the shell to find your newly installed program, regardless of what directory it resides in, you’ll need to add it to your PATH environment variable. To do this, you need to add a line to the .bashrc file that resides in your home directory (create one if it doesn’t exist). For example, my line looks like this: export PATH=$PATH:~/bin:~/bin/tetex, and that means that I’ve added ~/bin and ~/bin/tetex to the locations where the shell will search for programs; note the use of the colon to separate paths.

That’s all for now folks! I hope the instructions are clear, and that your days of being a webmaster are more productive than before. If you want to learn more, Google is your friend.