welcome: please sign in

Diff for "DomTool/Examples"

Differences between revisions 1 and 20 (spanning 19 versions)
Revision 1 as of 2006-12-17 21:31:54
Size: 1517
Editor: AdamChlipala
Comment:
Revision 20 as of 2007-11-12 02:46:44
Size: 10657
Editor: MichaelOlson
Comment: Add link to working examples subpage
Deletions are marked like this. Additions are marked like this.
Line 22: Line 22:
== 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 34: Line 59:
  nameserver "ns.hcoop.net";
  nameserver "ns2.hcoop.net";
  nameserver "ns1.hcoop.net";
  nameserver "ns3.hcoop.net";
Line 37: Line 62:

  dnsDefault "69.90.123.68";
  (* Add a mapping from yourdomain to IP address 69.90.123.68 *)
Line 46: Line 74:
end;}}}
  dnsIP "dynamic" "5.6.7.8" where
    TTL = 100
  end;
  (* Add an IP mapping with an abnormally low time-to-live of 100 *)
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;}}}

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

== 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;}}}

= 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 [:/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;}}}

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

    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 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.5. 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.
      • 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.6. 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.7. 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.8. 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.9. 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.10. 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.11. 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.12. mod_proxy

{{{domain "yourdomain" with

end;}}}

5. Mailman

{{{domain "yourdomain" with

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

end;}}}

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

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

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