welcome: please sign in

Diff for "DomTool/Examples"

Differences between revisions 4 and 35 (spanning 31 versions)
Revision 4 as of 2006-12-17 22:22:14
Size: 6674
Editor: AdamChlipala
Comment: More Apache examples
Revision 35 as of 2007-12-16 22:19:40
Size: 13532
Editor: AdamChlipala
Comment: cgiExtension
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:
== 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;}}}
== 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.
Line 23: Line 56:
Line 25: Line 57:
{{{domain "yourdomain" with
{{{
domain "yourdomain" with
Line 28: Line 62:
Line 30: Line 63:
Line 33: Line 65:
{{{domain "yourdomain" with
  nameserver "ns.hcoop.net";
  nameserver "ns2.hcoop.net";
{{{
domain "yourdomain" with
  nameserver "ns1.hcoop.net";
  nameserver "ns3.hcoop.net";
Line 37: Line 70:
  dnsDefault "69.90.123.68";
  (* Add a mapping from yourdomain to IP address 69.90.123.68 *)
Line 40: Line 74:
Line 43: Line 76:
Line 46: Line 78:
Line 51: Line 82:
end;}}}

  (* IPv6 alternatives to some of the above *)
  dnsIPv6 "host" "1111:2222:3333:4444:5555:6666:7777:8888";
  dnsDefaultv6 "1111:2222:3333:4444:5555:6666:7777:8888";
end;}}}
== 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;}}}
Line 54: Line 97:

{{{domain "yourdomain" with
{{{
domain "yourdomain" with
Line 58: Line 101:
Line 61: Line 103:
Line 64: Line 105:
Line 67: Line 107:
Line 70: Line 109:
Line 73: Line 111:
Line 77: Line 114:
Line 79: Line 115:
.'''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 81: Line 117:

{{{domain "yourdomain" with
{{{
domain "yourdomain" with
Line 87: Line 123:
Line 91: Line 126:

{{{domain "yourdomain" with
{{{
domain "yourdomain" with
Line 96: Line 131:
Line 100: Line 134:

{{{domain "yourdomain" with
{{{
domain "yourdomain" with
Line 103: Line 137:
    WebNodes = ["fyodor"]     WebPlaces = [web_place_default "fyodor"]
Line 108: Line 142:
== 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.

{{{
dom "yourdomain" where
  CreateWWW = false;
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;}}}
Line 110: Line 167:
{{{domain "yourdomain" with {{{
domain "yourdomain" with
Line 112: Line 170:
    DocumentRoot = "/some/random/directory";     DocumentRoot = home "private_html";
Line 115: Line 173:
    SSL = true     SSL = use_cert "/home/me/mycert.pem"
Line 120: Line 178:
`home "private_html"` builds the full path to subdirectory `private_html` of your home directory.
Line 121: Line 181:

{{{domain "yourdomain" with
{{{
domain "yourdomain" with
Line 125: Line 185:
    (* Serve all URIs beginning in /doc out of directory /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. *)
Line 128: Line 191:
    (* Handle requests for /my-script by calling the CGI program /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/"
*)
Line 134: Line 198:
Line 136: Line 199:

{{{domain "yourdomain" with
{{{
domain "yourdomain" with
Line 143: Line 206:
Line 148: Line 210:
  end;
end;}}}
    location "/cgi-bin" with
       options [execCGI];
       cgiExtension "cgi"
    end;
    (* Any path like /cgi-bin/*.cgi should be executed as a CGI script. *)
  end;
end;}}}
Line 152: Line 218:

{{{domain "yourdomain" with
  web "www" with
    serverAlias "www2.yourdomain";
    serverAlias "www.otherdomain";
{{{
domain "yourdomain" with
  web "www" with
    serverAliasHost "www2.yourdomain";
    serverAliasHost "www.otherdomain";
Line 158: Line 224:
  end
end;}}}
    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;}}}
Line 164: Line 233:


{{{domain "yourdomain" with
{{{
domain "yourdomain" with
Line 170: Line 238:
Line 173: Line 240:

unset_options [indexes];
    (* Change our mind about including indexes *)
    unset_options [followSymLinks];
    (* Ask not to follow symbolic links. *)
Line 179: Line 244:
Line 182: Line 246:
Line 185: Line 248:
Line 189: Line 251:
Line 192: Line 253:
Line 197: Line 257:
Line 199: Line 258:

{{{domain "yourdomain" with
{{{
domain "yourdomain" with
Line 205: Line 264:
Line 208: Line 266:
Line 211: Line 268:
Line 214: Line 270:
Line 217: Line 272:
Line 220: Line 274:
Line 224: Line 277:

location "/loc2";
    location "/loc2" with
Line 229: Line 281:
Line 232: Line 283:
Line 235: Line 285:
Line 241: Line 290:
== 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 =
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;}}}
= Common Web Applications =
== MoinMoin ==
=== A Standalone Site ===
{{{
dom "yourdomain" with
  moinMoin "mywiki" where
    Script = home "mywiki/moin.cgi"
  end
end}}}
=== 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}}}
== WordPress ==
=== A Standalone Blog ===
{{{
dom "yourdomain" with
  wordPress "myblog"
end}}}
Make sure you have the Word``Press distribution installed at the appropriate `DocumentRoot`.

=== 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 Word``Press distribution installed at the filesystem location implied by the URL prefix you choose.

= 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
= 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].

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;

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 *)

  (* IPv6 alternatives to some of the above *)
  dnsIPv6 "host" "1111:2222:3333:4444:5555:6666:7777:8888";
  dnsDefaultv6 "1111:2222:3333:4444:5555:6666:7777:8888";
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.

dom "yourdomain" where
  CreateWWW = false;
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;

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 *)
    location "/cgi-bin" with
       options [execCGI];
       cgiExtension "cgi"
    end;
    (* Any path like /cgi-bin/*.cgi should be executed as a CGI script. *)
  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 [followSymLinks];
    (* Ask not to follow symbolic links. *)
    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].

DomTool/Examples (last edited 2022-02-10 16:18:48 by 2603:7080:493d:db56:2d52:b733:fa7c:b161)