The domain-conf system has a centrally maintained list stating which people have which domains. I control this. You need to ask me to put things in the list.

From that list, it finds out what domain files to read from whose home directories. Just putting a domain file in your home directory will not cause the system to do anything with it. I need to authorise the domain.

You will find a file for each domain you have inside the warhead directory under your home directory.

The file starts with a [domain] section. This always follows a standard format:

[domain]
last-modified: 2001010200
refresh: 86400
retry: 7200
expire: 604800
minimum: 3600

You will never need to modify these apart from last-modified:, unless you are a DNS expert and know what an SOA record is for. The last modified date needs to be changed whenever you alter the file; it goes YYYYMMDDHH, but since the domain system only updates once a day you might as well leave the HH as 00 and just update the date.

In the rare case of you having your DNS hosted by somebody else but your web or email stuff handled by Warhead, add dns: 0 to the [domain] section to turn off Warhead DNS.

Then you have sections for each service you want at each domain. Service sections name the service and the domain address to provide that service at. For example, in a domain file for example.com, a section starting [mail.foo] will set up a mail domain with email addresses ending in @foo.example.com. A service with no domain name - such as [mail] - provides it's service to the master domain itself (example.com in our example).

mail services contain a list of redirection rules. Each rule looks like this:

peter: peter@yahoo.co.uk, peter@hotmail.com

In this example, email addressed to peter@foo.example.com ends up being delivered to peter@yahoo.co.uk and peter@hotmail.com.

If an email fails to match any of the rules, then a special rule called * is looked up. If it exists, then the email is sent to the addresses specified in that rule. If not, the email is returned to the sender.

web services are even simpler; they contain a single line, looking like:

site: example-main

This line names a web directory, as defined in the section called “Website directories”

For the intrepid, you can also cause raw DNS records to be inserted into your zonefile with rr services. They look like this:

[rr.anyUniqueLabelYouLike]
name: foo
type: A
body: 192.168.0.5

This causes your zone file to contain:

foo	IN	A	192.168.0.5

As with any BIND zone file, you can use absolute names, or @ to refer to the name of the zone:

[rr.anyUniqueLabelYouLike]
name: @
type: A
body: 192.168.0.5

[rr.anyUniqueLabelYouLike]
name: foo.bar.net.
type: A
body: 192.168.0.5

If you don't know what a zone file or a resource record is, you probably don't need to.

The domain-conf system finds a website directory in your home directory by being referred to it by name from a domain file.

The contents of a website directory are:

public_html.  This is compulsory. It must be a directory, and it is where the files you want to be available on your web site should be placed.

cgi-bin.  This directory is only required if you have set the cgi: flag in warhead.conf. It is mapped to /cgi-bin/ in your web site, and will execute CGIs from the directory instead of serving up the contents of the file.

error_log.  This file will be created for you automatically when your site becomes activated. Each line in the file will be a description of a failed attempt to access part of your site. A lot of these happen naturally - don't worry about them.

access_log.  This file will be created for you automatically when your site becomes activated. Each line in the file will be a description of an attempt to access a page on your site. The defaul format is the Apache “combined” log format, and can be overridden in warhead.conf.

error_log.*.gz, access_log.*.gz.  These files are compressed older copies of the logs, automatically created periodically. Eventually, they are deleted, to save disk space.

warhead.conf.  This file must follow the following format:

[site]
email: email address
primaryname: primaryname
logformat: Apache log format directive
directoryindex: default index.html file name
cgi: 1 or 0
mirror: 1 or 0
canonicalise: 1 or 0
forward: URL

Some of you will have elected to use raw zone files. These only configure DNS; they do not enable any Warhead email or Web site services.

Raw zone files also live in your warhead directory. They are BIND format zone files, with the name domain.zone. If you don't know about BIND format zone files, you will not be using raw zone files so I will not document their format here.