Apache Webserver Configuration

This page explains how to use Webmin to configure the Apache webserver. It covers virtual hosts, IP access control, password restrictions and much more.

Introduction to Apache

Apache is the Internet's most popular HTTP server, due to its zero cost, wide availability and large feature set. All Linux distributions include it as a standard package, and it can be installed on or compiled for every other Unix variant supported by Webmin. However, it has a very large number of option directives defined in a text configuration file, and so can be hard for an inexperienced administrator to set up.

Over the years since it was first introduced, many versions of Apache have been released. Starting with 1.0 and moving through to the current 1.3 and 2.2 series, each version has included more features and options. The basic webserving functionality and configuration file layout has remained essentially the same throughout, even though the internal implementation has changed significantly.

Apache has a modular design, in which each module is responsible for some part of its overall feature set. There are several standard modules that are included with almost every install of Apache, and many more that are optional or have to be downloaded separately. Modules can be compiled into the webserver executable, or dynamically loaded from shared libraries at run time. This modular architecture can be used to save memory by avoiding the need to load modules that do not provide any useful functionality for a particular system.

Apache takes its configuration from multiple text files, each of which contains a series of directives, usually one per line. Each directive has a name and one or more values, and sets an option such as the path to a log file or the MIME type for some file. The directives that Apache recognizes are dependant on the modules in use. Most modules add support for several directives to configure the functions they provide.

Often, you will want to host more that one website on a single server. Apache can be configured to use a different configuration depending on the web site that was requested by a browser. Each one of these sites is called a virtual host, and is defined in the configuration file with a special <Virtualhost> section. All directives inside this virtual host section apply only to requests that match its IP address or hostname.

Similarly, <Directory> and <Files> sections can be defined in the configuration file to contain directives that apply to only a certain directory or to files matching some pattern. These are often used to deny access to certain files on your system, to password protect them, or to control the way that they are displayed to clients.

Another method of creating directives that apply to only to a single directory is to put them in a special configuration file named .htaccess that resides in the directory itself. Often these files will be created by regular users, so that they can configure their own websites without needing full access to the master configuration file. This is very useful on a system that hosts multiple sites that are each owned by a different Unix user, rather than on a system with only one website that is set up by the server's owner.

The Apache Webserver module

This is one of the most complex and powerful Webmin modules, as it allows you to configure almost every feature of Apache. It can determine the version of Apache that is installed on your system and the modules that it uses, and adjusts its user interface accordingly so that you can edit only those directives that the webserver understands. However, the interface is generally the same for all versions of Apache.

Because there are so many directives and the module attempts to allow configuration of all of them, it groups directives into categories like Processes and Limits, Networking and Addresses and CGI Programs. These categories are represented by icons that will appear when you open a virtual server, directory or options file in the module. In all cases, you can view and edit the settings under each category by clicking on its icon.

Apache has a large number of standard modules, and an even larger number of separate modules that were developed by other people. Webmin does not support the editing of directives in most of these non-standard, such as mod_perl and mod_php. However, it will safely ignore any configuration file directive that it does not understand, so that any settings for unsupported modules that you make manually will not be harmed.

When you open the Apache module, the tabbed page shown below will be displayed :

The Apache Webserver module main page

In the first tab are icons for the various categories of global options, as well as a few extra features. In the second is a list of all current virtual servers, and in the third is a form for adding a new virtual host. If you have a very large number of virtual servers on your system (more than 100 by default) a search form for finding servers will be displayed instead. The first server will always be the special Default Server, which contains directives that apply to all other virtual servers and handles requests that other servers do not.

Naturally, the Apache module will not work if you do not have Apache installed on your system. If this is the case, the main page will display an error message instead of the module configuration form or list of virtual servers. All Linux distributions include a package or packages for it on their CD-ROM or website, so install it from there using the Software Packages module (covered in SoftwarePackages) before continuing.

Because the module assumes that the Apache executable and configuration files will be in the locations used by your distribution's package, it will report the same error about the software not being installed if you have compiled and installed it manually. If this is the case, click on the Module Config link and adjust the paths to the correct locations for your system.

On versions of Unix that do not include Apache by default, Webmin assumes that it will be installed from the standard source distribution from www.apache.org. If you have installed the webserver from an optional package that has been made available for your OS, then the main page will complain that it is not installed and you will need to adjust the module configuration.

