RSH Web Services Virtual Private Server's (VPS)

A Tour of the Virtual Private Server System
pg. 4

• The Virtual Private Server File System
• Your Home Directory
• Introduction to UNIX
• UNIX Commands Introduced in this chapter
• Entering UNIX Commands
• Learning More About UNIX Commands
• Basic Unix Tutorial
• A Tour of Your Virtual Private Server’s Directories
• Getting to Your Home Directory
• Other Directories
• Navigating the Virtual Private Server File Structure with Pilot
• Starting Pilot Automatically at Login

The Virtual Private Server File System
Any computer system is simply a collection of files. A file system is the method in which these files are organized. Your Virtual Private Server’s file system is organized into what is called a tree format. The branches of this "tree" are called directories. All the files on your Virtual Private Server reside in a directory, and any directory can contain both files and other directories. A directory that resides inside another directory is called a subdirectory. The directory that contains a subdirectory is called a parent directory. The directory tree starts at the root, which is the lowest possible level in the directory tree and can branch out into subdirectories, which can branch out and contain other subdirectories, which can contain other subdirectories, and so on. The relationship between the root and any directory on the system is called the path, because that relationship shows the path you take to that directory from the root. Paths are displayed with an initial slash (/) to denote the root, and subdirectories are shown separated by additional slashes.

Your Home Directory
When you first log into your Virtual Private Server, you are placed in what is called your home directory. This is the directory on the system that contains all the files and subdirectories that pertain to you and your Virtual Private Server. The path to your home directory is:

/usr/home/username

Except that the username is actually the username you used to log into your Virtual Private Server. You can understand the path to your home directory by seeing that by starting at the root, then branching off into the directory called "usr," then branching off into the directory called "home," you arrive at your very own home directory.

In your home directory, you "own," or have permission to access, any of the directories and files contained in or below this directory, with the exception of a few system files that you do not have the ability to edit or delete. The directories located above your home directory belong either to your "virtual neighbors" or to the dedicated server system. You cannot access any of these directories, with the exception of the /usr/home/contrib directory, which contains a library of useful add-ons to your Virtual Private Server. This directory will be discussed later in this guide.

Because we will be referring to your home directory so often in this guide, we will use the tilde character (~) (pronounced TILL-dee) to refer to your home directory. You should use the ~ interchangeably with /usr/home/username. For example, when we refer to the ~/bin directory, we are actually referring to the directory named "bin" that is a subdirectory of your home directory. In other words, /usr/home/username/bin.

Introduction to UNIX
UNIX is the operating system that runs your Virtual Private Server. Think of it as the language that your Virtual Private Server understands. Once you’re connected and logged into your Virtual Private Server, you should take some time to familiarize yourself with some of these basic UNIX commands. If you are already familiar with them, you may choose to skip ahead to the next section of this guide.

UNIX Commands Introduced in this chapter
man: A type of UNIX help system that displays a manual page about a specified command.
pwd: Short for Print Working Directory. Displays the path to the current directory.
ls (list): Displays a list of the files and directories in the current directory.
ll (long list): Displays a “long listing” of files, directories, permissions and file size in the current directory. Similar to the DOS command DIR.
grep: Searches documents or directories for a specific word, phrase, or file.
cd (change directory): Used to move to a different directory. If no directory is specified, it will take you to your home directory.
mkdir (make directory): Creates a new directory.
mv: Moves a file into another directory, or renames a file by “moving” an existing file to a new file with a new name.
rm (remove): Removes a file or directory.
cp (copy): Copies a file or directory.
touch: Creates a new, empty file or updates the date that an existing file was last modified.
more: Displays the contents of a text file. If the contents of the file are larger than your screen, it will wait for you to ask for more by pressing the space bar.
pico: Starts the PICO online text editor.

Entering UNIX Commands
UNIX commands are issued at the command prompt. Some commands require a special argument, with a dash (-) before the argument. If you are using a command that has an argument, be sure to insert a space between the command and the dash.
After you enter a command, your Virtual Private Server will attempt to execute the command, display any results of the command, and then display a new command prompt.

