Virtual Servers

The lower half of the Apache page contains a list of configured virtual servers. Each virtual server entry on this page shows the address and port the virtual server listens on, the server name, and the document root. Clicking on the icon for the virtual server will bring you to a page filled with many new options and many of the same options found in the Global section discussed earlier. The options that are repeated from that section generally behave the same, and so are not covered again.

Figure 7-8. Virtual Servers

apvirtual

It’s important to remember that each virtual server has its own configuration. While it is possible to set default behaviors by editing the Default server (the first in the list of Virtual Servers, each virtual server may have configuration directives that override the default behavior. Each may have its own directory structure, server settings, MIME types, logging configuration, and more. Apache provides near infinite options, and most of those can be applied to any individual virtual server, as well as to the server as a whole.

Log Files

Logs provide a window into the operation of your web server, and Apache provides a great set of logging options so you can keep up with what your server is up to. In short, Apache allows you to configure each virtual host as though it were an independent server. This includes the ability to independently log information to a separate file and in a custom format.

 

Caution

Beware that there are particular security issues associated with logging in Apache. Because any logging helper programs will be started as the user that started Apache (usually root), the program must be secure. A good resource for further security information is the Security Tips section of the official Apache Documentation.

Error log to – This sets where Apache sends error information for this virtual server. Usually this goes to the syslog daemon, which writes it to the primary web server error log. However, Apache can send this to an alternate logging program, or to a file. This option configures the ErrorLog directive, and usually defaults to logging to the syslog daemon, if available.

Browser log file – Here you can define whether Apache will keep logs of the user agents (browsers, most often, though robots and autodownloaders will show up also) that access the web server. This information is usually only of passing interest, except perhaps when you’re thinking of implementing some technology that is incompatible with some browsers (like Flash, Shockwave, and a host of lesser known and even less widely accessible data formats). Reviewing these logs will often remind you of what percentage of your clients such technologies may alienate. Agent information not logged by default. This option configures the AgentLog directive.

Default log format – This option allows you to configure Apache to write logs in an arbitrarily chosen format. If you want Apache to log in the Common Log Format you simply leave this on the default. However, to log in a different manner, you would select the Format choice, and fill in the field with either a nickname of a named log format (discussed next) or with a log format string. This option configures the CustomLog directive.

Named log formats – A named log format is a custom log format, as discussed above, that has been defined and given a nickname for use by other log directives. A custom log format is created by entering a series of variables to indicate the data fields that should be present and the order in which they will appear. For example, a custom log type that mimics the Common Log Format looks like this:

%h %l %u %t \"%r\" %>s %b

This option configures the LogFormat directive.

Access log files – Here, you can define additional locations, formats, or programs, for Apache to send logs to. Configuration is much like the Default log above, except that you may have any number of access log files. This allows you, for example, to log accesses of images to a separate file, or to log visits to another format for processing and analyses. This option correlates to the TransferLog directive. Beware that the same security implications that effect all of the other logging directives effect this option as well.

Don’t log references from – This option adds the hostnames provided to a list of hosts from whence referral information will not be logged. For example, if I wanted my web server at penguinfeet.org to ignore referrals from my other web page, swelltech.com, I would enter swelltech.com here. Then, my statistics wouldn’t be skewed by the large number of referrals from my own pages. This option correlates to the RefererIgnore directive.

Referer log file – Here you define where referer information is logged to. This can be a file, or a program. This option configures the RefererLog directive.

Document Options

Here you have access to many of the virtual server specific options that will effect permissions, locations, and behaviors.

The first field of this page has no label. It is the document root. This is usually set when the virtual server is created, and is created automatically by Webmin. This option correlates to the DocumentRoot directive.

User WWW directory – Here, you configure the location where users can publish HTML documents via Apache. The syntax has several forms that perform different types of expansion to create the actual path. First, a relative link, of the form htmldocs translates for user joe to ~joe/htmldocs. An absolute link, such as /usr/htmldocs will translate to /usr/htmldocs/joe. Finally, it is possible to use an * to represent the username in the translation. For example, /home/*/htmldocs, will translate to /home/joe/htmldocs. This option configures the UserDir directive.

The following fields are continued options connected to the above User WWW directory option. They control which users’ directories will have the translation performed. Selecting All users accessible means that for any username entered in the URL, the translation will occur and the users web directory will be browsable. All users except allows you to disallow some users, while the rest are translated. This could be used, for example, to disable the website of a user who violated the terms of service. Finally, Only users means that only those users explicitly named will have directory translation performed.

Per-directory options file – Here you can specify a filename to be checked for directory access options. Unless prohibited elsewhere in Apache’s configuration, options found in a file by this name in any directory will override the default permissions for that directory. For example, if I chose the filename .acl, and in one of my directories I created such a file that included instructions to Generate directory indexes, then for that directory such indexes would be generated. This would apply even if the default with to not generate indexes. If you are operating a virtual hosting server, this can allow your users to have some freedom in the behaviour of the web server for their individual site, without interfering with or altering the behaviour of other sites on the same server. This can be thought of as one more layer of the onion of configurability that is Apache. This option configures the AccessFileName directive and defaults to .htaccess.

Directory options – Here, you can choose to use the default options for this directory. This effects the root directory for your virtual server and all subdirectories, except those the contain and AccessFileName file as discussed in the Per-directory options file section above. This option correlates to the Options directive and defaults to all, except for Generate Multiviews.

The available directory options are as follows:

 

Available directory options

Execute CGI programs

Allows execution of CGI scripts located in this directory.

Follow symbolic links

The server will follow symbolic links in this directory. This correlates to the ExecCGI directive.

Server-side includes and execs

Server-side includes are permitted. This correlates to the FollowSymLinks directive.

Server-side includes

Permits server side includes, but disallows #exec command and the use of #include for CGI scripts. This correlates to the IncludesNOEXEC directive.

Generate directory indexes

When a URL maps to a directory in which there is no index html file (usually index.html, but this is a configurable option), then Apache can generate a formatted file list for the directory. This option correlates to the Indexes directive.

Generate Multiviews

Content negotiated multiviews are permitted. This allows for multiple languages, character sets, a presentations to be referenced by the same URL. The client browser then negotiates with the server to select the appropriate one for the user. For more, see Content Negotation. This option correlates to the MultiViews directive.

Follow symbolic links if owners match

Apache will only follow symbolic links for which the target file or directory ownership matches that of the link. This option correlates to the SymLinksIfOwnerMatch directive.

Note that if multiple items apply (inherited from a parent directory), then the ones specific to the selected directory apply, unless Merge with parent is selected. For example, if /home/httpd/penguinfeet has All permissions, but the subdirectory /home/httpd/penguinfeet/users has only ExecCGI, then that directory would only have the execute CGI option available. Merging with the parent however, gives the subdirectory the same options, except where explicitly turned off.

Generate MD5 digests – This option turns on generation of Conten-MD5 digest headers. When enabled, Apache will generate a message digest, or fingerprint, for each static page served. When using MD5 digests, the client can be assured with a very high degree of confidence that if the content has been altered during transit from the origin server those alterations will be reflected in alterations in the message digest. The Content-MD5 standard is described in RFC 1864 and RFC 2616. This option configures the ContentDigest directive. Be aware that this option can have performance implications, since the digest is generated for each request, and digests will not be created for any requests that are served by modules.

Virtual server path – Very old browsers and proxies cannot address name based virtual servers, and know only how to request a site by its IP. This leads to the unfortunate effect that those browsers will only be able to reach the default website on a given IP. A workaround for this problem, is to provide a path from the default server to each virtual server. Using this directive, you can define where in the path of the default server this particular virtual server will reside. So, if my virtual server www.penguinfeet.org resides on a server at IP 123.45.67.89, and an older browser visits that name, it will end up browsing to the default server on the host–which can provide the user with a list of links to virtual servers hosted on this server. If this were set to /penguinfeet, the link would then take the user to http://www.penguinfeet.org/penguinfeet/ which is the correct page! Not exactly pretty, but the web wasn’t always as well thought out as it is today. And who can blame the original designers of the web for not realizing the one day everyone would have their own domain name! The good news is that those old web clients are simply no longer in use in any statistically significant quantity (they don’t show up on any of my webserver logs, anyway, your mileage may vary). This option configures the ServerPath directive. For more on Virtual Hosts and the potential issues, see also the Apache Virtual Host Documentation.

Error message footer – This option allows you to add a footer to all server generated documents (such as error pages, mod_proxy ftp directory listings, mod_info output, etc.). This is usually only needed when your Apache is acting as a proxy, as it is most useful in discovering where are error message originates from in a chain of multiple proxies. This option configures the ServerSignature directive and defaults to Off.

Default base for imagemaps – This option sets the base directory for image maps. If this is not set, the default is http://servername/. This correlates to the ImapBase directive.

Default action for imagemaps – Sets the default used in imagemap files. This will be overridden by a default directive within the imagemap file. The default is nocontent or Do nothing which sends a 204 No content message to the browser. The browser should continue to display the original page. This option correlates to the ImapDefault directive.

Action on incorrect use of imagemaps – This option determines what action Apache should take if an imagemap file is called without valid coordinates. This correlates to the ImapMenu directive. The options are as follows:

 

Imap Menu Options

none

If ImapMenu is none, no menu is generated, and the default action is performed.

Show formatted menu

A formatted menu is the simplest menu. Comments in the imagemap file are ignored. A level one header is printed, then an hrule, then the links each on a separate line. The menu has a consistent, plain look close to that of a directory listing.

Show semi-formatted menu

In the semiformatted menu, comments are printed where they occur in the imagemap file. Blank lines are turned into HTML breaks. No header or hrule is printed, but otherwise the menu is the same as a formatted menu.

Show unformatted menu

Comments are printed, blank lines are ignored. Nothing is printed that does not appear in the imagemap file. All breaks and headers must be included as comments in the imagemap file. This gives you the most flexibility over the appearance of your menus, but requires you to treat your map files as HTML instead of plaintext.

For more on imagemap files in Apache visit the mod_imap Module documentation.

Error Handling

In the event of a server error, Apache can be configured to provide custom error messages, or redirect to a local or external URL, or by default output a simple hardcoded error message. Here, you may configure any error types for which you’d like to provide a custom message. So, for example, if you wanted a custom 404 message that directed users to a local site search page (a convenient and polite thing to do), you could do that on this page. To configure the custom error responses feature of Apache, simply enter to error code, and then enter the URL or message to be displayed. See the Custom error responses documentation for more on this feature.

User and Group

This page configures the user and group under which the Apache server will run. This sets the priviledges the Apache and child processes will have while operating. It is strongly suggested that you set this to a user and group with as little priviledge as possible (while still allowing the server to do its job). This is often configured to nobody and nogroup on many Unix operating systems, and this is a good choice in most cases. Do not set this to root unless you know exactly what you’re doing, and the security implications of doing so. Note that the Apache parent process, if started as root, will remain as root, while the child processes that actually service requests will run as the user and group set here. If the parent process is started by a non-root user, Apache will not be able to su to another user, and so will run as the user that started the process. This option configures the User and Group directives.

Aliases and Redirects

Apache provides several forms of alias and redirection. This allows you to present more unified or simpler paths to your users in the URL, as well as serve objects from outside of your servers root directory. It also allows you to redirect users to a new website during a transition period, or direct their browser to the correct link if directory structure has changed.

Document directory aliases – This allows objects to be stored in directories other than the root directory. Be aware the aliases that end in a / will require the slash in the requested URL to be translated. This option correlates to the Alias directive.

Regexp document directory aliases – This option is very similar to the above, except that it allows the use of regular expressions to match paths to be translated. This option correlates to the AliasMatch directive. For more on regular expressions, consult the regex manpage.

URL redirects – This option redirects an old URL into a new one. The new URL is returned to the client, which will attempt to fetch again with the new address. You can also specify a status message for thie redirect, which can be one of several HTTP status codes, as described below. This option configures the Redirect directive.

 

Redirect status codes

301

Moved permanently.

302

Moved temporarily.

303

See other, meaning the resources has been replaced.

410

The object is no longer available. When this status is used, the redirect To URL should be omitted.

Regexp URL redirects – This option behaves exactly like the above, except the From field can contain a regular expression to match. This option correlates to the RedirectMatch directive.

Permanent URL redirects – This option behaves as the above URL Redirect with a status of 301 (moved permanently). Correlates to the RedirectPermanent directive.

Temporary URL redirects – This option behaves as the above URL Redirect with a status of 302 (moved temporarily). Correlates to the RedirectTemp directive.

Map local to remote URLs – This option allows a remote server to be mapped onto the space of the local server; the local server does not act as a conventional proxy, but appears to be a mirror of the remote server. For example, if the Local URL is /mirror/otherdomain and the Remote URL is http://www.otherdomain.com then users will be able to access http://www.otherdomain.com via http://www.thisdomain.com/mirror/otherdomain. This option corresponds to the ProxyPass directive.

Map remote Location: headers to local – This option provides roughly the reverse functionality of the previous option. It adjusts the location header on HTTP redirect responses, which is necessary when Apache is being used as a reverse proxy in order to avoid having the reverse proxy bypassed by a redirect request. This option configures the ProxyPassReverse directive.

Directory Indexing

An index in Apache, is simply a page that is displayed when a client browses to a directory on the server rather than an object or document. For example, if someone browses to my Squid patches directory on my server, which is located at http://www.swelltech.com/pengies/joe/patches/, Apache will serve an index page. If there is no file in the directory that matches Apache’s definition of an index page, it will instead generate an index page containing a file list, or it will serve an error page, if index generation is prohibited. This page allows you to configure the behavior of Apache when displaying index pages.

Directory index options — This option sets the appearence and information contained in Apache-generated indexes. This option configures the IndexOptions directive. The following options are available:

 

Display fancy directory indexes

This turns on fancy indexing of directories, which means that icons will be provided for files and directories. This configures the FancyIndexing subdirective.

Display HTML title as description

If files within the directory contain HTML title information, those titles will be displayed as the filenames for their respective files. This option configures the ScanHTMLTitles subdirective.

Icon height

This sets the height of the icons in fancy directory listings. This correlates to the IconHeight subdirective.

Icon width

This sets the width of the icons in fancy directory listings. This correlates to the IconWidth subdirective.

Allow user sorting of columns

By default, Apache will generate listings that can be sorted by the user by clicking the column headings. If you do not wish for users to be able to sort by last-modified date, or size, then you may disable this, and no sorting links will be provided. This option configures the SuppressColumnSorting subdirective.

Show file descriptions

Enable this to display descriptions of the files in the fancy index listings. This option correlates to the SuppressDescription subdirective.

Output HTML header tags

If using a header file (also configured on this page) for directory indexes, you may choose to allow Apache to output a standard HTML preamble containing enough to start a legal HTML page. If this is disabled, your header will have to contain its own preamble to make it into a legal HTML page. This option configures the SuppressHTMLPreamble subdirective.

Show last modified times

By default, Apache will display the last modified time of each file in a generated index. Unselecting this option will cause Apache not to do so. This option configures the SuppressLastModified subdirectory.

Show file sizes

This option is much like the previous option, except that it allows you to disable display of the size information about the files listed in a generated index. This option correlates to the SuppressSize subdirective.

Include icon in link

This will cause Apache to display icons as part of the link. This option configures the IconsAreLinks subdirective.

Filename width

Here you may configure the number of characters Apache will display in the filename of indexes. This option correlates to the NameWidth= subdirective. If this is set to * Apache will set the length to the length of the longest filename in the directory.

Description width

The number of characters that will be displayed in the description field of generated indexes. This option correlates to the DescriptionWidth= subdirective. As above, if this value is set to * the description length will be set to that of the longest description in the directory.

Display directories first

You may choose to have Apache sort the listing such that directories are listed first in the index. This option corresponds to the FoldersFirst subdirective.

Directory index files — Here you configure the filenames that Apache will look for when entering a directory, and if one of them exists it will be displayed as the index of the directory rather than an autogenerated file index. This file will be displayed to clients who request any directory on the server by specifying a / at the end of the URL. This may be any filename or list of filenames, though those used by convention include index.html or index.htm on operating systems with filename limitations. It is now not uncommon to use script suffixes on inedex pages, such as index.plindex.cgi, or index.php. This option correlates to the DirectoryIndex directive.

Files to ignore in directory index — If an autogenerated index is being displayed, you may specify files that are not to be listed in the index. This option configures the IndexIgnore directive.

Directory index default icon — Apache will automatically add icons to index listings when the file types of files are recognized. When no icon is known for a file type, you may configure an icon to be displayed here. This option correlates to the DefaultIcon directive.

Directory index header file — Indexes may have a custom header file attached to them using this option. The file may either be a plain text file, or an HTML file. This option correlates to the HeaderName directive.

Directory index footer file — Sets the path to the file to append to the end of an index. This option corresponds to the ReadmeName directive.

Sort directory index by — This option allows you to select how Apache will sort the entries on the index page. The order may be Ascending or Descending, and it may sort based on the Name of the file, Date of last modification, Size of the file, or the Description of the file. This option correlates to the IndexOrderDefault directive and defaults to sorting by filename in ascending order.

Directory index icons — Here you may select the graphic icons that will be displayed beside filename links in the fancy directory listing index pages. The Icon is the relative path to the image file. The Alt text is the text to be displayed if the clients browser does not support images. Match by is the attribute to match against when deciding which icon will be displayed, and it can be one of FilenameMIME type, or Encoding. The Filenames, Types, or Encodings is simply the terms to be matched for this icon type to be displayed. This option configures the AddIconAddIconByEncoding, and AddIconByType directives. When matching against the filename of the MIME type, you can use wildcards to matchany of several variations. For example, to match all backup files (as generated by ispell and other software), you could use the file match *~. Or, for a MIME type wildcard example, to match all images types, you could use image/*. It is generally recommended to match based on the MIME type rather than file extensions, when possible, as it tends to be less prone to missing files of certain types or misidentifying a filetype.

 

Note

When adding a filename matched icon, there are a couple of special names that allow you to match directories and blank lines (Apache uses blank lines to format the list). These are ^^DIRECTORY^^ and ^^BLANKICON^^, respectively.

Directory index ALT tags — Much like the previous option, this option allows you to configure the text to be displayed for files instead of icons. The possible values and wildcard usage are the same as for the previous option. This configures the <AddAltAddAltByEncoding, and AddAltByType directives.

Directory index descriptions — Here you may define what descriptions will be displayed for a given filename extension. The length of this will be limited by the Description width option discussed above. This option configures the AddDescription directive.

Proxying

This page configures the mod_proxy module, which allows Apache to act as a full featured HTTP proxy. While Squid is a higher performance and more featureful option in most cases, Apache can also provide some interesting functions and features for proxying and reverse proxying in very simple environments. For additional information on proxying with mod_proxy see the mod_proxy module documentation. Generally, however, if you need HTTP proxying, or web caching, Squid is a far better choice, and usually no more complicated to configure.

Act as proxy server? – This option simply turns proxying on or off in Apache. This is not required for passing requests on to another server using the ProxyPass directive, which was documented briefly in the Directory Options section, and also is configurable on this page. This option correlates to the ProxyRequests directive, and defaults to off

Cache directory – This option sets the directory where cached files will be stored. This directory must be writable by the server. If this option is not set, proxying will still function, but not caching will occur. This option correlates to the CacheRoot directive and defaults to none.

Block requests to domains – Provides a simple means of access control, wherein any domain or domain containing a word listed will be inaccessible through the proxy. The sites listed will be blocked even if the site is accessed via IP address, as Apache will resolve the names on startup and cache the IP information. This option correlates to the ProxyBlock directive and defaults to none.

Requests to pass to another proxy – This option configures remote proxies that requests will be sent to if the request contains the words or domains in the match field. This option correlates to the ProxyRemote directive and defaults to none.

Don’t pass requests to another proxy for – Here you can configure any number of domains, IP addresses, IP subnets, or hostnames that will not be forwarded to another proxy via the above option. This option correlates to the NoProxy directive, and defaults to none.

Domain for requests with no domain – This option is useful for proxy servers on intranets. It allows you to configure a domain name to be redirected to if a request is encountered without one. This option correlates to the ProxyDomain directive and defaults to none.

Domains not to cache – If caching is enabled above, here you can select some number of domains that will not be stored on the local proxy. This is useful for local domains, for which no benefit would be gained by locally caching the content thereof. This option configures the NoCache directive and defaults to none.

Ports to which CONNECT is allowed – This option dictates which ports Apache will allow the proxy CONNECT method on. This method is used to set up a tunnel for https connections. This option correlates to the AllowCONNECT directive and defaults to ports 443 (https) and 563 (snews). Enabling this option overrides the default, so if you add ports here, you must include at least the https port for secure connections to work corrcetly through your proxy.

Cache default expiry time – If an object is fetched via a protocol that does not support expiry times (such as ftp), or no expiry time is present, the cached data will be stored the specified number of hours. This option configures the CacheDefaultExpire and defaults to 1 hour.

Cache directory name length – Sets the number of characters in proxy cache subdirectory names. This option correlates to the CacheDirLength directive and defaults to 1.

Cache directory levels – Sets the number of levels in the proxy cache subdirectory hierarchy. This option correlates to the CacheDirLevels directive and defaults to 3.

Finish and cache transfer after – If a transfer is cancelled before completion, but after this percentage of the object has been received, Apache will continue to fetch the object in order to cache the complete object. Entering 0 here will cause the default to be used, and 100 will not store an object unless the whole transfer was completed. A number between 60 and 90 is suggested. This option configures the CacheForceCompletion and defaults to 90.

Cache garbage collection interval – If this is configured, Apache will perform periodic garbage collection, wherein it deletes files if the space used for cached objects is greater than the configured Cache size. This option accepts floating point values, so can be configured to perform garbage collection every 30 minutes, for example, by entering 0.5 here. If this is unset, the cache will grow indefinitely. This option configures the CacheGcInterval and defaults to none.

Cached file expiry time factor – If the origin HTTP server does not provide an expiry time for the object, Apache can estimate one by multiplying the time since the last modification by this factor. This option configures the CacheLastModifiedFactor directive, and defaults to 0.1.

Cached file maximum expiry time – After an object has been stored for this many hours, Apache will check for new content with the origin server, even if the expiry time supplied by the origin server has not yet been reached. This option configures the CacheMaxExpire directive and defaults to 24 hours.

Cache size – Assuming garbage collection has been configured, Apache will restrict the size of the cached object storage directories to this number of kilobytes. This option correlates to the CacheSize directive and defaults to 5 KB.

Server Configuration

This page allows you to reconfigure the basic configuration details of your virtual server. For example, if when you created your virtual server you placed it on port 8080 for testing, but now want to move it over to port 80 for production, you can perform that update here.

Address and Port – If your system has multiple interfaces, Apache will answer on any of them by default on port 80. However, you can configure your virtual server to only answer on one address using this option. You can also configure a different port here.

Document Root – This is the root directory, from whence the paths to access objects on your server will begin. This option configures the DocumentRoot directive.

Server Name – When using name based virtual servers, this name should match the name under which this server should answer. This is also used when creating redirection URLs. If not specified Apache will try to deduce it from the IP address, which isn’t always reliable. This option correlates to the ServerName directive.