makehosteddomains rebuilds the contents of the /usr/local/courier/etc/hosteddomains.dat database from the contents of /usr/local/courier/etc/hosteddomains. This can be either a file or a directory. If it's a directory, the contents of all the files in this directory are simply concatenated. The makehosteddomains script must be run in order for any changes to /usr/local/courier/etc/hosteddomains to take effect.
The function of /usr/local/courier/etc/hosteddomains is very similar to the one of /usr/local/courier/etc/locals. Both configuration files specify a list of domains that are considered to be local domains - domains whose mailboxes are stored locally.
The difference is that domains listed in /usr/local/courier/etc/locals are removed from addresses before their mailbox is looked up. For example, if the domain "example.com" is listed in /usr/local/courier/etc/locals, then the address <email@example.com> is delivered to a local mailbox named "user". If this domain is listed, instead, in /usr/local/courier/etc/hosteddomains, then the address <firstname.lastname@example.org> is delivered to a local mailbox named "email@example.com". Usually you would use /usr/local/courier/etc/locals to specify domains that correspond to your local system accounts, that are looked up in your system's password database. The /usr/local/courier/etc/hosteddomains file is usually used when you have database-based virtual domains, that are maintained via an LDAP or a MySQL server. Courier's LDAP and MySQL authentication modules will use the full E-mail address to query the LDAP or MySQL server for the location of the local mailbox that correspond to the E-mail address. Courier's authuserdb authentication module can also use full E-mail addresses.
The file /usr/local/courier/etc/hosteddomains simply contains a list of domains, one per line, for example:
Each domain can optionally be followed by a single tab character, in order to specify an alias for a domain, for example:
First, we list the domain "domain.com" as a hosted domain. Then, we also list the domain "mail.domain.com", which is an alias for domain.com. Courier will take any address of the form <firstname.lastname@example.org>, rewrite it as <email@example.com>, and attempt to deliver the mail to a local mailbox for that name.
This is a special local mail delivery rule for hosteddomain-listed domains. This rule allows Courier accept mail to any address@hosteddomain, where "hosteddomain" is a domain listed in the hosteddomains file, but there is no corresponding account for address@hosteddomain. To provide delivery instructions for any non-existing address in a hosteddomain-listed domain:
1) Create the local address alias@hosteddomain. For example, if the hosteddomains file contains "example.com", create the local account firstname.lastname@example.org. This should be a normal account, with its own home directory, userid and groupid.
2) Create $HOME/.courier-default file in this account, containing the delivery instructions. See the dot-courier(5) manual page for avaiable delivery instructions.
NOTE that email@example.com must be a real account, not a mail alias. If you want to forward firstname.lastname@example.org to another address, put forwarding instructions in the .courier-default file. However, email@example.com can be a clone of another account (with the same home directory, userid, and groupid).