1 Here are some example configuration files for DomTool, our distributed configuration management system.
9 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:
10 {{{dom "yourdomain" with
13 == Upgraded Model T ==
15 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`:
16 {{{dom "yourdomain" with
18 (* More configuration could go here *)
22 == Attack of the Model T Clones ==
24 We can take the Model T and use it with some alternate names for the domain we're configuring.
25 {{{dom "yourdomain" where
26 Aliases = ["yourotherdomain", "yourotherotherdomain"]
29 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.
31 == The Do-It-Yourself ==
33 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:
34 {{{domain "yourdomain" with
35 (* Your directives here *)
40 Here's a tour through the available DNS features.
42 {{{domain "yourdomain" with
43 nameserver "ns1.hcoop.net";
44 nameserver "ns3.hcoop.net";
45 (* Specify two DNS servers that are authoritative for yourdomain *)
47 dnsIP "host" "1.2.3.4";
48 (* Add a mapping from host.yourdomain to IP address 1.2.3.4 *)
50 dnsMail 23 "mail.yourdomain";
51 (* Register mail.yourdomain as an SMTP handler for yourdomain, with priority 23 *)
53 dnsAlias "hcoop" "hcoop.net";
54 (* Add an alias such that hcoop.yourdomain resolves to the same thing as hcoop.net *)
56 dnsIP "dynamic" "5.6.7.8" where
59 (* Add an IP mapping with an abnormally low time-to-live of 100 *)
62 == Keeping DNS elsewhere ==
64 This example shows how to configure mail handling for a domain that is primarily hosted off of HCoop:
66 {{{domain "yourdomain" where
74 {{{domain "yourdomain" with
76 (* HCoop should provide relaying for yourdomain *)
78 emailAlias "user1" "user1@gmail.com";
79 (* Forward mail from user1@yourdomain to user1@gmail.com *)
81 emailAlias "user2" "me";
82 (* Forward mail from user2@yourdomain to HCoop user me *)
84 aliasMulti "pals" ["pal1@yahoo.com", "pal2@prodigy.com", "pal3"];
85 (* Forward mail from pals@yorudomain to pal1@yahoo.com, pal2@prodigy.com, and HCoop user pal3 *)
88 (* Silently drop all mail to spamtrap@yourdomain *)
91 (* Send all yourdomain mail that doesn't match some local user or other special rule to user me *)
94 (* Send all yourdomain mail, period, to user me *)
101 {{{domain "yourdomain" with
103 (* This is a web host found at www.yourdomain. *)
107 Note that the `web` directive also adds the right DNS mapping for your virtual host.
109 == The Do-It-Yourself ==
111 {{{domain "yourdomain" with
116 This one doesn't add any DNS mappings.
118 == Using a nonstandard web server ==
120 {{{domain "yourdomain" with
122 WebNodes = ["fyodor"]
127 == Bucking all the trends ==
129 {{{domain "yourdomain" with
131 DocumentRoot = home "private_html";
134 SSL = use_cert "/home/me/mycert.pem"
139 `home "private_html"` builds the full path to subdirectory `private_html` of your home directory.
141 == Basic URL handling ==
143 {{{domain "yourdomain" with
145 alias "/doc" "/usr/local/doc";
146 (* Serve all URIs beginning in /doc out of directory /usr/local/doc *)
148 scriptAlias "/my-script" "/var/cgi/a-program";
149 (* Handle requests for /my-script by calling the CGI program /var/cgi/a-program.
150 The example here uses a file, but scriptAlias directive can also alias CGI
151 directories, as you'd expect: scriptAlias "/location/" "/directory/" *)
153 errorDocument "404" "not_found.html";
154 (* Handle HTTP error code 404 by sending file not_found.html *)
158 == Location-specific configuration ==
160 {{{domain "yourdomain" with
162 location "/private" with
163 errorDocument "404" "not_found_private.html";
165 (* When in the /private tree of URI-space, handle 404s with not_found_private.html *)
167 directory "/usr/local/doc" with
168 errorDocument "404" "not_found_doc.html";
170 (* When looking for a file in real directory /usr/local/doc, handle 404s with not_found_doc.html *)
176 {{{domain "yourdomain" with
178 serverAliasHost "www2.yourdomain";
179 serverAliasHost "www.otherdomain";
180 (* www2.yourdomain and www.otherdomain are alternate names for this vhost *)
183 (* Short form for an alternate name within the current domain *)
186 (* Make this virtual host answer to yourdomain, with no extra hostname needed in front. *)
190 Note that you must have domtool configuration rights to all domains you name with `serverAlias`.
192 == Directory options ==
195 {{{domain "yourdomain" with
197 options [execCGI, indexes];
198 (* Use exactly the Apache options execCGI and indexes by default for this vhost *)
200 set_options [includesNOEXEC];
201 (* Add the option includesNOEXEC, leaving the others alone *)
203 unset_options [indexes];
204 (* Change our mind about including indexes *)
206 directoryIndex ["index.html", "index.php", "index.txt"];
207 (* When looking for the default file to serve for a directory, consider these possibilities in order *)
209 action "image/gif" "/cgi-bin/images.cgi";
210 (* Run /cgi-bin/images.cgi to serve images *)
212 addDefaultCharset "utf-8";
213 (* Use the UTF-8 character set by default *)
215 location "/prefix" with
216 forceType "text/plain";
217 (* Serve all files in this location as plain text *)
220 (* Change our mind about that! *)
222 (* All the other directives mentioned above can be used in locations, too, but forceType* _must_ be in a location. *)
229 {{{domain "yourdomain" with
231 location "/loc1" with
233 (* Use HTTP basic authentication in this location *)
235 authName "my domain";
236 (* Tell users that they're authenticating for "my domain" *)
238 authUserFile "/etc/webusers";
239 (* Look up user/password information in /etc/webusers *)
242 (* Access is denied by default *)
245 (* Anyone providing a valid password is allowed *)
247 denyFrom "badguys.evil.net";
248 (* However, anyone coming from this domain is banned *)
251 (* Also ban anyone with a 1.2.*.* IP address *)
256 authName "my other domain";
257 authUserFile "/etc/otherone";
260 (* Deny everyone by default *)
262 requireUser ["fred", "barney"];
263 (* Allow fred and barney in *)
265 requireGroup ["prehistoric"];
266 (* Also require membership in the prehistoric group *)
271 == Fancy directory index generation ==
273 {{{domain "yourdomain" with
275 addDescription "The planet Mars" "/web/pics/mars.gif";
276 (* Describe /web/pics/mars.gif as "The planet Mars" on index pages *)
278 indexOptions [fancyIndexing, htmlTable, iconHeight 10, iconWidth 10];
279 (* Set some index-generation options *)
281 headerName "header.html";
282 (* Include header.html at the start of a directory listing *)
284 footerName "footer.html";
285 (* Include footer.html at the end of a directory listing *)
291 {{{domain "yourdomain" with
293 rewriteRule "^(.+)\.php$" "$1.sml" [];
294 (* Rewrite all URLs ending in .php to end in .sml *)
296 rewriteRule "/gone.html" "http://somewhere.else/there.html" [redirectWith permanent];
297 (* Redirect /gone.html to http://somewhere.else/there.html, giving an HTTP code indicating a permanent relocation *)
300 (* Turn on some more logging for rewrite debugging in /afs/hcoop.net/usr/$USER/apache/log/$NODE/www.yourdomain/rewrite.log *)
306 {{{domain "yourdomain" with
308 proxyPass "/mirror/foo/" "http://localhost:5555/";
309 (* Proxy path /mirror/foo/ to a local server with URL base http://localhost:5555/ *)
311 proxyPassReverse "/mirror/foo/" "http://localhost:5555/";
312 (* Adjust Location and other HTTP headers appropriately for the above proxying *)
318 {{{domain "yourdomain" with
319 mailmanWebHost "lists.yourdomain";
320 (* The default server for web interfaces to this domain's mailing lists is lists.yourdomain *)
323 = Live Examples in HCoop AFS =
325 * /afs/hcoop.net/user/d/do/docelic/.domtool/spinlocksolutions.com