1 Before continuing with this page, you probably want to read DomainTool to learn the basics of how we handle shared daemon configuration.
3 Any file in a domain's directory whose name is a valid hostname (i.e., `www`, `myhost`, etc.) is taken to be configuration for an Apache 2 virtual host. These are separate web sites that Apache serves, differentiated based on the hostname contained in a request.
5 In addition, a file named `name.ssl`, where `name` is a valid hostname, is taken to be an SSL virtual host.
7 Don't forget that creating a virtual host file '''does not add a DNS mapping'''. Your new virtual host will not work unless you add the appropriate DnsConfiguration directive.
9 '''A note on `.htaccess` files''': You'll probably find plenty of information on the web about configuring a shared Apache daemon using "`.htaccess` files." We ''don't'' allow this, because that facility really wasn't designed for our kind of environment; it makes it too easy to disrupt others' web sites. An example is the `RewriteRule` directive, which, combined with `mod_proxy`, allows you to send one of the Apache child processes into an infinite loop contacting itself. After enough hits to your web site, all child processes will be occupied talking to themselves, and so Apache will refuse to serve any pages. The `RewriteRule` directive below is checked to avoid this and other undesirable behaviors. Even for Apache directives that look safe, it's best to err on the side of caution and force everything to go through `domtool`, since they could change in upgrades, have subtle problems that we didn't realize, etc.. Giving each user a direct configuration input to a shared daemon just doesn't make security sense.
11 = Configuration directives =
13 The following configuration directives may appear on separate lines in such files.
15 == Grouping other directives ==
17 * `Location url_prefix`: This is like the Apache 2 `Location` directive. You specify a prefix of URLs to which you want to apply special configuration. Everything from this directive to the next `/Location` directive will apply to that set of URLs only.
18 * `Directory path`: Like the above, but for real filesystem paths. You can only use this for paths that you have access to via a `.paths` file.
22 * `Default`: Where the configuration file is describing `host.domain`, this sets `domain` by itself as an alternate name for this vhost.
23 * `ServerAlias hostname`: Serve requests for full hostname `hostname` with this same vhost. There must exist an appropriate `host.aliased` file corresponding to `hostname`. For example, if `hostname` is `my.web.site`, the file `/etc/domains/site/web/my.aliased[` must exist.
27 * `ErrorDocument code url`: This is the [http://httpd.apache.org/docs/2.0/mod/core.html#errordocument Apache ErrorDocument] directive verbatim.
28 * `ServerAdmin email`: Set the e-mail address of the vhost's admin to `email`. This will mainly be used in error pages to tell visitors to whom they should whine.
32 * `AddDefaultCharset something`: This is the [http://httpd.apache.org/docs/2.0/mod/core.html#adddefaultcharset Apache AddDefaultCharset] directive verbatim.
33 * `DocumentRoot dir`: Use `dir` as the base directory for site content.
34 * `HTML realdir`: Serve every file in `realdir` as HTML.
38 Currently, domtool isn't set up to accommodate members' SSL vhosts that won't trigger warning dialogs in standard browsers, saying that the certificate's name doesn't match the vhost's hostname. This is because SSL is applied at the IP address level, and our main IP address is already being used for members.hcoop.net. We '''can''' request additional IP addresses, but we have to go through a bureaucratic process regulated by ICANN to do so, so no one has yet thought it sufficiently important to do so. You could be the first.
40 * `SSLCertificateFile path`: Indicate where to find the SSL certificate to use for this vhost, which must be an SSL vhost. The certificate probably has a file extension like `.pem` (see UsingSsl). In the style of `.paths`, `.certs` files are associated with domains to provide information on which domains may use which certificates. We can't just let you reference arbitrary files as certificates because Apache will refuse to load if any vhosts happen to reference invalid certificates, which is a security problem for everyone. Therefore, if you want to use SSL, [https://members.hcoop.net/portal/support submit a support request] asking for your certificate to be installed. We'll put it somewhere where you can't modify it and then add it to `.certs` for your domain.
42 Anyone can use the members.hcoop.net certificate without special permission, since it is in `/etc/domains/.certs`.
46 * `BasicAuth password_file description`: This must be used inside a `Location` or `Directory` block. It describes how to authenticate users who want to access that part of your web site. `password_file` designates a password file created with Apache's `htpasswd` program. `description` (which may contain spaces) gives a description to be displayed when asking visitors to authenticate.
47 * `Block pattern`: Disallow access to the site for anyone from a hostname or IP address matching the `pattern`. The possibilities for `pattern` are described in [http://httpd.apache.org/docs/howto/auth.html#allowdeny the Apache docs for Deny]. Mixing this with `AbuPrivate` may give zany results.
48 * `Group group`: Run dynamic page generators (CGI, PHP, etc.) with UNIX group `group`. Your domain probably has a `.groups` files that declares at least one group that you may use. If so, then the default group is the alphabetically first of these, and this is used if you omit the `Group` directive. Otherwise, the default is `nogroup`, which will effectively prevent you from doing anything interesting. This directive also sets things up so that members of `group` can read the logfiles for this virtual host in `/var/log/apache2`. (E.g., `/var/log/apache2/your.host/access.log` and `/var/log/apache2/your.host/error.log`.) If the actual log file permissions end up out-of-synch with the directives, run the `logperms` program. The upside or downside of this log ownership (depending on your point of view) is that your domains' log files are counted toward your disk quota.
49 * `HcoopPrivate`: This is a special combined version of `BasicAuth`/`Require valid-user` that uses our HCoop web passwords file. The passwords are set using the `webpasswd` command-line program. Deny access if a correct username and password are not provided. For security reasons, this directive isn't allowed on non-SSL hosts.
50 * `Require group groups`: Only allow access to visitors in the given `htpasswd` groups, specified as a space-separated list.
51 * `Require user users`: Only allow access to visitors authenticated as the given `htpasswd` users.
52 * `Require valid-user`: Only allow access to visitors who can authenticate as some user.
53 * `User user`: Run dynamic page generators as UNIX user `user`. The default is the alphabetically first user that you're authorized to run as, or `nobody` if no such user exists. `nobody` isn't allowed to run CGI, so you can't do much if you fall into the second category.
54 * `WebalizerUsers userlist`: Only allow users in space-separated `userlist` to view the Webalizer statistics for this vhost.
55 * `LimitRequestBody bytes`: [http://httpd.apache.org/docs/2.0/mod/core.html#limitrequestbody The Apache directive] verbatim. Restricts the total size of the HTTP request body sent from the client, such as the size of POST data for a CGI script.
57 For step-by-step instructions to password protect a part of your website, see WebsitePasswordExample.
61 * `RewriteLogLevel n`: This is the [http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html#rewriteloglevel Apache 2 RewriteLogLevel directive]. By default, no rewrite logging is generated for vhosts. Including this directive turns on logging to `/var/log/apache2/<vhost>/rewrite.log`, at the specified level of verbosity.
65 * `Action`: The Apache 2 [http://httpd.apache.org/docs/2.0/mod/mod_actions.html#action Action] directive verbatim.
66 * `CGI dir`: This sets filesystem directory `dir` as a location of CGI scripts, such that any web requests serviced from this directory will run the scripts instead of returning their source code. You don't need to use it if you use `ScriptAlias` for each script.
67 * `Mailman`: Designate this host as allowed for Mailman web requests. You probably only want to use this if you have a mailing list for which you want web links to go to your domain instead of `hcoop.net`.
68 * `Mason cgi`: Sets all requests for `.html` files to be serviced by the given Mason CGI script, given as an absolute filesystem path.
69 * `Mod lang path handler`: Sets up a special Apache language module to handle scripts in the given URI directory `path`. `handlers` specifies a handler in a language-specific format. When `lang` is `python`, it is a source file name (relative to `path` and minus file extension) that handles the requests. When `lang` is `perl`, it's a Perl module name. No other languages are supported yet. ''(Actually, both languages are currently disabled while we figure out how to make them run scripts as the owning users.)''
70 * `MoinMoin url cgi`: A handy shortcut for setting up a MoinMoin wiki like this one. The parameters are treated in the same way as for `ScriptAlias` below, except that `cgi` should be a `moin.cgi` somewhere. In addition to what `ScriptAlias` would do, this directive also sets up mappings for the MoinMoin static content. See MoinMoinConfiguration for more info.
71 * `PerlINC path`; `PerlVersion filename`: These are [http://search.cpan.org/dist/Apache-PerlVINC-0.02/ Apache::VINC] directives.
72 * `PerlSetVar name value`: The Apache mod_perl directive verbatim
73 * `SSI`: Enable server-side includes for the entire vhost.
74 * `ScriptAlias url cgi`: This declares that `url` (probably beginning with a slash) should be handled by running a script found at filesystem path `cgi`. In fact, this is accomplished by a simple replacement in the URL, so `url` and `cgi` can be directories. This won't work if you haven't used the `User` and `Group` directives to set as whom your script should run.
76 == Special URL handling ==
78 * `Alias urldir realdir`: Serve requests for things in directory `urldir` out of `realdir`.
79 * `LocalProxy from to port`: This directive gives back some of the functionality of `RewriteRule` with the (disallowed) `P` flag. It calls another web server (probably one that you maintain yourself) running locally on `port` to handle certain requests. `from` is a regular expression pattern to match against requests in the style of `RewriteRule`. `to` is like the replacement for `RewriteRule`, except that it is not a full URL. Rather, when the rule is triggered, a proxy request is make to `localhost` on `port` for the path `/to` with variable replacements made. `port` may not be 80, since it's too easy to get accidental infinite loops that hang Apache for everyone this way.
80 * `LocalProxyPass from to port`: This is an alternate, simplified version of `LocalProxy` that you should use if you can. Instead of giving a pattern for `from`, instead give a URI prefix, like `/stuff/otherstuff/`. `to` should similarly be a URI prefix that applies on the local server that you want to receive proxy requests. In addition to what you'd expect with the equivalent `LocalProxy` directive, `LocalProxyPass` also includes rewriting URLs in HTTP headers generated by the proxy web server to avoid some errors that could result from its different point of view.
81 * `RewriteCond ...`: Passed directly to [http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html#rewritecond mod_rewrite].
82 * `RewriteRule ...`: These lines are passed verbatim to Apache's [http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html#rewriterule mod_rewrite], with some restrictions. First, if you want to pass multiple flags, you must use the `[FLAG1,FLAG2]` format instead of the `[FLAG1] [FLAG2]` format that Apache itself accepts. Second, the `P` and `N` flags are not allowed, to remove possibilities for infinite loops due to nothing but mod_rewrite's actions.
86 * `AddDescription file description`: The [http://httpd.apache.org/docs/2.0/mod/mod_autoindex.html#adddescription Apache directive] with slightly different syntax: you can only specify a single file pattern at a time, it comes before the description, and the description isn't in quotes.
87 * `IndexOptions options`: The [http://httpd.apache.org/docs/2.0/mod/mod_autoindex.html#indexoptions Apache directive] verbatim, currently only allowing the `FoldersFirst` and `SuppressColumnSorting` options.
88 * `HeaderName name`: The [http://httpd.apache.org/docs/2.0/mod/mod_autoindex.html#headername Apache directive] verbatim
89 * `ReadmeName name`: The [http://httpd.apache.org/docs/2.0/mod/mod_autoindex.html#readmename Apache directive] verbatim
90 * `NoAutoindex`: Disable mod_autoindex for this directory/location.
94 You may sometimes find it helpful to consult `/etc/apache2/vhosts.conf` to see how your changes affect the concrete Apache configuration.
96 The `Default` directive, by itself, causes Apache to respond identically to any requests for `host.domain/path` and `domain/path`. It's generally better for search engines and other spiders if you redirect all requests to `host.domain` to `domain` or vice versa. You can use `mod_rewrite` to do this:
102 # NC: match case-insensitively
103 # L: last rule; do not apply any more rewrite rules
104 # R=301: force an HTTP redirect with status code 301 (Moved Permanently)
105 RewriteCond %{HTTP_HOST} ^www.example.org$ [NC]
106 RewriteRule ^(.*) http://example.org$1 [NC,L,R=301]
HCoop / hcoop / zz_old / ikiwiki / blob