The module's user interface is quite complex and has a large number of pages, forms and sub-pages due to the complexity and power of the Apache configuration files. However, there are elements of the interface that are repeated on many pages throughout the module, such as :

• Category icons When you click on the icon for a virtual server, directory or options file, a table of icons with names like MIME Types and CGI Programs is displayed at the top of the page. Under each of these icons are fields and tables for configuring options related to the label of the icon they are under. This commonly used layout breaks down the vast number of editable Apache options into categories, as there are far too many fields to display on a single page. The exact icons that appear and the fields under them differ depending on the part of the webserver configuration you are editing, and the version of Apache that is installed. However, their basic layout is always the same.

• Tables fields On many forms, some fields use tables for entering multiple values such as MIME types and their associated file extensions. There is no limit on how many rows each table can have, but Webmin will only display a single empty row in each table at any one time. This keeps down the size of forms that have lots of tables, but means that you can only add one new row to a table at a time. To add more than one, you will need to save the form and then re-enter it again, which will cause a new blank row to be displayed below the one you just filled in.

The sections below explain in more detail exactly which icons to click and which tables to fill in when doing things like enabling CGI scripts and setting MIME types.

Starting and stopping Apache

Before browsers can connect to the Apache webserver on your system, its server process must be started. You can check if it is currently running by looking at the top of any of the pages in the module. If links labelled Apply Changes and Stop Apache appear, then it is currently active. However, if only the link *Start Apache* appears them it is not yet running.

To start it, click the Start Apache link. If all goes well, the page that you are currently on will be re-displayed and the links at the top should change to indicate that it is now running. Otherwise, an error message will appear explaining what went wrong - most likely the cause will be an error in the configuration file.

To stop the webserver once it is running, click the Stop Apache link on any of the module's page. In the unlikely event that Webmin is unable to stop the server, an error message page will be shown. If it is stopped successfully, the same page will re-displayed with the links at the top changed to show that it is no longer running.

When Apache is active, every page will have an Apply Changes link at the top that can be used to signal the webserver to re-load its current configuration. After you make any changes in this module (except those in .htaccess files), this link must be clicked to make them active. Unlike other Webmin modules that have an Apply button on the main page, this one has it on every page so that you do not have to return to the index every time you make a change.

Editing pages on your webserver

This section explains how to find and edit the files on your system that are displayed when a client connects to your Apache webserver. If you already know how to do this, feel free to skip it and move on to the next section.

When Apache is first installed from a package or from source, its initial configuration will typically not have any virtual servers set up. Instead just the default server will exist, serving pages to any client that connects on port 80. You can view the default pages by running a web browser and going to the URL http://_yourhostname_/ , or http://_localhost_/ if you are running the browser on the same system that Webmin is on. The page that appears will probably just be one supplied with Apache or your Linux distribution.

The document root directory that Apache serves files out of will be shown on the module's main page next to the Default Server icon. On Redhat Linux for example, this directory is /home/httpd/html by default. The files in this directory can be edited by logging in as root, or by using Webmin's File Manager module. Any changes that you make will be immediately reflected on the website.

If your system is just going to host a single static website, it may not be necessary to configure any other aspects of Apache. You can just upload or copy HTML, image and other files to the directory and its subdirectories to create the site that you want. The most important file is index.html, which is served by Apache whenever a browser does not request a specific page. Because most people will go to http://_yourserver_/ first, the index.html page will be the first one that they see.

To make editing easier, you may want to change the ownership of the document root directory and all its files to a non-root user. However, you must make sure that they are still readable by the user that the Apache server process runs as, which is typically named httpd. The easiest way to do this is to make all files and directories world-readable and world-executable.

Creating a new virtual host

If you want to host multiple websites on your system, then you will need to create an Apache virtual host for each one. Before you can add a site, its address must first be registered in the DNS, either on a DNS server on your system or on another host. If the site's files are to be owned by a different Unix user to the one who owns the document root directory, then he must be created first as well.

The entire process for adding a virtual server, including the above steps, is :

