12938
Comment: Removed 'handleMail' from Mailman example, because 'dom' already includes that.
|
13159
domNoDefaultAlias deprecated
|
Deletions are marked like this. | Additions are marked like this. |
Line 6: | Line 6: |
Line 8: | Line 7: |
Line 10: | Line 8: |
{{{dom "yourdomain" with end;}}} |
{{{ dom "yourdomain" with end;}}} Or, if you don't want all mail to be forwarded to your mailbox, use: {{{ dom "yourdomain" where DefaultAlias = false; with end;}}} |
Line 14: | Line 21: |
Line 16: | Line 22: |
{{{dom "yourdomain" with | {{{ dom "yourdomain" with |
Line 21: | Line 29: |
Line 23: | Line 30: |
Line 25: | Line 31: |
{{{dom "yourdomain" where | {{{ dom "yourdomain" where |
Line 37: | Line 45: |
Line 39: | Line 46: |
Line 41: | Line 47: |
{{{dom "yourdomain" where | {{{ dom "yourdomain" where |
Line 48: | Line 56: |
Line 50: | Line 57: |
{{{domain "yourdomain" with | {{{ domain "yourdomain" with |
Line 53: | Line 62: |
Line 55: | Line 63: |
Line 58: | Line 65: |
{{{domain "yourdomain" with | {{{ domain "yourdomain" with |
Line 62: | Line 70: |
Line 65: | Line 72: |
Line 68: | Line 74: |
Line 71: | Line 76: |
Line 74: | Line 78: |
Line 80: | Line 83: |
Line 82: | Line 84: |
Line 85: | Line 86: |
{{{domain "yourdomain" where | {{{ domain "yourdomain" where |
Line 90: | Line 92: |
Line 92: | Line 93: |
{{{domain "yourdomain" with |
{{{ domain "yourdomain" with |
Line 96: | Line 97: |
Line 99: | Line 99: |
Line 102: | Line 101: |
Line 105: | Line 103: |
Line 108: | Line 105: |
Line 111: | Line 107: |
Line 115: | Line 110: |
Line 117: | Line 111: |
.'''htaccess'''files are not processed on our servers. See examples(mod_rewrite, 404 handling, etc) below to learn how to use rewrite rules and other features normally provided by .'''htaccess'''. | |
Line 119: | Line 113: |
{{{domain "yourdomain" with |
{{{ domain "yourdomain" with |
Line 125: | Line 119: |
Line 129: | Line 122: |
{{{domain "yourdomain" with |
{{{ domain "yourdomain" with |
Line 134: | Line 127: |
Line 138: | Line 130: |
{{{domain "yourdomain" with |
{{{ domain "yourdomain" with |
Line 145: | Line 137: |
Line 147: | Line 138: |
Line 150: | Line 140: |
{{{domNoWww "yourdomain" with | {{{ domNoWww "yourdomain" with |
Line 156: | Line 147: |
Line 159: | Line 149: |
{{{domain "yourdomain" with | {{{ domain "yourdomain" with |
Line 166: | Line 157: |
Line 168: | Line 158: |
{{{domain "yourdomain" with |
{{{ domain "yourdomain" with |
Line 178: | Line 168: |
Line 182: | Line 171: |
{{{domain "yourdomain" with |
{{{ domain "yourdomain" with |
Line 191: | Line 180: |
Line 196: | Line 184: |
Line 201: | Line 188: |
Line 203: | Line 189: |
{{{domain "yourdomain" with |
{{{ domain "yourdomain" with |
Line 210: | Line 196: |
Line 217: | Line 202: |
Line 219: | Line 203: |
{{{domain "yourdomain" with |
{{{ domain "yourdomain" with |
Line 225: | Line 209: |
Line 228: | Line 211: |
Line 233: | Line 215: |
Line 237: | Line 218: |
{{{domain "yourdomain" with |
{{{ domain "yourdomain" with |
Line 242: | Line 223: |
Line 245: | Line 225: |
Line 248: | Line 227: |
Line 251: | Line 229: |
Line 254: | Line 231: |
Line 257: | Line 233: |
Line 261: | Line 236: |
Line 264: | Line 238: |
Line 269: | Line 242: |
Line 271: | Line 243: |
{{{domain "yourdomain" with |
{{{ domain "yourdomain" with |
Line 277: | Line 249: |
Line 280: | Line 251: |
Line 283: | Line 253: |
Line 286: | Line 255: |
Line 289: | Line 257: |
Line 292: | Line 259: |
Line 296: | Line 262: |
location "/loc2"; |
location "/loc2" with |
Line 301: | Line 266: |
Line 304: | Line 268: |
Line 307: | Line 270: |
Line 313: | Line 275: |
Line 315: | Line 276: |
{{{domain "yourdomain" with |
{{{ domain "yourdomain" with |
Line 320: | Line 281: |
Line 323: | Line 283: |
Line 326: | Line 285: |
Line 331: | Line 289: |
Line 333: | Line 290: |
{{{domain "yourdomain" with |
{{{ domain "yourdomain" with |
Line 338: | Line 295: |
Line 341: | Line 297: |
Line 346: | Line 301: |
Line 348: | Line 302: |
{{{domain "yourdomain" with |
{{{ domain "yourdomain" with |
Line 353: | Line 307: |
Line 358: | Line 311: |
Line 360: | Line 312: |
Line 366: | Line 317: |
{{{dom "yourdomain" with |
{{{ dom "yourdomain" with |
Line 371: | Line 322: |
Line 373: | Line 323: |
Line 375: | Line 324: |
Line 377: | Line 325: |
{{{dom "yourdomain" with |
{{{ dom "yourdomain" with |
Line 383: | Line 331: |
Line 385: | Line 332: |
{{{dom "yourdomain" with |
{{{ dom "yourdomain" with |
Line 389: | Line 336: |
Line 397: | Line 343: |
Line 399: | Line 344: |
Line 401: | Line 345: |
{{{dom "yourdomain" with |
{{{ dom "yourdomain" with |
Line 405: | Line 349: |
Line 409: | Line 352: |
{{{dom "yourdomain" with |
{{{ dom "yourdomain" with |
Line 413: | Line 356: |
Line 417: | Line 359: |
Line 421: | Line 362: |
Line 425: | Line 365: |
Line 427: | Line 366: |
In order to help you put all of the pieces together, some full working examples are available in [:/Full:separate subpage]. |
In order to help you put all of the pieces together, some full working examples are available in [:DomTool/Examples/Full:separate subpage]. |
Here are some example configuration files for DomTool, our distributed configuration management system.
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;
Or, if you don't want all mail to be forwarded to your mailbox, use:
dom "yourdomain" where DefaultAlias = false; 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
.htaccessfiles are not processed on our servers. See examples(mod_rewrite, 404 handling, etc) below to learn how to use rewrite rules and other features normally provided by .htaccess.
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" with 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 [:DomTool/Examples/Full:separate subpage].