Manually Configuring Virtual Subhosts

In order to manually configure a Virtual Subhost, connect to your Virtual Private Server via SSH or Telnet and do the following.

1. For each Virtual Subhost you configure on your Virtual Private Server you will need to create a new directory for the Virtual Subhost domain files. To ensure compatibility with Microsoft FrontPage) you will need to create the new directory in your server's ~/www/vhosts directory.

   % mkdir -p ~/usr/local/etc/httpd/vhosts/subhost-domain

   % mkdir -p ~/usr/local/etc/httpd/vhosts/subhost-domain/htdocs

2. Open up your web server configuration file (~/www/conf/httpd.conf) and add the following lines in the <VirtualHost> section of the file (again, to ensure compatibility with Microsoft FrontPage). If your server was set up with just one web server configuration file (httpd.conf), then the <VirtualHost> section is found in the middle of the file. If your server was set up with three separate configuration files (httpd.conf, srm.conf, and access.conf), then the <VirtualHost> section is found at the bottom of the file.

   # point www.SUBHOST-DOMAIN.NAME and SUBHOST-DOMAIN.NAME 
   # to subdirectory subhost-domain
   <VirtualHost www.SUBHOST-DOMAIN.NAME SUBHOST-DOMAIN.NAME>
     ServerName www.SUBHOST-DOMAIN.NAME
     ServerAdmin webmaster@SUBHOST-DOMAIN.NAME
     DocumentRoot /usr/local/etc/httpd/vhosts/subhost-domain/htdocs/
   </VirtualHost>

   You must substitute the Virtual Subhost domain name in place of SUBHOST-DOMAIN.NAME and the name of the directory you created for the Virtual Subhost for subhost-domain above. Also be sure that the first domain name you list in the <VirtualHost...> directive above matches the domain name you specify as the ServerName (once again, to ensure compatibility with Microsoft FrontPage).

   NOTE: If the NameVirtualHost directive is not already in your web server configuration file (~/www/conf/httpd.conf), you will need to add it if you add any Virtual Subhosts. NameVirtualHost YOUR.IP.ADD.RESS:*

3. Many of your Virtual Subhost customers will want to install their own CGIs into their own cgi-bin directory. If you choose to provide this feature, first you must create a cgi-bin directory for the Virtual Subhost.

   mkdir ~/usr/local/etc/httpd/vhosts/subhost-domain/cgi-bin

   Then, use the ScriptAlias directive in the ~/www/conf/httpd.conf file on your Virtual Private Server (or possibly the ~/www/conf/srm.conf file)

   # point www.SUBHOST-DOMAIN.NAME and SUBHOST-DOMAIN.NAME 
   # to subdirectory subhost-domain
   <VirtualHost www.SUBHOST-DOMAIN.NAME SUBHOST-DOMAIN.NAME>
     ServerName www.SUBHOST-DOMAIN.NAME
     ServerAdmin webmaster@SUBHOST-DOMAIN.NAME
     DocumentRoot /usr/local/etc/httpd/vhosts/subhost-domain/htdocs/
     ScriptAlias /cgi-bin/ /usr/local/etc/httpd/vhosts/subhost-domain/cgi-bin/
   </VirtualHost>

   NOTE: It is important to understand the Virtual Subhosting Security Issues involved when giving cgi-bin access to your Virtual Subhost customers. Giving your Virtual Subhost customers cgi-bin access is a potential security risk! The CGIs your customers upload and execute have all of the rights and privileges of the CGIs you execute. Therefore, it is possible for a Virtual Subhost customer, which has been granted CGI privileges, to read or remove any file in your directory hierarchy. Moreover, it is possible for a malicious Virtual Subhost customer to crack weak passwords and gain shell access to your Virtual Private Server.

4. Many of your Virtual Subhost customers will want their own separate web server log files. If you choose to provide this feature, first you must create a logs directory for the Virtual Subhost web server log files.

   % mkdir ~/usr/local/etc/httpd/vhosts/subhost-domain/logs

   Then, use the TransferLog and ErrorLog directives to configure the web server log files in your ~/www/conf/httpd.conf.

   # point www.SUBHOST-DOMAIN.NAME and SUBHOST-DOMAIN.NAME 
   # to subdirectory subhost-domain
   <VirtualHost www.SUBHOST-DOMAIN.NAME SUBHOST-DOMAIN.NAME>
     ServerName www.SUBHOST-DOMAIN.NAME
     ServerAdmin webmaster@SUBHOST-DOMAIN.NAME
     DocumentRoot /usr/local/etc/httpd/vhosts/subhost-domain/htdocs/
     TransferLog /usr/local/etc/httpd/vhosts/subhost-domain/logs/access_log
     ErrorLog /usr/local/etc/httpd/vhosts/subhost-domain/logs/error_log
   </VirtualHost>

5. Most Apache Web Server resource directives can be included in your <VirtualHost> definition. For example, we can include the ErrorDocument directive in order to define a Error 404: File Not Found page for the Virtual Subhost.

   # point www.SUBHOST-DOMAIN.NAME and SUBHOST-DOMAIN.NAME 
   # to subdirectory subhost-domain
   <VirtualHost www.SUBHOST-DOMAIN.NAME SUBHOST-DOMAIN.NAME>
     ServerName www.SUBHOST-DOMAIN.NAME
     ServerAdmin webmaster@SUBHOST-DOMAIN.NAME
     DocumentRoot /usr/local/etc/httpd/vhosts/subhost-domain/htdocs/
     ErrorDocument 404 /notfound.html
   </VirtualHost>

   The File Not Found location is specified with respect to the DocumentRoot. So, in the example above, the actual file location of notfound.html is:

   ~/usr/local/etc/httpd/vhosts/subhost-domain/htdocs/notfound.html

6. Finally, your Virtual Subhost customer will probably want a file upload account, in order to upload their own web site to the Virtual Subhost directory. Use the vadduser command to create Virtual Private Server FTP User Accounts for your Virtual Subhost customers. When prompted for the account home directory, you will want to specify it to give them access to their DocumentRoot. For example, you may want to set the home directory as follows.

   /usr/local/etc/httpd/vhosts/subhost-domain

7. For more details about Virtual Subhosts and e-mail, see the following.

   • Virtmaps - Providing E-Mail for Virtual Subhosts