welcome: please sign in

The following 747 words could not be found in the dictionary of 7 words (including 7 LocalSpellingWords) and are highlighted below:
404s   abnormally   about   above   Access   accessed   accessible   accessing   action   actually   add   Add   Adding   adding   Additional   additional   address   adds   Adjust   administer   afs   Again   Alias   alias   aliases   Aliases   all   All   Allow   allow   allowed   Allowing   alone   already   Also   also   alternate   alternatives   an   An   and   And   answer   answering   any   Any   Anyone   anyone   Apache   apache   apache2   Applications   applied   appropriate   appropriately   Arbitrary   are   area   argument   as   Ask   assume   at   Attack   auth   authenticating   authentication   authoritative   automatic   available   badguys   ban   banned   bar   barney   base   based   Basic   basic   be   because   been   begin   beginning   behaviour   below   between   Bigger   bin   block   blog   Blog   both   Bucking   builds   but   by   calling   can   cases   Category   cd   cert   certificate   cgi   chain   Change   changes   character   Charset   choose   Clones   code   codex   com   come   comes   coming   commands   Common   common   Cond   cond   config   configuration   configure   configuring   connection   consider   contain   contains   content   Contents   control   controlled   convenient   Coop   copied   copy   could   Create   create   created   creates   Creates   creating   creation   current   custom   customized   debugging   declare   Default   default   defaults   Defaultv6   defined   delivery   demonstrate   demonstrated   denied   deny   Deny   Describe   Description   dev   directive   directives   directories   Directory   directory   disable   distributed   distribution   dns   Dns   Do   do   doc   docelic   docroot   Document   does   doesn   doing   Dom   dom   domain   domains   Domains   Domtool   domtool   don   done   drop   Drop   duplicated   duplicating   dynamic   each   easier   easy   else   elsewhere   email   enable   end   ending   entered   Entire   environment   error   etc   every   everyone   everything   evil   exactly   example   Examples   examples   exec   executed   expect   explained   Extending   Extension   external   External   externalmailserver   extra   false   fancy   Fancy   features   few   File   file   files   filesystem   find   flags   follow   following   foo   footer   For   for   force   Force   form   Forward   forwarded   found   fred   from   From   from2   front   full   Full   further   fyodor   general   generation   gif   gives   giving   gmail   go   goes   gone   good   granted   grep   Group   group   had   handle   Handle   handler   handling   have   hcoop   header   headers   Height   help   here   Here   home   Host   host   hosted   hostname   how   However   htaccess   Htaccess   Htdocs   html   http   https   icon   if   If   illustrative   image   images   implied   In   in   iname   include   Include   includes   including   Index   index   indexes   Indexing   indicating   information   inherently   insecure   install   installed   installing   Installing   instance   Instead   instead   interface   interfaces   Internet   ip   is   Is   it   It   just   Keeping   know   last   learn   leaving   level   Level   life   like   likely   links   Links   list   listinfo   listing   lists   live   Live   loc1   loc2   local   localhost   Location   location   locations   Log   log   logging   Look   looking   low   lowest   Ls   mail   Mail   mail2   mailbox   mailcust   mailing   Mailman   mailman   Mailserver   mailserver   main   make   Make   management   Manual   manual   manually   Map   mapping   mappings   Mars   mars   matching   me   means   Member   membership   mentioned   mind   mirror   mod   Model   more   More   most   much   Multi   multiple   must   my   myblog   mycert   mydomain   mysite   mywebhost   mywiki   name   Name   names   nameserver   need   needed   net   never   Never   No   no   nocase   non   nonstandard   normal   not   Note   nothing   Now   ns1   ns3   null   Of   of   Off   off   often   old   on   one   Only   only   option   options   Options   Or   or   order   org   ornext   Other   other   otherdomain   otherone   others   our   out   overview   own   page   pages   pal1   pal2   pal3   pals   parameters   particular   Pass   password   path   pem   period   permanent   permission   permissions   Permit   permits   php   pics   pieces   place   Places   plain   planet   possibilities   possible   possibly   prefix   Prefix   prehistoric   Press   primarily   priority   private   probably   processed   prodigy   production   program   proper   protocols   provide   provided   providing   proxy   Proxy   proxying   public   pulling   purposes   put   Putting   Pv6   qsappend   re   read   real   really   reason   reasons   receiving   record   records   redirect   Redirect   Redirection   redirects   Register   relaying   relocation   remaining   reminding   Removes   requests   require   resolves   rest   Reverse   rewrite   Rewrite   right   rights   Root   Rule   rule   Run   same   script   Script   second   section   sections   secure   security   see   See   Send   sending   sent   separate   Serve   serve   Server   server   servers   serving   Set   set   Sets   settings   share   shell   Short   should   shouldn   shows   Silently   Simple   simple   since   single   site   Site   site1   site2   Sites   sites   skip   sml   some   somewhere   sort   space   spamtrap   special   specific   Specify   specifying   spf1   spinlocksolutions   ssi   Ssl   ssl   Standalone   standard   start   static   still   stripped   subdirectories   subdirectory   Subdomain   subdomain   subpage   Subversion   subversion   such   sure   Sym   symbolic   system   Table   take   Tell   Text   text   that   The   the   them   then   there   these   These   they   thing   this   This   through   time   to   To   to2   together   Together   too   tool   Tool   Top   tour   track   tree   trends   Turn   tweak   two   txt   type   Type   typically   unless   unset   up   updater   Updating   Upgraded   url   use   Use   used   User   user   user1   user2   username   users   uses   Using   using   usr   utf   valid   Valid   var   variable   ve   verification   vhost   vhosts   via   virtual   want   way   wc   We   we   Web   web   websites   webusers   well   what   When   when   where   which   Why   Width   Wiki   wiki   Wildcard   will   With   with   within   word   Word   Wordpress   wordpress   working   world   worth   wouldn   www   www2   www3   xargs   yahoo   yorudomain   You   you   Your   your   yourdomain   yourotherdomain   yourotherotherdomain   Yourself  

