Here are some example configuration files for DomTool, our distributed configuration management system.

TableOfContents()

1. Domains

1.1. 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;}}}

1.2. 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;}}}

1.3. Model T with customized www.yourdomain

You wouldn't want to copy the last example with "www" instead of "other", because dom already creates a www vhost. Instead, there's a more convenient way to configure this most common of vhosts: {{{dom "yourdomain" where

• DocumentRoot = "/my/custom/docroot"; (* See "Bucking all the trends" in the Apache section for other options you can

  • use like DocumentRoot. *)

  WWW = begin
  • alias "/from" "/to"; alias "/from2" "/to2"; (* These are just examples. Arbitrary vhost config goes here. *)
  end

with

• (* And other domain configuration can go here, including more vhosts. *)

end;}}}

1.4. 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.

1.5. 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;}}}

2. DNS

Here's a tour through the available DNS features.

{{{domain "yourdomain" with

• nameserver "ns1.hcoop.net"; nameserver "ns3.hcoop.net"; (* Specify two DNS servers that are authoritative for yourdomain *) dnsDefault "69.90.123.68"; (* Add a mapping from yourdomain to IP address 69.90.123.68 *) 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;}}}

2.1. Keeping DNS elsewhere

This example shows how to configure mail handling for a domain that is primarily hosted off of HCoop:

{{{domain "yourdomain" where

• DNS = noDns

with

• handleMail;

end;}}}

3. 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;}}}

4. Apache

4.1. 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.

4.2. The Do-It-Yourself

{{{domain "yourdomain" with

• vhost "www" with end;

end;}}}

This one doesn't add any DNS mappings.

4.3. Using a nonstandard web server

{{{domain "yourdomain" with

• web "www" where

  • WebPlaces = [web_place_default "fyodor"]

  with end;

end;}}}

4.4. Using SSL

For this example, we assume that you've applied for and been granted permissions on the SSL certificate /etc/apache2/ssl/user/yourdomain.pem and the IP address 1.2.3.4 on mire.

{{{domNoWww "yourdomain" with

• webAtIp "1.2.3.4" "www" where
  • SSL = use_cert "/etc/apache2/ssl/user/yourdomain.pem"
  with end;

end;}}}

Here's how to do it with just a vhost.

{{{domain "yourdomain" with

• vhost "www" where

  • WebPlaces = [web_place web_node "1.2.3.4"]; SSL = use_cert "/etc/apache2/ssl/user/yourdomain.pem"

  with end;

end;}}}

4.5. 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.

4.6. 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.
    • Note that the second argument can't be just any old path. You need to have been granted permission to read from the path. You should have permission to read from any path within your home directory, as well as a few others, like /usr/share/moin. *)
    scriptAlias "/my-script" "/var/cgi/a-program"; (* Handle requests for /my-script by calling the CGI program /var/cgi/a-program.
    • The example here uses a file, but scriptAlias directive can also alias CGI directories, as you'd expect: scriptAlias "/location/" "/directory/" *)
    errorDocument "404" "not_found.html"; (* Handle HTTP error code 404 by sending file not_found.html *)
  end;

end;}}}

4.7. 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;}}}

4.8. 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.

4.9. 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;}}}

4.10. 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}}}

4.11. 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;}}}

4.12. 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;}}}

4.13. 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;}}}

5. Mailman

The following example will:

• Permit delivery of email of the form LIST@yourdomain to Mailman, provided that LIST is a valid Mailman list that you own.

• Set up a web interface at http://lists.yourdomain/listinfo, which contains a general overview of the lists that you own, and permits you to administer them.

• Add a valid DNS mapping for lists.yourdomain.

{{{dom "yourdomain" with

• mailman "lists"; (* The default server for web interfaces to this domain's mailing lists is lists.yourdomain *)

end;}}}

6. Common Web Applications

6.1. MoinMoin

6.1.1. A Standalone Site

{{{dom "yourdomain" with

• moinMoin "mywiki" where
  • Script = home "mywiki/moin.cgi"
  end

end}}}

6.1.2. Adding a Wiki to a Bigger Site

{{{dom "yourdomain" with

• web "mysite" with
  • (* Other normal web config goes here.... *) addMoinMoin where
    • Script = home "mywiki/moin.cgi"; Htdocs = "/where/static/content/is/accessed/in/URLs"; Prefix = "/url/prefix/for/wiki/page/names"
    end
  end

end}}}

6.2. WordPress

6.2.1. A Standalone Blog

{{{dom "yourdomain" with

• wordPress "myblog"

end}}}

Make sure you have the WordPress distribution installed at the appropriate DocumentRoot.

6.2.2. Adding a Blog to a Bigger Site

{{{dom "yourdomain" with

• web "mysite" with
  • (* Other normal web config goes here.... *) addWordPress "/url/prefix"
  end

end}}}

Make sure you have the WordPress distribution installed at the filesystem location implied by the URL prefix you choose.

7. Live Examples in HCoop AFS

This is a listing of files in the HCoop AFS area which contain in-production examples of DomTool configuration.

• /afs/hcoop.net/user/d/do/docelic/.domtool/spinlocksolutions.com

8. Putting It All Together

In order to help you put all of the pieces together, some full working examples are available in [:/Full:separate subpage].