Learning More About UNIX Commands
For more information about any UNIX command, type man at the command prompt , followed by the command you wish to know about. For example, to learn more about the mkdir command, you would type:
man mkdir Enter
In this example, a page of technical information (called a man page) would appear that explains how to use the mkdir command. If there is more information than will fit on your screen, you will see a display at the bottom of the page showing the percentage of the manual that is being displayed. Press the space bar to continue reading the rest of the available information. When you reach the end of the file, the command prompt returns. A portion of this example man page might look something like this:

Man pages serve as a valuable resource and are available for most UNIX commands.

Basic Unix Tutorial
Part 1 – Finding Your Bearings
This section introduces some useful commands that you can use whenever you’re unsure of your whereabouts, or if you want to know what files or directories are available from your current location.
The pwd command
Use the pwd command to display the full path of the directory you are currently in.
Example: After logging into your Virtual Private Server, type:
pwd Enter
You will see a display with the following format, where username is the username of your Virtual Private Server:
/usr/home/username
You can use the pwd command at any time to display the directory that you are currently in.
The ls command
Use the ls command to view the files and directories contained within your current directory.
Example: At the command prompt, type:
ls Enter
A list of files and subdirectories appears similar to the following:
bin dev etc ftp shlib tmp usr var www
From this view, it is impossible to tell which are files and which are directories. If you would like a more detailed listing, use the ll command as described below.
The ll command
The ll command displays a “long list” of files and subdirectories within the current directory, including file permissions, file ownership, file sizes (in bytes), and the date each file or directory was created or last modified. ll is technically not a command, but an alias to ls –al. The ll “command” is similar to the DOS command DIR.
Example: At the command prompt, type:
ll Enter

A list of files and subdirectories appears, similar to the following:
-rw-r--r--  1 user vuser   2790 Oct 22 10:39 .README
drwxr-xr-x  2 user vuser  512 Oct 22 10:39 .Xincludes
-rw-r--r--  1 user vuser  635 Oct 22 10:39 .Xmodmap
-rw-r--r--  1 user vuser  624 Oct 22 10:39 .Xmodmap.USKBD
-rw-r--r--  1 user vuser  845 Oct 22 10:39 .Xresources
-rw-------  1 user vuser  1390 Jul 29 1997 .cshrc
-rw-r--r--  1 user vuser  4852 Oct 22 10:39 .exmh-defaults
-rw-r--r--  1 user vuser  1951 Oct 22 10:39 .fvwmfmgr
-rw-r--r--  1 user vuser 19704 Oct 22 10:39 .fvwmrc
-rw-------  1 user vuser   57 Jun 10 1997 .inputrc.locale
-rw-------  1 user vuser  258 Jun 10 1997 .login
-rw-------  1 user vuser   52 Jun 10 1997 .login.locale
-rw-------  1 user vuser   20 Jun 10 1997 .logout
-rw-------  1 user vuser  176 Jun 10 1997 .mailrc
-rw-r--r--  1 user vuser   54 Oct 22 10:39 .mh_profile
drwxr-xr-x  3 user vuser  512 Oct 22 10:39 .netscape
-rw-------  1 user vuser  2052 Jun 10 1997 .profile
-rw-------  1 user vuser   52 Jun 10 1997 .profile.locale
Notice that in this view of the same directory, files that start with a dot (.) also appear. These files are typically necessary system files and they are not shown with the ls command.
Take a look at the first (far-left) column of this output. Note that each line begins with one of 3 characters: a ‘d’, an ‘l’, or a dash (-). A dash denotes a file; ‘d’ stands for directory; and ‘l’ refers to link.
The file and directory names appear in the last (far-right) column.
Part 2 – Creating and Navigating Files and Directories
To learn how to create, move, and delete files and directories, follow the procedures in this section in the order they’re presented. You will need to know how to use these commands to complete Part 3, which follows.
The mkdir command
You can create your own directories with the mkdir command.
Example: At the command prompt , type:
mkdir tour Enter
You have just created a directory called “tour.”
Use the ls command to verify that the directory has been created:
ls Enter
Note that the tour directory has been added to the list.
The cd command
To work within a directory, you must first move into that directory using the cd command.
Example: To check out the “tour” directory you just created, type:
cd tour Enter
You are now in the ~/tour directory. To verify this, type:
pwd Enter
The full path is displayed as /usr/home/username/tour.
Here are some other features of the cd command worth noting:
If you don’t specify a directory (i.e., if you type cd Enter
), you will automatically be taken to your home directory.
The tilde symbol (~) can be used to indicate your home directory. Therefore, “cd ~” means “take me home.” Likewise, “cd ~/etc” means “take me to the etc directory that is located inside of my home directory.”
You can use “..” to represent the parent directory of the directory you are currently in, so that “cd ..” means “take me up one directory.” Likewise, “cd ../test” means “take me to the directory called test, which is in the same parent directory of my current location.”
Searching for words with the grep command
The grep command can be used to search text files for occurrences of a word or phrase.
Example: To search your ~/www/htdocs/index.html file for occurrences of the word ‘web,’ type:
grep ‘web’ ~/www/htdocs/index.html Enter
The output displays all of the lines that contain the word ‘web’ within the file
Part 3 – Editing and Deleting Files and Directories
The pico command
Although empty files are sometimes useful, in most cases you will want your files to contain some text. To add text to a file, you can use pico, an online editor. Pico is a simple text editor that you’re likely to use very often. In fact, it’s the program you will probably use most often as the Virtual Private Server administrator.
Example: Add text to a file called “hello” by typing the following at the command prompt:
pico hello Enter
The pico editor opens the empty hello file, and your screen looks something like the following:

Because the file is empty, the editing screen will look blank. While in the editor, type:
This is my first file. Look at me!
Now press Enter twice. UNIX tends to behave better when it sees a few blank lines (also called hard returns) at the end of a text file. Remembering this will help prevent a few common problems that many users have.
To save the new contents of this file, press Ctrl+X. Pico will ask if you would like to save the contents of the file. Press Y to do so. Finally, pico will ask you what to name the saved file (File Name to write). By default, pico suggests you keep the same filename, so simply press Enter to accept.
While using pico, there are several key combinations that will help you view or edit a file. Some useful key combinations, along with their definitions, are:
Ctrl+G Take the pico tutorial
Ctrl+V View next page
Ctrl+Y View previous page
Ctrl+A Go to the beginning of a line
Ctrl+E Go to the end of a line
Ctrl+C Display the line number that you are currently on
Ctrl+W Search for a word or phrase
Ctrl+O Save (write-out) the file
Ctrl+X Exit the pico editor
We encourage you to learn more about pico by pressing Ctrl+G from within the pico program itself, or by typing the following from your command prompt:
man pico Enter
The more command
The more command displays the contents of a text file. If the contents of the file are larger than your screen, you “ask for more” by pressing the space bar when you are ready, or quit by pressing Ctrl+C.
Example: Use the more command to verify that the new text you entered with pico is now saved inside your “hello” file:
more hello Enter
The input you typed appears:
This is my first file. Look at me!
The cp command
The cp command is used to copy one file to another. The format of the cp command is
cp source target
where the source is the original file and the target is the name of the new file.
Example: Make a copy of your hello file and name the copy “hello2.”
cp hello hello2 Enter
To verify that the file was copied successfully, type:
ls Enter
There is now a hello2 file in addition to the hello file. To verify that the contents of the hello file have been copied to hello2, type:
more hello2 Enter
Again, the input you typed appears.
The mv command
The mv command can be used to either move a file into another directory, or to rename a file (by “moving” an existing file to a new file with a new name).
Example 1: To rename the hello file as “hello3,” type:
mv hello hello3 Enter
ls Enter
The hello2 and hello3 files appear, but the original hello file is missing. The hello file hasn’t really disappeared; it’s been renamed as hello3.
Example 2: Create a new directory called subtour1 and move the hello2 file into it:
mkdir subtour1 Enter
You’ve just created a directory called subtour1. Now type:
mv hello2 subtour1 Enter
To verify that the hello2 file has been moved into the new subtour1 directory, type:
cd subtour1 Enter
ls Enter
The hello2 file is now in the new subtour1 directory.
Removing a file using the rm command
You can remove files with the rm command.
Example: To remove the hello2 file from the subtour1 directory, first make sure you’re in the subtour1 directory, then type:
rm hello2 Enter
You will be asked if you really want to delete the file. Press Y, Enter
to accept. You can verify the file has been deleted by typing:
ls Enter
Because the directory is now empty, the command prompt returns immediately.
Removing a directory using the rm -r command
Using the –r option with the rm command allows you to delete directories as well as files. Be very careful when using the -r option with the rm command. Used incorrectly, this command can cause a lot of damage, and can even stop your Virtual Private Server system from operating altogether.
Example 1: Delete the ~/tour/subtour1 directory.
First, type the following to ensure you’re in the ~/tour directory, which is the parent directory of subtour1:
cd ~/tour Enter
The rm command alone will NOT remove a directory. To prove this, type:
rm subtour1 Enter
The following error message appears:
rm: subtour1 is a directory
To prevent you from deleting an entire directory by accident, the rm command requires an additional flag, or command line option, to verify that you really want to remove the directory. Now, try removing the subtour1 directory using the –r flag:
rm -r subtour1 Enter
In the preceding command line, the –r option tells the rm command to recurse –in other words, to not only remove the specified directory, but to also remove all files and/or subdirectories that the subtour1 directory contains.
You’ll now be asked to confirm that you really want to delete the directory and each file contained within it. Press Y, Enter to confirm.
To verify that the directory was deleted, type:
ls Enter
The subtour1 directory is now gone.
Example 2: Remove the entire ~/tour directory.
Type the following at the command prompt:
rm –r ~/tour Enter
Once you confirm that you want to delete the contents, all the directories and files you created for this tutorial will be removed.