1. Decide on a hostname that will be used in the URL for the new website, such as www.example.com.
2. Decide if your new site is going to be IP-based, or name-based. A name-based site will work fine with all except for old browsers, and so is by far the best choice these days. An IP-based site will work with any browser, but needs its own separate IP address to be added to your system. Because IP addresses are often scarce, this only makes sense if you need to set up a virtual FTP or POP3 server for the domain as well.
3. If your site is going to be IP-based, use the Network Configuration module (covered on NetworkConfiguration) to add a new virtual IP address to the external network interface on your system. Make sure that it will be activated at boot time and is active now. If your system has only a single static internet IP address assigned by your ISP, then any extra virtual IP addresses that you add to it will not work. In that case, you will have to use a name-based virtual server instead, or request that your ISP assign you multiple addresses.
4. If the example.com domain already exists on a DNS server, add a record for www.example.com with the external IP address of your system (for a name-based site) or the address chosen in the previous step (for an IP-based site). If the domain does not yet exist, you will need to add it to a DNS server and register it with a DNS registrar like Network Solutions. Either way, the BINDDNSServer page explains how to add records and domains in detail.
5. If the site is going to use the standard HTTP port 80 (which is almost always what you want), then you can skip to step 8. Otherwise, on the Apache Webserver module's main page click on the Networking and Addresses icon to bring up the form shown in the first screenshot below.
6. In the empty row in the Listen on addresses and ports table, select All under the Address column and de-select Default under the Port column. Then enter the TCP port number for your website into the field next to it, and click the Save button at the bottom of the page.
7. On the module's main page, scroll down to the Create a New Virtual Server form below the list of existing virtual hosts.
8. If you are setting up an IP-based virtual server, in the Address field you should enter the virtual IP address that was added in step 3. If setting up a name-based virtual server, enter the external IP address of your system into the field instead. If your Apache server has been configured to accept name-based connections on any IP address, you can select the Any option for this field instead. See the explanation below for more details. If your new virtual server is going to use a port other than 80 and will be the only server on that port, you can select the Any option as well so that it handles all requests that come in on the port.
9. If you are setting up an IP-based virtual server, de-select the Add name virtual server address checkbox. For name-based servers, it should be left enabled.
10. If the new virtual host is going to use a non-standard port, select the last option for the Port field and enter the number into the field next to it.
11. In the Document Root field, enter the full path to the directory that will contain files for this website. For example, this might be /home/example/www.
12. In the Server Name field, enter the hostnames that clients will use to refer to this website such as www.example.com. You can enter more than one name, such as web.example.com and example.com if this is going to be a name-based server that should be accessible at several different URLs.
13. Unless you have a separate file on your system that contains all virtual hosts, leave the Add virtual server to file field set to Standard httpd.conf file. Otherwise you can choose Selected file and enter the path into the field next to it. Make sure that the chosen file is actually used by Apache (such as by an Include directive in httpd.conf) or the virtual server will be useless and will not appear in Webmin. If you always use the same separate file for storing virtual hosts, the File to add virtual servers to field explained in the Configuring the Apache Webserver module section below may be useful. If it is set, another option is add to the Add virtual server to file field for adding to the file set by this module configuration option.
14. To have Webmin copy all of the directives from another virtual server to the one that you are creating, select it from the Copy directives from menu. This can be useful if all of your virtual hosts have a similar configuration.
15. When you are done filling in the form, click the Create button. The new virtual server will be added to the Apache configuration file and to the list of servers on the main page.
16. Click on the icon for the new virtual server, which will take you to its options page, shown in the second screenshot below.
17. Scroll down to the form under Per-Directory Options, and enter the document root directory that you chose in step 11 into the Path field. Make sure the Type is set to Directory, and the Regexp? field to Exact match.
18. Click the Create button to add a new section to the configuration file for the directory. This is necessary so that you can grant clients the rights to browse files that it contains, which the default Apache directory configuration denies.
19. Click on the new icon for the directory that has been added to the virtual server options page. This will take you to the directory options page, shown in the third screenshot below.
20. Click on the Document Options icon, and on the form that appears change the Directory options field to Selected below. Under the Set for directory column, change the entry for Generate directory indexes to Yes. Then click the Save button at the bottom of the page.
21. To make all your changes active, click the Apply Changes button at the top of any page.
22. You or the user who owns the virtual server can now start adding files to the document root directory. You can test it out by opening the URL (such as http://_www.example.com_/) in your web browser to make sure that everything is working properly.

The global networking and addresses page

The virtual server options page

The directory options page

When Apache receives an HTTP request, it must first work out which virtual server the request is for. It will first look for a name-based virtual server whose hostname matches the host requested by the client, and whose address and port are the same as the ones that the client connected to. If none is found, the first defined virtual server for the address and port will be used instead, or if there are none then the request will be handled by the default server.

Name-based virtual servers can only be used on addresses listed in the Addresses for name virtual servers field on the global Networking and Addresses page. If you follow the instructions above, an address will be added to this list automatically when you create a new virtual server. If all the virtual servers on your system are going to be name-based, you can open this page, enter * into the field and click Save so that Apache will handle such requests on any IP address. This also makes sense if you system has a dynamically assigned IP address and you want to serve multiple virtual hosts.

Once a virtual server has been created, you can edit its settings or delete it by following these steps :

1. On the module's main page, click on the virtual server's icon. This will take you to the server options page shown in screenshot above.
2. Scroll down to the Virtual Server Details form at the bottom of the page.
3. Change the Address, Port and other fields to whatever you want and click the Save button. These fields have the same meanings as on the virtual server creation form. However, if the address is changed on a name-based virtual server you may need to change it on the global Networking and Addresses page as well. Or if you want to get rid of the virtual server and all the configuration directives that it contains, click the Delete Virtual Server button instead.
4. Back on the module's main page, click on the Apply Changes link to make the new settings active.

You cannot change the settings for the default server, nor can you delete it.

Setting per-directory options

Apache allows you to specify different options for certain directories, either for all virtual servers or just to a single one. Including directories, you can actually set options that apply to three types of object on your Apache server :

• Directory The options apply to a specified directory and all files in it or in sub-directories that it contains.

• Files The options apply to files with a specified name in any directory.

• Location The options apply to any files or directories requested by a URL whose path starts with the specified location. For example, in the URL http://www.example.com/foo the path would be /foo.

Whenever Apache processes a request, it checks for the options that apply to it in a fixed order. Those from directory sections and .htaccess files are read first ordered so that the most specific directories are checked first. They are then followed by files and then location sections. Then options from the virtual server that the request was made to (if any) are read, and finally options from the default server.

This means that options set for a directory will override the same options set in a higher level directory, or in the virtual server that it is a member of. To set options for a directory, files or URL location the steps to follow are :

1. Even though the options you are going to set apply to a directory, they must be defined under one of the virtual servers or the default server. If they are under a virtual host, then they will apply only to requests to that server for files in the chosen directory or URL location. But if they are under the default server, requests to any virtual host for files in the directory will be effected. On the module's main page, click on either the Default Server icon or the icon for a virtual server that you want the directory options to be limited to. For directories, it is usually simplest to put their options under the default server as each virtual host typically has its own separate document root directory. URL location options however should be put under the virtual server that they are related to, because the same URL path may be used in different ways on more than one virtual host. The same goes for file options.
2. On the server options page that appears (shown in Figure 29-4), scroll down to the Create Per-Directory, Files or Location Options form.
3. From the Type menu, choose one of the options described above.
4. If you are setting options for a directory, enter it into the Path field such /home/example/www/images. You can also enter a wildcard path such as /home/example/w*, which will cause the options to apply to all directories that match. If the options are being set for a URL location, enter the part of the URL after the hostname into the Path field, such as /images. You can also use shell wildcard characters like * and ? in the URL as well. If setting options for files, enter a filename into the Path field such as secret.html. Once again, wildcard characters can be used in the filename, for example secret*.
5. If you want to be able to used complex regular expressions in the directory, filename or URL location, set the Regexp? field to Match regexp. This will allow you to use Perl regular expression characters like [, ], +, . and * in the path.
6. Click the Create button to add the new directory section to the Apache configuration. The virtual server options page will be displayed again, but with a new icon for the directory.

Now that you have created a new icon for a directory, URL location or filename, you can set options that apply to it. One of the most common per-directory changes is configuring how files are listed when a browser requests a directory with a URL like http://www.example.com/images/. By default, if there is an index.html file in the directory it will be displayed, or if not a page listing all files that it contains will be shown instead.

If you want to change the name of the index file, the style of the directory listing or any other settings related to indexing, the steps to follow are :

1. Click on the icon for the directory that you want to configure on the virtual server options page. This will take you to the directory options page shown in Figure 29-5.
2. Click on the Directory Indexing icon to bring up a form for setting indexing and listing options.
3. To change the appearance of directory listings, set the Directory index options field to Selected below and change the fields in the box below it. The defaults will generate a very plain list of files, but you can enhance it by setting the following options :
   • Display fancy directory indexes If enabled, the list of files will include their icon, size and modification date.
   • Display HTML title as description If enabled, the description for HTML files will be taken from their <title> tags.
   • Icon height This option allows you to change the height of icons included in the directory listing. If it is set to Default, the height of the standard Apache options will be used.
   • Icon width Like the previous option, this one allows you to specify the width of icons in the directory listing.
   • Allow user sorting of column When this is enabled users will be able to sort the list of files by clicking on the column headings, assuming they are being displayed.
   • Show file descriptions If enabled, the directory listing will include a description for each file taken from its MIME type or HTML title.
   • Output HTML header tags When enabled, the directory listing will include the normal <html> and <head> tags that should begin every HTML page. You would only want to turn it off if providing your own header and footer files.
   • Show last modified times When enabled, the directory listing will include the last modified date for each file.
   • Show file sizes When enabled, the listing will include the size of each file.
   • Include icon in link If this option is enabled, the icon in the listing will be a link to the file itself. Otherwise only the filename is a link.
   • Filename width This option controls the length of the filename column in the directory listing. You can either enter a number of characters or * to size the column to the length of the longest filename.
   • Description width This option controls the length of the description column in the directory listing, if any. You can either enter a number of characters or * to size the column to the length of the longest description.
   • Display directories first If enabled, the listing will show any directories above any files regardless of any other files. The options that are available depend on the version of Apache that you have installed on your system. Those listed above are valid for version 1.3.19, but if you have a newer release more options may be available.
4. If you want Apache to return a file other than the default (usually index.html) when a browser requests the directory, enter a list of filenames into the Directory index files field. More that one can be entered, and the first that is found will be used. If none of the index files are found a directory listing using the options chosen in step 3 will be returned to the browser instead.
5. To have the webserver ignore certain files when generating the list of files in the directory, enter their filenames into the Files to ignore in directory index field. You can use shell wildcards in the regular expressions, such as *.doc.
6. To have an HTML file inserted at the start of the directory listing, enter its filename (relative to the directory) into the Directory index header file field.
7. Similarly, to have a file added at the end of the directory listing, enter its into the Directory index footer file field.
8. To control the default ordering of the directory, de-select Default in the Sort directory index by field and select an order and column to sort on from the two menus next to it.
9. You can set descriptions for files by filling in the Directory index descriptions table. In the table's empty row, enter a short message describing the file in the Description column, and a list of filenames or wildcard names in the Filenames column. Because only one empty row is shown at a time, you will need to re-visit this page after adding each description if you want to enter more than one.
10. Finally, click the Save button at the bottom of the page to store your changes and return to the directory options page. To activate them, click the Apply Changes link anywhere in the Apache module.

Most of these options can be set for an entire virtual server by clicking on the Directory Indexing icon on the virtual server options page as well. In this case, they will apply to all files requested from the virtual host unless overridden by options for a directory or URL location.

On the directory options page there are many more icons that you can click on to set options that apply only to that directory, URL path or filename. Some of these are explained in other sections later in this chapter, such as Aliases and redirects and *Password protecting a directory*.

You can change the directory, filenames or URL location that settings apply to using the Options apply to form at the bottom of the directory options page. It has the exact same fields as the creation form described at the start of this section. If you make any changes, click the Save button to update the Apache configuration and then the Apply Changes link to make them active. Or to remove the directory configuration and all its options, click on Delete instead.

Creating aliases and redirects

Normally, there is a direct relationship between the path in URL and the file that is returned by the webserver. For example, if a browser requests http://www.example.com/images/foo.gif and the document root for www.example.com is /home/example/www, then the file /home/example/www/images/foo.gif would be read by the webserver and returned to the client.

This can be changed though by using what Apache calls aliases. An alias maps a particular URL path to a file or directory, which does not necessarily have to be under the document root. So in the example above, the /images URL path might actually be aliases to the directory /www/images, which would cause the file /www/images/foo.gif to be read instead.

Aliases can be defined globally or in a virtual server. To create one, the steps to follow are :

1. On the module's main page, click on the icon for the virtual server that you want to create the alias under. If you want it to apply to all virtual servers (or you don't have any), click on the *Default Server *icon instead.
2. On the virtual server options page that appears, click on the Aliases and Redirects icon. This will take you to the page in the screenshot below.
3. Fill in the empty row in the Document directory aliases table with the URL path (under From) and the file or directory that it should map to (under To). If you are editing the default server, there may already be several entries in this table that are part of the standard Apache configuration. There will always be exactly one empty row in the table. If you need to add more than one alias, you will need to re-visit this page after filling in the row and saving.
4. Click the Save button to have your new alias stored in the Apache configuration. The browser will return to the virtual server options page.
5. To make the alias active, click on the Apply Changes link at the top of the page.

