Apache virtual host configuration on dedicated servers

This document will discuss the steps required to configure web hosting on an Anchor dedicated server. This guide assumes that all DNS records have already been set to point towards the dedicated server.

Overview

Website changes must be done as the 'root' user. When the dedicated server was configured you would have been givin access to an account with sudo access. The idea being, you log in with your usual account and when you require the additional access level you can escalate your permissions using the following command:

         sudo su - 

Process

All our Linux dedicated servers run Apache 2 as the web server. The configuration files are kept within the following location on the server:

        /etc/httpd/conf/users/ 

By convention, all the configuration is broken up on a per user basis. This means, that when a new website is added to the dedicated server, there are essentially two steps which must be completed in each occasion:

1. Create the new user account

The username will be a unique name that will be used to access the account. When creating a username it is good practice to pick a username around 8 characters long that will closely match the primary domain name.

The following command will create the account:

         useradd -g users USERNAME 

Replacing the USERNAME section with the username you would like to use.

Once this has been done you will be need to set a password for the account using the following command:

        passwd USERNAME 

Most servers have an additional layer of security via the use of a the pam_access module. This is defined in /etc/pam.d/sshd and /etc/pam.d/vsftpd to control access to SSH and FTP respectively.

        account    required     pam_access.so accessfile=/etc/security/ssh_users

        account    required     pam_access.so accessfile=/etc/security/ftp_users

To then allow login, you add an appropriate entry to /etc/security/ssh_users and/or /etc/security/ftp_users.

        # This is in the form of three colon-separated fields. The first is a + or - symbol to indicate allow/deny.
        # The second is the username. The last governs what address/es the user may login from
        +:NEW_USERNAME:ALL

        # Rules are evaluated from top to bottom, the first match wins
        # You end with a clause to deny-all, for security
        -:ALL:ALL

The final step is to allow apache access to the website files (which will be stored in /home/USERNAME/public_html/). This is done using:

         chmod o+x /home/USERNAME

2. Configure web server to work with new hosting account

Once this has been done you will need to configure apache, the web server to work with this new site.

This can be done using the following method:

  • Change to the directory where the configuration is contained using:

        cd /etc/httpd/conf/users
  • There is a configuration template which is stored at:

         /etc/httpd/conf/templates/user.conf 

We can copy this into place using a command similar to the following:

        cp /etc/httpd/conf/user.conf USERNAME.conf 
  • Or

        cp ../user.conf USERNAME.conf 

Remember to replace the USERNAME section with the name of the user that you used in part 1.

  • Once this has been done the configuration will need to be edited. This can be done in any standard text editor, such as vi. To edit the file within vi the following command can be used:

             vi USERNAME.conf 
  • The editor vi is an extremly powerful and flexible text editor. As such, providing a full guide to using the entire feature set is outside the scope of this document. There are however many, many great guides on using vi which can be found online, see: http://www.google.com.au/search?q=vi+tutorial for more information on general vi usage. Once the file is opened you will be presented with a screen similar to the following:

# -*- apache -*- vim: syntax=apache
# %s,DOMAIN,X,g
# %s,USER,Y,g
# Please contact Anchor Support before editing this file.
<VirtualHost *>
        ServerName DOMAIN:80
        ServerAlias www.DOMAIN
        ServerAlias DOMAIN.tmp.anchor.net.au
        ServerAlias www.DOMAIN.tmp.anchor.net.au

        ServerAdmin webmaster@DOMAIN

        DocumentRoot /home/USER/public_html
        CustomLog logs/access_logs/DOMAIN_log combined
        ErrorLog logs/error_logs/USER_log

        # CGI Execution
        <IfModule mod_suexec.c>
                SuexecUserGroup USER users
        </IfModule>
        <IfModule mod_alias.c>
                ScriptAlias /cgi-bin/ /home/USER/public_html/cgi-bin/
        </IfModule>

        # Statistics - Awstats/Webalizer
        Alias /stats /var/www/html/usage/DOMAIN
        Alias /statistics /var/www/html/usage/DOMAIN
        Alias /logs /var/www/html/usage/DOMAIN
        Alias /usage /var/www/html/usage/DOMAIN

</VirtualHost>

This contains all the configuration for this particular site.

This template is designed in a fashion which allows for the relevant sections to quickly and easily replaced using vi the following two commands within vi:

    :%s,DOMAIN,X,g

