Here are some example configuration files for DomTool, our distributed configuration management system. [[TableOfContents()]] = Domains = == The Model T == If you just want to declare your domain with a `www.yourdomain` virtual host serving out of `~/public_html/` and all mail forwarded to your mailbox, use: {{{dom "yourdomain" with end;}}} == Upgraded Model T == If you like everything `dom` gives you but want to add additional configuration, include it between `with`..`end`. For instance, to add an extra web virtual host `other`: {{{dom "yourdomain" with web "other" with (* More configuration could go here *) end; end;}}} == Attack of the Model T Clones == We can take the Model T and use it with some alternate names for the domain we're configuring. {{{dom "yourdomain" where Aliases = ["yourotherdomain", "yourotherotherdomain"] with end;}}} A single Apache virtual host is created, answering to multiple names. Other configuration is duplicated like you had entered it in a separate `dom` block for each alias. == The Do-It-Yourself == The lowest-level way of configuring a domain is the `domain` directive, which does nothing but set up basic DNS parameters and provide a space for including further directives: {{{domain "yourdomain" with (* Your directives here *) end;}}} = DNS = Here's a tour through the available DNS features. {{{domain "yourdomain" with nameserver "ns.hcoop.net"; nameserver "ns2.hcoop.net"; (* Specify two DNS servers that are authoritative for yourdomain *) dnsIP "host" "1.2.3.4"; (* Add a mapping from host.yourdomain to IP address 1.2.3.4 *) dnsMail 23 "mail.yourdomain"; (* Register mail.yourdomain as an SMTP handler for yourdomain, with priority 23 *) dnsAlias "hcoop" "hcoop.net"; (* Add an alias such that hcoop.yourdomain resolves to the same thing as hcoop.net *) dnsIP "dynamic" "5.6.7.8" where TTL = 100 end; (* Add an IP mapping with an abnormally low time-to-live of 100 *) end;}}} = Mail = {{{domain "yourdomain" with handleMail; (* HCoop should provide relaying for yourdomain *) emailAlias "user1" "user1@gmail.com"; (* Forward mail from user1@yourdomain to user1@gmail.com *) emailAlias "user2" "me"; (* Forward mail from user2@yourdomain to HCoop user me *) aliasMulti "pals" ["pal1@yahoo.com", "pal2@prodigy.com", "pal3"]; (* Forward mail from pals@yorudomain to pal1@yahoo.com, pal2@prodigy.com, and HCoop user pal3 *) aliasDrop "spamtrap"; (* Silently drop all mail to spamtrap@yourdomain *) defaultAlias "me"; (* Send all yourdomain mail that doesn't match some local user or other special rule to user me *) catchAllAlias "me"; (* Send all yourdomain mail, period, to user me *) end;}}} = Apache = == The Model T == {{{domain "yourdomain" with web "www" with (* This is a web host found at www.yourdomain. *) end; end;}}} Note that the `web` directive also adds the right DNS mapping for your virtual host. == The Do-It-Yourself == {{{domain "yourdomain" with vhost "www" with end; end;}}} This one doesn't add any DNS mappings. == Using a nonstandard web server == {{{domain "yourdomain" with web "www" where WebNodes = ["fyodor"] with end; end;}}} == Bucking all the trends == {{{domain "yourdomain" with web "www" where DocumentRoot = home "private_html"; User = "me_web"; Group = "me_web"; SSL = use_cert "/home/me/mycert.pem" with end; end;}}} `home "private_html"` builds the full path to subdirectory `private_html` of your home directory. == Basic URL handling == {{{domain "yourdomain" with web "www" with alias "/doc" "/usr/local/doc"; (* Serve all URIs beginning in /doc out of directory /usr/local/doc *) scriptAlias "/my-script" "/var/cgi/a-program"; (* Handle requests for /my-script by calling the CGI program /var/cgi/a-program *) errorDocument "404" "not_found.html"; (* Handle HTTP error code 404 by sending file not_found.html *) end; end;}}} == Location-specific configuration == {{{domain "yourdomain" with web "www" with location "/private" with errorDocument "404" "not_found_private.html"; end; (* When in the /private tree of URI-space, handle 404s with not_found_private.html *) directory "/usr/local/doc" with errorDocument "404" "not_found_doc.html"; end; (* When looking for a file in real directory /usr/local/doc, handle 404s with not_found_doc.html *) end; end;}}} == Server aliases == {{{domain "yourdomain" with web "www" with serverAliasHost "www2.yourdomain"; serverAliasHost "www.otherdomain"; (* www2.yourdomain and www.otherdomain are alternate names for this vhost *) serverAlias "www3"; (* Short form for an alternate name within the current domain *) serverAliasDefault; (* Make this virtual host answer to yourdomain, with no extra hostname needed in front. *) end end;}}} Note that you must have domtool configuration rights to all domains you name with `serverAlias`. == Directory options == {{{domain "yourdomain" with web "www" with options [execCGI, indexes]; (* Use exactly the Apache options execCGI and indexes by default for this vhost *) set_options [includesNOEXEC]; (* Add the option includesNOEXEC, leaving the others alone *) unset_options [indexes]; (* Change our mind about including indexes *) directoryIndex ["index.html", "index.php", "index.txt"]; (* When looking for the default file to serve for a directory, consider these possibilities in order *) action "image/gif" "/cgi-bin/images.cgi"; (* Run /cgi-bin/images.cgi to serve images *) addDefaultCharset "utf-8"; (* Use the UTF-8 character set by default *) location "/prefix" with forceType "text/plain"; (* Serve all files in this location as plain text *) forceTypeOff; (* Change our mind about that! *) (* All the other directives mentioned above can be used in locations, too, but forceType* _must_ be in a location. *) end; end; end;}}} == Access control == {{{domain "yourdomain" with vhost "www" with location "/loc1" with authType basic; (* Use HTTP basic authentication in this location *) authName "my domain"; (* Tell users that they're authenticating for "my domain" *) authUserFile "/etc/webusers"; (* Look up user/password information in /etc/webusers *) orderAllowDeny; (* Access is denied by default *) requireValidUser; (* Anyone providing a valid password is allowed *) denyFrom "badguys.evil.net"; (* However, anyone coming from this domain is banned *) denyFrom "1.2"; (* Also ban anyone with a 1.2.*.* IP address *) end; location "/loc2"; authType basic; authName "my other domain"; authUserFile "/etc/otherone"; denyFromAll; (* Deny everyone by default *) requireUser ["fred", "barney"]; (* Allow fred and barney in *) requireGroup ["prehistoric"]; (* Also require membership in the prehistoric group *) end; end; end}}} == Fancy directory index generation == {{{domain "yourdomain" with web "www" with addDescription "The planet Mars" "/web/pics/mars.gif"; (* Describe /web/pics/mars.gif as "The planet Mars" on index pages *) indexOptions [fancyIndexing, htmlTable, iconHeight 10, iconWidth 10]; (* Set some index-generation options *) headerName "header.html"; (* Include header.html at the start of a directory listing *) footerName "footer.html"; (* Include footer.html at the end of a directory listing *) end; end;}}} == mod_rewrite == {{{domain "yourdomain" with web "www" with rewriteRule "^(.+)\.php$" "$1.sml" []; (* Rewrite all URLs ending in .php to end in .sml *) rewriteRule "/gone.html" "http://somewhere.else/there.html" [redirectWith permanent]; (* Redirect /gone.html to http://somewhere.else/there.html, giving an HTTP code indicating a permanent relocation *) rewriteLogLevel 1; (* Turn on some more logging for rewrite debugging in /afs/hcoop.net/usr/$USER/apache/log/$NODE/www.yourdomain/rewrite.log *) end; end;}}} == mod_proxy == {{{domain "yourdomain" with vhost "www" with proxyPass "/mirror/foo/" "http://localhost:5555/"; (* Proxy path /mirror/foo/ to a local server with URL base http://localhost:5555/ *) proxyPassReverse "/mirror/foo/" "http://localhost:5555/"; (* Adjust Location and other HTTP headers appropriately for the above proxying *) end; end;}}} = Mailman = {{{domain "yourdomain" with mailmanWebHost "lists.yourdomain"; (* The default server for web interfaces to this domain's mailing lists is lists.yourdomain *) end;}}}