The aliases and redirects form

Existing aliases can be editing by just changing the entries in the Document directory aliases table and then clicking Save. You should not change the alias for /icons in the default server though, as this is used by Apache when it generates icons for directory listings. If you want to delete an alias, just delete the contents of both its fields in the table.

Aliases can also be created that use Perl regular expressions to match more complex URL paths. These must be entered into the Regexp document directory aliases table on the Aliases and Redirects form, which has the same columns as the *Document directory aliases* table described above. The difference is that any regular expression can be entered into the From field, such as ^/images/(.*)\.gif$. The To field can taken a string that refers to bracketed sections in the expression, such as /images/$1.jpg. This would convert any request for a GIF file into one for the JPEG with the same name.

Redirects are similar to aliases, but have a different purpose and work in a different way. Whenever a client requests a URL path that has been redirected, Apache will tell it to go to another URL (possibly on another server) instead. For example, you might redirect all requests to http://www.example.com/webmin/ to http://www.webmin.com/. Unlike the way aliases behave, if a browser requests a page like /webmin/foo.gif it will not be redirected to http://www.webmin.com/foo.gif - it will just go to the URL http://www.webmin.com/ instead.

Redirects are implemented by the webserver sending the special 302 status code to the browser, which tells it to go to a new location. It is quite possible for the new URL to be a redirect itself, and you can even create a loop of redirects - not that this is a good idea.