Clear message
Edit

DomTool / Examples

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 your-hcoop-username@yourdomain mail forwarded to your mailbox, use:

dom "yourdomain" with
end;

Or, if you don't want any 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. Model T with redirect from www.yourdomain to yourdomain

To redirect all URLs from http://www.mydomain/some/path/ to http://mydomain/some/path/ you need to disable the automatic creation of the www host, and then create it manually specifying a permanent redirect rule.

dom "mydomain.com" where
 CreateWWW = false;
with
 vhostDefault with
 end;

 web "www" with
   rewriteRule "^(.*)$" "http://mydomain.com$1" [redirectWith permanent]
 end;
end;

1.5. 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.6. Subdomain Redirection

This example aliases a subdomain and redirects it to the "www" virtual host. This means that when accessing yourSubdomain.yourdomain.com you will actually be receiving content defined by www.yourdomain.com.

dom "yourdomain.com" where
  CreateWWW = false
with
  dnsIP "yourSubdomain" web_ip;
  web "www" with
    serverAlias "yourSubdomain"
  end
end;

1.7. 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. You shouldn't use the domain directive unless you really know what you're doing when it comes to Internet protocols, and you have a good reason not to like the defaults that dom includes.

domain "yourdomain" with
  (* Your directives here *)
end;

2. DNS

Here's a tour through the available DNS features. You probably don't want to use any nameserver, dnsDefault, or dnsMail directives in your configuration, since dom will include the proper defaults for you. It's worth reminding that you probably shouldn't use the domain directive. We only use it here for illustrative purposes.

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, see the section about dynamic DNS below *)
  (* 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";
  (* Map every remaining hostname to 2.2.2.2. *)
  dnsWildcardIP "2.2.2.2";
end;

2.1. Keeping DNS elsewhere

This example shows how to configure mail handling for a domain that is primarily hosted off of HCoop. We only use domain instead of dom because dom already includes the handleMail directive that we want to demonstrate.

domain "yourdomain" where
  DNS = noDns
with
  handleMail;
end;

3. Mail

We only use domain instead of dom because dom already includes the handleMail directive that we want to demonstrate.

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, period, to user me *)
  addDefaultSPF;
  (* Only allow mail to be sent through your MX, typically mail.hcoop.net. *)
end;

3.1. External Mailserver

Using an external mailserver is possible by adding manual DNS records.

dom "yourdomain" where
  AddMX = false; (* Removes default mail.hcoop.net DNS record. *)
 with
  dnsMail 10 "mail.externalmailserver.com";
  dnsMail 50 "mail2.externalmailserver.com";
  dnsDefaultText "v=spf1 include:_mailcust.externalmailserver.com ?all"; (* Sets TXT record for verification. *)
end;

4. Apache

.htaccess files are not processed on our servers for security reasons, as explained on DomTool/WhyNoHtaccess. See the examples below to learn how to use Apache features that are often controlled with .htaccess files.

4.1. The Default

The standard dom directive gives you a web site at www.yourdomain and yourdomain, pulling content from your ~/public_html directory.

dom "yourdomain" with
end;

4.2. Extending the Default

You can tweak the configuration for your domain's www virtual host like this:

dom "yourdomain" where
  DocumentRoot = home "somewhere/else";
  (* Serve static content from ~/somewhere/else. *)
  WWW = begin
    (* Here you can put any of the web configuration directives found in the sections below. *)
  end
with
  (* ...and you can still put other domain configuration here. *)
end

4.3. Simple Additional Web Sites

It's easy to add extra web sites to your domain when they just serve static content from subdirectories of your home directory:

dom "yourdomain" with
  simpleWeb "site1" "sites/site1";
  (* This creates a web virtual host site1.yourdomain, serving content from ~/sites/site1. *)
  simpleWeb "site2" "sites/site2";
end

4.4. The Model T

Now we come to the web directive, which should be your main tool for creating additional virtual vhosts with custom configuration.

dom "yourdomain" with
  web "mywebhost" with
    (* This is a web host found at mywebhost.yourdomain. *)
  end;
end;

