Overview

Our Linux Cloud Servers are built from a minimal installation image, meaning there are no additional applications installed beyond the base Operating System.

To begin using your server, you initiate an SSH session to remotely connect to the Cloud Server. In order to make it more useful, you are responsible for installing applications. This can be done by compiling a program from the source code, or more commonly using the Package Manager to install an application from a repository.

The most common application installed is a web server, such as Apache or Nginx.

In order to serve a website you must set up the rest of the framework to serve your content, and then upload the actual content to your server. This entails installing any databases or Content Management Systems your site requires. For networking, you will need to add appropriate DNS records in the Rackspace Cloud control panel, to let the DNS system and the rest of the Internet know that your site is hosted from a Rackspace Cloud IP address.

Finally, you come to the part that allows your Cloud Server to deliver your websites, and for this you will need to create your sites as virtual hosts within your webserver configuration.

Procedure

Greatly simplified, the procedure for serving a website is as follows:

A browser sends a request to your Cloud Server's IP address asking for the contents of 'http://yourexampledomain.com/' (your domain name).

Your web server jumps into action and says "Yes! I have something for you matching your request". The web server does its 'thing' and serves up an http representation of your site, which is sent to the requesting browser. The browser then translates the http and parses it to a human-readable form.

Simple, right? But how does your web server know what http to serve? If all you are serving is one website from the server, then it will serve the html in your /var/www/html directory, starting with index.html. We've all made a "Hello World" page before, right? But having a unique server for every website you want to serve is costly, and an inefficient use of your resources.

Virtual Hosts

Here come name based virtual hosts, allowing you to serve content for multiple websites from one server.

One of the first lines in any virtual host configuration file contains the domain name that is associated with the vhost.

Each configuration starts slightly differently, but the same principle applies - that particular virtual host will respond to queries for 'domain1.com' and 'www.domain1.com'.

Multiple domains

So, serving different content for different domains is as simple as adding another virtual host.

Let's say you have a subdomain called 'blog.domain1.com' serving a blog.