To set up redirection for a path on your server, the steps to follow are :

1. On the module's main page, click on the icon for the virtual server that you want to create the redirect under. If you want it to apply to all virtual servers, click on the *Default Server *icon instead.
2. On the virtual server options page that appears, click on the Aliases and Redirects icon to go to the page in Figure 29-6.
3. In the empty row of the URL redirects *table, enter the URL path on your server under the *From column, such as /webmin. Under the To column, enter the URL that requests should be redirected to, such as http://www.webmin.com/. The Status field is optional, but can be filled in if you want to change the HTTP status code that will be used for this redirect. The default is 302, which indicates a temporary redirection. However, you can 301 to tell browsers that the direction is permanent, or 303 to tell them that the original content has been replaced. There will always be exactly one empty row in the table. If you need to add more than one redirect, you will need to re-visit this page after filling in the row and saving.
4. Click the Save button to have your new redirect stored in the Apache configuration. The browser will return to the virtual server options page.
5. To make the redirection active, click on the Apply Changes link at the top of the page.

As with aliases, existing redirects can be edited by just changing the entries in the URL redirects table and then clicking Save. To delete a redirect, just delete the contents of all of its fields in the table.

You can also create regular expression redirects that behave in a similar way to regexp aliases, using the Regexp URL redirects table on the same page. Under the From column you can enter a URL path expression such as ^/webmin/(.*)$, and under the To column a URL that can refer to bracketed parts of the path, such as http://www.webmin.com/$1. In this example, an request by a client for a page under /webmin would be redirected to the same file at www.webmin.com.

