This page documents the procedures for administering the sites you have hosted with HCoop. All the configuration files described support line comments, indicated by beginning a line with {{{#}}}.

This page describes in detail how to use domtool. It may be easiest for you to simply look at the setup of an existing domain and copy most of the directives. See, for example, {{{/etc/domains/net/schizomaniac}}}, AdamChlipala's personal domain.

You won't be able to find help about domtool elsewhere on the web.  We've developed it ourselves specifically for hcoop (see [http://hcoop.sf.net/ the SourceForge project]).  Also, you will no doubt be wasting your time looking elsewhere for information on configuring Apache, your individual web sites, DNS, e-mail aliases, or any other shared service, since we don't allow users to modify these settings directly.  You have to go through domtool, and this page should tell you everything you need to know about doing that.

= Directory structure =
The configuration files for the sites hosted here are rooted in {{{/etc/domains}}}. This directory tree corresponds to the structure of Internet domain names. For instance, tpu.org configuration is rooted in {{{/etc/domains/org/tpu}}}. We use standard UNIX file permissions to control who may modify which domains. There are appropriate files to edit in a domain's directory to control its DNS, e-mail aliases, Apache virtual hosts, and Webalizer statistics. Upon making changes, you run the {{{domtool}}} command line program (with no parameters) to publish them. It will let you know if it finds any errors in your changes. ''Remember'', none of the files in {{{/etc/domains}}} have any direct effect on our services by themselves. You must always run {{{domtool}}} to publish your changes.

To begin configuring a new domain, [https://members.hcoop.net/portal/domain request access to it through our portal].  This will create a directory for your domain and populate it with the skeleton files .dns, .groups, .paths and .users.  You will need to add any additional files and review these initial files to see if they are appropriate for your domain.  Do not attempt to change the .groups, .paths or .users files yourself.  This must be changed by an administrator.  If you do edit them {{{domtool}}} will reject them.  After making changes remember to execute {{{domtool}}} from the directory.

= Variables =
Domain directories, including the root {{{/etc/domains}}}, may contain {{{.vars}}} files. These define simple mappings from strings to strings, in the form of whitespace-separated name/value pairs on separate lines. Currently, they are used only in naming IP addresses that will be used in many domains. For example, the IP address of the web server configured by this tool is called {{{www}}}. Subdomains inherit the variables set in their parents, and they may also define new variables.

= Paths =
To control access to the filesystem, each domain has an associated list of directories it is allowed to access. Any of these directories or their subdirectories is allowed to be used any place a directory must be specified. {{{.paths}}} files in domain directories give lists of allowable paths. They are inherited in the same manner as {{{.vars}}} files. {{{.paths}}} files must be configured by someone with root access or they will not be read.  Do '''not''' attempt to edit your {{{.paths}}} file, as doing so will change its ownership and make {{{domtool}}} reject your changes.

When a {{{.paths}}} file begins with a line that says {{{CLEAR}}}, it causes its domain not to inherit parents' path privileges. This can be used to delegate subdomains to others without giving them access to resources associated with the main domain.

= Users and groups =
The set of users and groups as whom you may run CGI programs is controlled in a manner analogous to paths. {{{.users}}} and {{{.groups}}} files in any position in the domain hierarchy add permissible users for those domain subtrees. {{{CLEAR}}} is supported for these, as well.  As with {{{.paths}}}, do '''not''' edit your own {{{.users}}} or {{{.groups}}} file. Only administrators may do this, and changing its ownership will result in {{{domtool}}} rejecting your changes.

= Configuring daemons =
domtool lets you configure a number of different daemons.  We've documented each one on a separate page.  See:

 * DnsConfiguration: Mapping Internet hostnames to IP addresses
 * EmailConfiguration: Controlling how e-mail to your domain is delivered or otherwise handled
 * VirtualHostConfiguration: Managing web sites at different hostnames of your domain
 * MailingListConfiguration: Setting which web site provides the Mailman web interface for any mailing lists you host with us