A Tour of Your Virtual Private Server’s Directories
Now that you’re armed with a few of the more useful UNIX commands, let’s take a look around at the various directories and files that make your Virtual Private Server work.
We will start in your home directory. This guide will refer to your home directory as ‘~’. Recall that the full path to this directory is /usr/home/username, where username is the same username that you login to your Virtual Private Server with.

Getting to Your Home Directory
You can get to your home directory by typing cd /usr/home/username, but there are a couple of shortcuts. You can use the ~ key to specify your home directory in many UNIX commands. Doing so will save you a lot of typing:
cd ~Enter
Or, you could simply use the cd command without specifying any directory:
cd Enter
If you don’t specify which directory you want to change to, your Virtual Private Server assumes that you want to “go home,” so that’s exactly where it will put you–into your home directory.
To verify that you are back in your home directory, type:
pwd Enter
You should see that you are in fact in the /usr/home/username directory. Recall that throughout this guide, we will use the ~ symbol to represent this directory. Remember also that whenever you are lost and want to verify the full path of the directory that you are in, you can use the pwd command.
As we stated earlier, you have access to the files and directories in and below your home directory in the directory tree, but not to the files and directories located above this directory. That is because they belong to either your “virtual neighbors” or to the server itself.
To view all the files and subdirectories within your home directory, use the “long list” command:
ll Enter
Note that some of the items in first (far-left) column begin with a “d,” and some just have a dash (-). Those that start with a “d” are directories; those that start with a dash are files. Some lines start with an “l,” which indicates a link or shortcut to another file.

Other Directories
The etc directory