Also on the Aliases and Redirects page are two more tables labelled Permanent URL redirects and Temporary URL redirects. The first behaves exactly the same as a normal redirection, but with the status code always set to 301, indicating a permanent redirection. The second also behaves like a normal redirect, but always uses a status code of 302 (temporary redirection). This option is really quite useless, as normal redirections default to using status 302 if one is not specified.

Redirects can also be defined in the options for directories, URL locations, filenames and .htaccess files. When editing the options for one of these (described in the *Setting per-directory options* section), the exact same icon and table are available as when setting up aliases for a virtual server. Naturally, a redirect in a directory only makes sense if the URL path being redirected actually refers to that some file or sub-directory that it contains. The same goes for redirects in URL locations - the path being redirected must start with the location's path.

If Apache on your system has been compiled with or dynamically loads the proxy module (covered in the *Configuring Apache as a proxy server* section below), tables labelled *Map locale to remote URLs* and Map remote Location: headers to local will appear on the Aliases and Redirects form under the virtual server options page. These allow you to specify a URL path that when requested will cause Apache to itself request pages from another website and return them to the browser. Even though the URL that the user is accessing is on your server and their browser is connecting only to your system, the content is actually being loaded from elsewhere.

To set up this URL mapping, the steps to follow are :

1. On the module's main page, click on the icon for the virtual server that you want to create the mapping under. If you want it to apply to all virtual servers, click on the *Default Server *icon instead.
2. On the virtual server options page that appears, click on the Aliases and Redirects icon to go to the page in Figure 29-6.
3. In the empty row in the Map locale to remote URLs table, enter a URL path on your server (like /webmin) into the first field, and the full URL that you want the pages to be requested from into the second (like http://www.webmin.com/).
4. In the empty row in the Map remote Location: headers to local table, enter the same full remote URL into the first field and the URL path on your server into the second. This second table controls the conversion of redirects issued by the remote server, and should almost always be set. If it is not set, whenever the remote server issues a redirect the browser will end up connecting directly to it instead of to your server.
5. Click the Save button to have your new mapping stored in the Apache configuration. The browser will return to the virtual server options page.
6. To make the mapping active, click on the Apply Changes link at the top of the page.

You can test it out by going to the mapped URL path on your system, and you should see pages that have been requested from the remote server. The process is not totally transparent though, because it does not convert HTML files in any way. So if in the example above the remote server contained an HTML page with a link like <a href=/foo.html>, following it would take the browser to /foo.html on your system, not /webmin/foo.html as you might expect. There is no solution to this problem, apart from making sure that the remote server always uses relative links and image paths.

Running CGI programs

CGI stands for Common Gateway Interface, and is a standard method for webservers to run external programs, pass them details of a browser's request, and read back any content that the program generates. CGI programs are one of the simplest way of adding dynamic pages to your webserver, and are relatively easy to set up and develop. Server-side includes (covered in the next section) are even simpler, but very limited in what they can do.

A CGI program can be written in any language as long as it follows certain rules. The most common is Perl, but C, Python, PHP or any other language that can access environment variables and produce output can be used. You can even write shell scripts that are valid CGI programs. This section is not going to explain the details of how to write them though - there are plenty of books that cover that already.

CGI programs are just files on your system, like any other HTML or image file. The difference is that when they are requested by a browser, Apache executes them and returns their output instead of the contents of the file. Because you only want this to happen for programs and not for HTML files, the server must be configured to identify certain files as CGI programs. This is normally done in one of two ways - by putting all CGI programs into a certain directory, or by giving them all a file extension like .cgi.

The choice is yours, but the latter option is simpler to use as you can freely mix CGI scripts, HTML and image files in the same directory. To set it up, the steps to follow are :

1. On the module's main page, click on the icon for the virtual server that you want to set up CGI programs for. Or click on the *Default Server *icon if you want to use them on all servers.
2. Click on the icon for the directory that you want CGI programs to be enabled under. Typically each virtual server will have an icon for options for its document root directory, but if not you can create one by following the steps in the Setting per-directory options section above. If you only want to allow CGI programs to be run in some sub-directory of the website, you can create a new directory icon for that as well.
3. On the directory options page, click on the Document Options icon and change the Directory options field from Default to Selected below. Then set the rows Execute CGI programs and Generate directory indexes to Yes, and click the Save button at the bottom of the page. This tells Apache that CGI programs can be executed in the directory.
4. Back on the directory options page, click on the MIME Types icon. In the Content handlers table, select cgi-script from the first blank menu under the Handler column, and enter .cgi into the field next to it under the Extensions column. Then click the Save button at the end of the form. This tells Apache to treat all files in the directory ending in .cgi as CGI programs.
5. Finally, click the Apply Changes link on any page. You should now be able to create a file with a .cgi extension in the chosen directory, and test it out in a web browser.

An alternative to this approach is to specify a directory in which all files are treated as CGI programs. This has the advantage that they can be given any name you like, instead of being forced to have a .cgi extension. You can also set permissions on this directory to restrict who is allowed to create CGI programs, while still allowing others to edit normal HTML pages.

To set up a directory for CGI scripts, the steps to follow are :

1. On the module's main page, click on the icon for the virtual server that you want to set up a CGI directory for. Or click on the *Default Server *icon if you want to set it up for all servers.
2. Click on the CGI Programs icon to bring up a page for setting various CGI options.
3. The CGI directory aliases table works in a very similar to the Document directory aliases table described in the previous section. However, in addition to mapping a URL path to a directory on your server it also tells Apache that any files accessed through that path should be treated as CGI programs. In the first empty row of the table, enter a URL path like /cgi-bin/ into the From field and a directory like /home/example/cgi-bin/ into the To field.
4. Click the Save button at the bottom of the page to return to the virtual server options page. Then click the Apply Changes link to make the CGI directory active.

You should now be able to create CGI programs in the directory, and test them out in a web browser. On some Linux distributions, the default Apache configuration will already have a CGI directory available at the URL path /cgi-bin/, mapped to a directory like /home/httpd/cgi-bin/. If this is good enough for you, there is no need to follow the steps above - instead, you can just put CGI programs in that directory.

Normally, all CGI programs execute as the Unix user that the webserver runs as, typically named httpd or apache. On a system with multiple users who cannot be fully trusted, this is not a good thing - anything that one user's CGI program can do, everyone else's can as well. So for example if a user writes a CGI program that edits some file, he would have to make that file writeable by the httpd user, meaning that everyone else's CGI programs could write to it as well.

Fortunately, there is a solution. Apache comes with an optional program called suexec that can be used to have CGI programs run as some other Unix user, rather than as the webserver user. Typically the CGI programs under each virtual server will be run as the Unix user who owns that server's files. To set this up, the steps to follow are :

1. Make sure that the suexec program exists on your system, and that it has setuid-root permissions. Apache typically expects to find it in /usr/sbin or /usr/local/apache/sbin, and most Linux distributions include it as a standard part of their Apache package. However, some do not have it setuid by default, so you may need to run chmod 6711 /usr/sbin/suexec to make it so.
2. On the main page of the module, click on the icon for the virtual server that you want to have CGI programs run as a different user on. This will take you to the options page shown in Figure
3. -4.
4. Click on the User and Group icon on the virtual server options page.
5. For the Run as Unix user field, select User name and enter the name of the user who owns the virtual server into the field next to it.
6. Similarly, for Run as Unix group select Group name and enter the primary group of the user specified in the previous step.
7. Click the Save button to return to the options page for the virtual server.
8. To activate suexec for the first time, you need to stop and re-start Apache. Use the Stop Apache link at the top of the page to halt it, and then the Start Apache link to start it up again.
9. To check that suexec is actually working, check the Apache error log file for a line containing suEXEC mechanism enabled that was logged when the webserver was re-started.

Because it can execute commands as any user on your system, suexec has many security restrictions to prevent misuse by normal users. It will only run CGI programs that are owned by the user and group specified in steps 4 and 5, and only if they are not writeable by any other user, or in a directory that is writeable by another user. The IDs of the user and group must be above minimums that are compiled into the program, to prevent programs owned by system users such as root or bin from being run. Finally, the program must reside under a directory that is compiled into suexec, and nowhere else on the filesystem.

This last restriction can be very annoying if you have a large number of virtual servers and want to enable the execution of CGI programs in their directories. The default allowed directory is typically the standard CGI directory for Apache, such as /home/httpd/cgi-bin. To change this, you will need to re-compile suexec with a different directory, such as /home.

Whenever suexec fails to run a CGI program, it fails with HTTP status code 500. Because there are many things that can go wrong, you should check the file suexec_log in the same directory as the other Apache logfiles to see why it is refusing to execute a particular program. For each failure, a line is written to this file explaining the problem, such as incorrect permissions or a file ownership mismatch.

Writing CGI programs can be difficult because when they fail, very little information is displayed in the browser. All you see is a message like 500 server error, which no explanation of the real cause. However, more detailed error information is written to the Apache error log file. This is usually named error_log, and can be found in the same directory as the Apache access log files. See the section below on Configuring logging for more details on how to find and change it.

Anything that a CGI programs outputs to STDERR will also be written to the error log, which is useful if you want your program to generate debugging information that is not sent to the web browser. Because many programming languages like Perl output error messages on STDERR if a script fails to compile or run, all such messages will also be written to the error log file.

The biggest problem with CGI programs is that the webserver has to launch a new process every time one is requested. If the CGI is written in Perl or PHP, the process then has to load the interpreter for that language which can itself be a large program. The end result is that processing a request for a CGI page takes much longer than a request for a static HTML or image file, and generates much more load on the server system.

For this reason, optional modules have been developed that allow the webserver to run Perl and PHP scripts using an interpreter that is part of the Apache process. These modules are called mod_perl and mod_php, and are included in the Apache package in many Linux distributions. Installing and configuring them is not covered in this chapter though.

Setting up server-side includes

Server-side includes allow you to create simple dynamic web pages without the complexity of writing an entire CGI program in a language like Perl. When active, some of the HTML files served by Apache are checked for special tags starting with