The basic creation process would be to create a folder in your public_html folder with the relevant files (let's say a Wordpress install).

A virtual host would be created with the server_name or ServerName as 'blog.domain1.com' which would be configured to point to the blog files and folders in your public_html folder.

Troubleshooting

This section shows you how to troubleshoot problems with Apache name-based virtual host configurations.

It will show you useful commands for testing your virtual host configuration, how to interpret their output, and how they help fix common virtual host configuration problems.

Restart Apache

Before we make a start on learning to diagnose your issue, make sure that you have restarted Apache since the last changes you made to your Apache configuration files:

For Red Hat derived distributions use:

sudo /usr/sbin/httpd -k restart

For Debian derived distributions use:

sudo /usr/sbin/apache2 -k restart

If Apache gives you any warning or error message, make a note of it for the moment because we're first going to take a look at a diagnostic command that's used to check your virtual host configuration.

All the examples that follow assume you have created two virtual hosts: vh1.example.com and vh2.example.com.

We’re now ready to make a start, run the following command on the webserver:

For Red Hat derived distributions use:

sudo /usr/sbin/httpd -S

For Debian derived distributions use:

sudo /usr/sbin/apache2 -S

Understanding the Configuration Report

The following example shows the configuration report for a server configured with two name-based virtual hosts.

[1] Reports that the webserver is listening on the default port of 80 for all the IP addresses that Apache is listening to, and that name-based virtual hosting is turned on. The * is a wildcard specifying all IP addresses.

[2] Reports the default virtual host the webserver will serve for any requests for which no specific hostname is requested. It also shows the path to the configuration file and line number where this configuration is set.

[3] Reports the port and the name of first virtual host configuration found, the file it is configured in and the line number its configuration starts on.

[4] Reports the port and the name of second virtual host configuration found, the file it is configured in and the line number its configuration starts on.

[5] Reports if the configuration syntax is correct, though that does not necessarily mean your site is working!

The output above was produced by the following virtual host file configuration:

NameVirtualHost *:80 Turns on name-based host resolution and binds the virtual server to IP addresses and ports as in [1] above. The * is a wildcard specifying all IP addresses.
<VirtualHost *:80> Configures the first and default virtual host in [2] & [3] above. It is the default because it is the first virtual host whose IP and port matches those in the NameVirtualHost directive before it.
ServerName vh1.example.com
DocumentRoot /var/www/vhosts/vh1
</VirtualHost>
<VirtualHost *:80> Configures the second virtual host in [4] above.
ServerName vh2.example.com
DocumentRoot /var/www/vhosts/vh2
</VirtualHost>

Now that that you've seen how a basic virtual host configuration looks and how it maps to Apache's own configuration report, let's use those reports to look at common configuration issues.

This indicates that multiple virtual hosts are trying to use the same "socket" without being set up as name-based virtual hosts. This error often shows up on a first pass at creating Apache virtual hosts because the default NameVirtualHost directive is commented out with a hash. That hash instructs Apache to ignore the directive.

To fix this in a default Apache configuration file, you would check that the "NameVirtualHost *:80" directive is not commented out. If working with a minimal Apache configuration file, you would add a "NameVirtualHost *:80" directive prior to the individual virtual host configurations.

In the example below, we show the commented “NameVirtualHost *:80” directive that caused the above error:

This means that the virtual host's VirtualHost directive is missing a vital element. The VirtualHost is the first line of any individual virtual host configuration. In this case, it is on the 8th line of the configuration file /etc/httpd/conf/custom/virtualhost.conf.

Note in the example above how the configuration test reports about vh2.example.com's configuration before it reports the NameVirtualHost configuration. You may see this error if the VirtualHost IP address or port does not match that of a webserver's NameVirtualHost directive. In this example, the test reports that vh2.example.com uses port 800 rather than the NameVirtualHost's port 80. We mis-typed "80" when we configured the vh2.example.com virtual host's listening port. As a result, Apache is seeing vh2.example.com as a separate port-based virtual host.

The test command “httpd –S” will not warn you about this because it is permissible to configure virtual hosts to use any port, such as 800, without their being part of the name-based virtual host configuration on the same server.

If you do make this mistake, you will probably see content from the default virtual host (vh1.example.com in this example) when you try to view the site in your web browser.

To help you map the above output to how its configuration file might look, here's the virtual host configuration that created this error:

This specific error indicates that the directory specified as containing the website files for the vh2.example.com virtual host does not exist, or that Apache cannot access it. Similar errors can appear for any of the file paths specified in a virtual host configuration, such as the paths to the virtual host's log files.

To fix, make sure you created the directory. If you definitely created it, check there are no mistakes in the DocumentRoot directive. A common mistake is to miss out the path's initial "/". Leaving out the "/" instructs Apache to read the path - the DocumentRoot path in this case - as a relative path. That is, as a path relative to the main Apache configuration's ServerRoot path.

As there are several ways in which this error is often created, we've created an example of just one of them. In the example below, you'll see that the path for the DocumentRoot in the first virtual host starts with a "/" but the second one does not. This makes Apache read the DocumentRoot path for vh2.example.com as an extension of the default webserver's ServerRoot path /etc/httpd/ to create a DocumentRoot path of /etc/httpd/var/vhosts/vh2.

The first line shows the all-important status code. We want to see a "200 OK" as in the above line's "HTTP/1.1 200 OK". If that's what you see, test the webserver with your browser, though be careful with this because you browser may be displaying a cached page.

If you don't see “200 OK”, some of the common messages you may see are:

1. curl: (6) Couldn't resolve host "vh1.example.com" If curl reports it cannot find the host you need to check that you have an A record for the domain that points to the correct IP address for your server. The dig command can be used to do this:

dig vh2.example.com

2. curl: (7) couldn't connect to host

Check that your Apache configuration files include the necessary Listen directives and that they are not commented out. You'll need "Listen 80" at the very least.

Check Error Log

Another way to look for this is check the error log. The default error log is at /var/log/httpd/error_log on Red Hat-derived systems and at /var/log/apache2/error_log on Debian-derived systems. You will see "no listening sockets available, shutting down" following Apache's attempt to restart if you're not specifying any port for Apache to listen on.

If you get this response when using curl it indicates the permissions aren't quite right for allowing Apache access to the page you're requesting. This could be because the directory permissions are incorrect or it could be the page itself.

You may also see a 403 error if the DocumentRoot contains no "index" file - typically named "index.html" or "index.php". Note the filename is case sensitive. Or you may see 403s if the virtual host doesn't contain a DirectoryIndex directive specifying the default index file.

The Apache error logs will usually reveal on which directory or file the permissions are incorrectly set. The default error log is at /var/log/httpd/error_log on Red Hat-derived systems and at /var/log/apache2/error_log on Debian-derived systems.

Individual virtual hosts may write errors to their own logs if they were configured to, so check these logs too.

Do not be put off by the volume of data in a busy server's log files. Instead, use the "tail" command to selectively view just the most recent ten lines of a log. For example:

tail /var/log/apache2/error_log

Better yet, you can see new entries as they are added to the error_log - or any log - while you test the server if you instruct the "tail" command to "follow" the log. For example:

tail -f /var/log/httpd/error_log

Common Permissions-Related Errors

To round off our exploration of common Apache configuration errors, here are some examples of how some common permissions-related configuration errors appear in Apache's logs