The ~/etc directory (pronounced "ET-see") contains configuration and data files that control how your Virtual Private Server operates. The most notable item inside the ~/etc directory is the ~/etc/mail directory, which contains the files that control your Virtual Private Server's mail services.
From your home directory, type the following at the command prompt:
cd etc/mail
You are now in the etc/mail subdirectory of your Virtual Private Server.
Use the ls command to view the files within the ~/etc/mail directory:
ls
The most noteworthy files in this directory are:
aliases: This file controls where various email addresses point to.
virtmaps: Similar to aliases, but used when you have more than one domain name on your Virtual Private Server.
catchall: This file contains the catchall address for your Virtual Private Server, if any.
access: This file enables you to allow or deny access to your mail server. You can create a blacklist of known spammers or allow trusted users to relay email through your mail server.
sendmail.cw: Contains a list of domain names that you wish to be able to provide email service for on your Virtual Private Server. This only works if you have contacted the Virtual Private Servers DNS department and requested that the domain name be properly pointed to your Virtual Private Server’s IP address.
sendmail.cf: A very important file that allows your Virtual Private Server to handle email. Unless you are a UNIX expert who is extremely fluent in sendmail gibberish, you should not attempt to modify this file. Doing so can cause serious problems with your email service.
The ftp directory
The ~/ftp directory is a subdirectory of your home directory, so you'll need to go back to your home directory, then change into the ftp directory. You could do this by typing the following:
cd .. Enter
cd ftp Enter
There is, however, a more direct way to accomplish this. You can show the cd command which path you want by simply typing:
cd ../ftp Enter
Remember that the '..' takes you back up one directory level, and then the /ftp places you in the ftp subdirectory. Verify that you're now in the ~/ftp directory by typing:
pwd Enter
The ~/ftp directory is referred to as your FTP Root Directory because it houses the directories for both user-authenticated and anonymous FTP access. Anonymous FTP service is only available on the Virtual Private Server Pro. For the Virtual Private Server Mini this directory serves no purpose.
As far as the FTP service is concerned, this directory is where everything starts. Anyone who logs on to your Virtual Private Server's anonymous FTP service will have read access to this directory, and all of the files and directories that it contains, by accessing ftp://ftp.yourdomain.com, where yourdomain.com is the domain name of your Virtual Private Server. Read access means that they can see the files and their contents. They can't modify or delete the files, but they can see them, access them, and download a copy of them. They cannot access anything above this directory, nor can they write to or send anything to these directories unless you specifically allow them to.
In your FTP root directory, type:
ls Enter
Note the directory called pub. This is commonly referred to as your public FTP directory. It's common practice on the Internet to place all the files that you want anonymous FTP users to be able to access within this directory or one of its subdirectories. For more information about FTP, please see the FTP chapter of this guide.
The usr directory
To visit the ~/usr (pronounced "user") directory, type:
cd ~/usr Enter
Although the ~/usr directory itself doesn't contain any noteworthy files, it does contain subdirectories that contain many important files. The most important subdirectories of the ~/usr directory are:
bin: This directory contains many of the commands that you use on your Virtual Private Server. Because of the way your Virtual Private Server is configured, these commands are accessible from any directory. For example, the files ls and pwd are actually stored in this directory, but you can use them from any directory on your Virtual Private Server. You should never need to change any of the files in this directory, and it's a very good idea not to try.
log: This directory contains an important file, called xferlog. The xferlog file contains a record of all the FTP activity that takes place on your Virtual Private Server.
spool: This directory contains a subdirectory called mqueue, which stores any mail that is waiting to be sent from your Virtual Private Server. Because mail is usually sent immediately, this directory will be empty most of the time. However, if there is a temporary delivery problem, mail may queue up here for later delivery.
home: This directory contains files for email and FTP users that you add to your Virtual Private Server. In some cases, a directory will be created in here with the user's name and will act as that user's home directory.
mail: This directory contains stored email messages for your Administrative Email Account, and for any POP users you have added to your Virtual Private Server.
The www directory
The ~/www directory is technically not a true directory, but a symbolic link. A symbolic link is actually a shortcut that points to a directory on your Virtual Private Server. Symbolic links make access to certain directories easier. They are commonly used as shortcuts to directories with long paths. In the long directory view (ll), symbolic links have an "l" on the far left side of their listing. Type:
cd Enter
This will place you in your home directory. Now type:
Il Enter
You should see the www "directory," denoted as a symbolic link by the "l." Now type:
cd www Enter
pwd Enter
You may see something other than what you expected. You should be in the ~/usr/local/etc/httpd directory (/usr/home/username/usr/local/etc/httpd). Since this directory has such a long name and is used so often, we've created the symbolic link www for you in your home directory that links to it. This directory is known as the Web Root because as far as your Virtual Private Server's Web service is concerned, this is where everything starts.
The Web root contains several important directories of its own. To see them, type:
ls Enter
Note the following directories:
htdocs: This directory, also known as the Document Root, houses your Web pages, graphics, and any other files you want available for public view through a Web browser. You can create any number of subdirectories within the htdocs directory. Those who access your Virtual Private Server with a Web browser will have read access to the htdocs directory, and to every file and subdirectory that it contains. However, nobody has the ability to write to or change any of these files unless you specifically configure your server to allow them to do so. You can configure your Virtual Private Server to restrict access to certain subdirectories of your document root. This process is discussed in a later chapter.
cgi-bin: Contains executable binary files and script files that can interact with Web visitors through their Web browser. These programs are commonly referred to as CGI programs. CGI stands for "Common Gateway Interface."
logs: Contains records of all the Web activity that occurs on your Virtual Private Server.
conf: This very important directory contains the main configuration files for your Virtual Private Server's Web service. The files located in this directory will be briefly discussed on the last stop of this tour, and discussed in great detail in a later chapter.
The logs directory
The ~/www/logs directory stores logs of your Virtual Private Server's Web activity. You can get there by typing:
cd ~/www/logs Enter
There are four files in this directory, each of which tracks different information about your Web service. These files are:
access_log: Contains information about the files accessed through your Virtual Private Server's Web service. Any time someone views anything on your Virtual Private Server through a Web browser, information about it gets recorded in this file.
agent_log: Contains information about what types of Web browsers your Web visitors are using, such as the browser's type, version number, operating system, and so on.
referer_log: Contains information about what your Web visitors were viewing just before coming to your site. This is often useful to track the effectiveness of Internet advertising and for locating Internet sites that have links to a file on your Virtual Private Server.
error_log: Contains information about any errors that have occurred with your Web service. Errors are usually the result of someone looking for a file that does not exist on your Virtual Private Server.
The conf directory
The ~/www/conf directory houses the main configuration files for your Virtual Private Server's Web service. Although you will need to edit these files from time to time for various reasons, you should do so very carefully, and should always create a backup copy using the cp command before you edit any file. If you were to accidentally corrupt one of the files in this directory, your Virtual Private Server's Web service could function incorrectly, or stop altogether.
To get to the ~/www/conf directory, type the following:
cd ~/www/conf Enter
Some of the files contained in this directory are:
httpd.conf: The main configuration file for your Virtual Private Server's Web service. This is the configuration file that is modified most often. You can edit it to configure your Virtual Private Server's Virtual Hosting capabilities, to modify the way your log files are managed, and to configure many other advanced features.
srm.conf: Contains important configuration data concerning Web directories and file names. One part of this file that you may want to modify is a section that allows you to specify custom error pages for you Virtual Private Server's Web service. This feature is discussed in a later section.
access.conf: Defines the general access settings for your Virtual Private Server. This file determines who is able to access your Virtual Private Server and what visitors are able to do in certain directories. You can edit this file in order to restrict access to specific directories of your document root to specific people, groups, and passwords.
mime.types: Defines the media types for your Virtual Private Server. You may edit this file to add new file types to your Virtual Private Server as new multimedia extensions become standardized.