Note that the web directive also adds the right DNS mapping for your virtual host. Never use web "www" within a dom directive. Instead, see the examples at the beginning of the Apache section. All of the directives demonstrated in the rest of the Apache section can be used between the begin and end demonstrated in that example.

4.5. The Do-It-Yourself

dom "yourdomain" with
  vhost "mywebhost" with
  end;
end;

This one doesn't add any DNS mappings. You probably never want to use vhost instead of web.

4.6. The Top-Level Do-It-Yourself

The same can also be done to create a vhost accessible via http://yourdomain/.

dom "yourdomain" with
  vhostDefault with
  end;
end;

4.7. Using a nonstandard web server

dom "yourdomain" with
  web "mywebhost" where
    WebPlaces = [web_place_default "fyodor"]
  with
  end;
end;

4.8. Using SSL (HTTPS)

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

dom "yourdomain.com" where
  CreateWWW = false;
with
  web "www" where
    SSL = use_cert "/etc/apache2/ssl/user/yourdomain.pem"
  with
  end;
end;

4.9. Allowing non-secure & secure connection with same behaviour

If you want to enable ssl and force a redirect from http to https, the webSsl directive can handle this for you in most cases.

The example below is stripped of all extra settings on the "www" web directive. If you have any special settings, they should be copied as well.

dom "yourdomain.com" where
  CreateWWW = false;
  DocumentRoot = home "websites/yourdomain.com"
with
  webSsl "www" (use_cert "/etc/apache2/ssl/user/yourdomain.pem") with
  end;
end;

If you want to allow both http and https with the same configuration instead, you can set the ForceSSL environment variable to false.

dom "yourdomain.com" where
  CreateWWW = false;
  DocumentRoot = home "websites/yourdomain.com"
with
  webSsl "www" (use_cert "/etc/apache2/ssl/user/yourdomain.pem") where
    ForceSSL = false
  with
  end;
end;

dom "yourdomain" with
  web "mywebhost" 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.11. Basic URL handling

dom "yourdomain" with
  web "mywebhost" 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.12. Location-specific configuration

dom "yourdomain" with
  web "mywebhost" 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.13. Server aliases

dom "yourdomain" with
  web "mywebhost" 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. See the example "Attack of the Model T Clones" for a more convenient way of duplicating all of a domain's configuration for one or more other domains.

4.14. Directory options

dom "yourdomain" with
  web "mywebhost" 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.15. Access control

dom "yourdomain" with
  web "mywebhost" 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.16. Fancy directory index generation

dom "yourdomain" with
  web "mywebhost" 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.17. mod_rewrite

dom "yourdomain" with
  web "mywebhost" 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/error.log *)
    rewriteCond "%{REQUEST_FILENAME}" "-f" [cond_nocase, ornext];
    (* An example of Apache's RewriteCond directive *)
    rewriteRule "/a.html" "http://a/b.html" [gone, chain, skip 5];
    (* An example of specifying multiple rewrite flags *)
  end;
end;

4.18. mod_proxy

dom "yourdomain" with
  web "mywebhost" 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 *)
    proxyRewrite "/foo/(.*)$" "bar/$1" "http://localhost:5555" [qsappend];
    (* Proxy path matching /foo/(.*)$ to http://localhost:5555/bar/$1, using mod_rewrite *)
    proxyPassReverse "/foo/" "http://localhost:5555/";
    (* Adjust Location and other HTTP headers appropriately for the above proxying *)
  end;
end;

4.19. SSI

dom "yourdomain" with
  web "mywebhost" with
    set_options [includesNOEXEC];

    (* Or you could enable it for just some URIs: *)
    location "/ssi_world" with
      set_options [includesNOEXEC];
    end;
  end;
end;

5. Mailman

The following example will:

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"
  with
  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

When installing Wordpress, you most likely want to install using subversion. The web based updater is inherently insecure, and your life will be much easier if you use subversion to track changes in Wordpress.

6.2.1. A Standalone Blog

dom "yourdomain" with
  wordPress "myblog" where
    DocumentRoot = home "path/to/wordpress"
  end
  (* Creates a WordPress blog at http://myblog.yourdomain/ *)
end

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

6.2.2. If the Blog is Your Entire Site

dom "yourdomain.com" where
  DocumentRoot = home "path/to/wordpress";
  WWW = begin
    addWordPress "/";
  end;
  (* Creates a WordPress blog at http://www.yourdomain.com/ *)
with end;

Again, make sure you have the WordPress distribution installed at the appropriate DocumentRoot.

6.2.3. 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. Your blog will be accessible at http://mysite.yourdomain/url/prefix/....

7. Live Examples in HCoop AFS

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

To find other files and possibly grep for particular examples in them, you can use the following shell commands:

cd /afs/hcoop.net/user/

find ?/??/*/.domtool/ -type f
# or
find ?/??/*/.domtool/ -type f \( ! -iname "*~" \)  2> /dev/null | xargs -I {} wc -l {}  | sort -n

grep KEYWORD ?/??/*/.domtool/*

8. Putting It All Together

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


CategoryMemberManual

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