Important: Please replace the X section with the domain name this is being configured for. For example, if I wanted to set this up with the domain anchor.net.au I would use:

  • :%s,DOMAIN,anchor.net.au,g

The second section which will need to be changed is the section relating to the username. This can be done with the following command within vi:

   :%s,USER,Y,g

Important: On this occasion Y needs to be replaced with the username that is to be associated with this website. This should be the username which was created in section 1. Example:

    :%s,USER,anchor,g

Please note, the syntax for both of these commands are listed at the top of the file to assist in making these changes.

Once these changes have been made you will be able to exit out of vi and save the changes using the following command:

    :wq!

If you make a mistake and would like to exit without making any changes, the following command can be used:

    :q!

The final and most important step is to check the configuration and then reload it. This can be done using the following command:

   service httpd graceful 

This command should run without any errors.

Important: If this generates ANY errors you will need to open the file up and correct the mistake. If you are unsure what the problem is please contact support. On Anchor Secure and Anchor Complete support packs the web server is monitored 24 hours a day 7 days a week. If it stops running for whatever reason visual and audible alerts are generated. Outside of hours these are sent to on-call staff via SMS.

Each morning at 4am a process is run which consolidates all the log files for the web server, generates statistics and restarts the webserver. If the configuration is left in a broken state then Anchor system administrators will get notifications at 4am when the web server is started. Whilst on-call staff will get up and fix the problem, obviously we are keen to avoid this where ever possible.

The managed server is now configured to work with the new website.

Advanced

As discussed earlier in this document, the files which contain the per user configuration for all the websites on the machine are stored in the directory: /etc/httpd/conf/users/

This is all broken up on a per user basis, which means that all users on the machine have a configuration file that relates to the site(s) they are hosting.

Dissecting a configuration file

This section will breakdown each section of the configuration file and discuss some of the options which can be used.

Each site is broken down into what is referred to as a 'virtual host'. Historically, the term 'host' referred to a single machine on the Internet.

As machines these days are capable of hosting many websites the term 'virtual host' was defined. Essentially, this means that the web server appears and simulates the behaviour of a single, individual host, but really it isn't.

 <VirtualHost *>

All virtual hosts must be started with this line. This indicates the beginning of the configuration and the * specifies that it will work across all interfaces (IP addresses) on the machine. From this point on the file has a number of lines which are referred to as 'Directives'. These Directives dictate the behaviour of the virtual host.

       ServerName anchor.net.au:80 

The ServerName Directive is required in every virtual host. This value must be unique and is equivalent to the name of the virtual host. There can only ever be 1 ServerName directive per virtual host. When the web server receives a request the first thing it will look at is the site the user is looking for. This is required to ensure that it delivers the correct content.

         ServerAlias www.anchor.net.au
         ServerAlias anchor.tmp.anchor.net.au
         ServerAlias www.anchor.tmp.anchor.net.au

ServerAlias is an alternative to server name. As you can only have 1 ServerName directive this lets multiple domains work with the one site. This allows many domains to point to the one website.

        ServerAdmin webmaster@anchor.net.au 
        DocumentRoot /home/anchor/public_html
        ErrorLog logs/error_logs/anchor_log

This first directive in this block lists the email address of the web master.

When an error is generated by the webserver an email address will be listed as the web masters. This is designed to allow people visiting the website the opportunity to email the web master to tell them something has broken.

The second directive in this block relates to the DocumentRoot. This is going to be the place where all webpages are stored for the hosting account.

By default across the Anchor servers this will be within the public_html directory in the users home directory. The third directive relates to where all error files should be logged to for this virtual host. This is relative to the webserver home directory.

    # CGI Execution 
        <IfModule mod_suexec.c>
                SuexecUserGroup example users
        </IfModule>
        <IfModule mod_alias.c>
                ScriptAlias /cgi-bin/ /home/example/public_html/cgi-bin/
        </IfModule>

This section relates to CGI scripts execution.

Firstly all scripts are to executed using suexec. This allows all CGI's on the server to run as the users account instead of the apache user, which is undesirable in a shared hosting environment.

The second section refers to mapping the /cgi-bin to the appropriate location on the server.

</VirtualHost> 

The above tag is required to close the virtual host and is designed to signify the end of the virtual host configuration.