Navigating the Virtual Private Server File Structure with Pilot
Pilot is a simple file navigation program that allows you to view your Virtual Private Server’s file structure, display and edit files, and even run programs - all by using your arrow keys and a few other keyboard shortcuts. Try out the pilot command by typing the following from your command prompt:
pilot Enter
You should see a screen similar to the following:

Pilot displays the current working directory at the top of the screen, and also shows the directory’s contents and file sizes.
The parent of the current working directory is indicated by the file name “..”. File names that are symbolic links to other files are displayed with a file size of “--”.
Several basic file manipulation commands are provided: Delete, Rename, Copy, View, Launch, and Edit. The View and Edit commands will operate only on text files. By default, the View command uses whatever program is set in your PAGER environment variable to display the file (by default, the more command). The Edit command opens the file in the pico online editor, (or in whatever editor is set in your EDITOR environment variable). The Launch command provides a convenient way to execute the selected file or a command.
You can run pilot with a few different command line options. Here is a list of command line options that can be used with pilot:

Additional information on pilot is available by typing the following from your command prompt:
man pilot Enter

Starting Pilot Automatically at Login
You may like using pilot so much that you would like to launch it automatically when you first log in. This can be done by editing the file that contains your Virtual Private Server's login script. This file is called .cshrc, and is found in your home directory. To launch the pilot program automatically upon logging in, you could add the following line to the bottom of your ~/.cshrc file:
pilot
You can add whatever command line options you like. For example, this line could read "pilot –a" or "pilot –za." Additionally, you may want to comment out the line in the ~/.cshrc file that says:
setenv PAGER more
by placing a # in front of it like this:
#setenv PAGER more
Doing this will cause pilot to use the pine viewer to view files rather than the more command.