The Directory refers to the lookup mechanisms for identifying and authenticating local users and domains.
In the absence of any Directory data, Mailismus will act as a relay-only SMTP switch, with no local users or mailboxes.

4.10.1 - Configuration

The top-level config block looks as follows:

<directory>
    <domains>/path/to/domains-file</domains>
    <users>/path/to/users-file</users>
    <aliases>/path/to/aliases-file</aliases>
    <virtualusers>Y</virtualusers>
    <plainpass>N</plainpass>
</directory>

domains
This is an optional setting which specifies a file that contains a list of domain names, one per line.
Although this item is optional (its absence meaning that there are no recognised local domains), if it is specified, then the referenced file must exist.
Each entry is an FQDN (fully qualified domain name) representing a local domain.
Eg. if you have a local user such as firstname.lastname@mydomain1.com, then one of the lines in this file would be mydomain1.com

users
This is an optional setting which specifies a file that contains a list of local usernames, one per line.
Although this item is optional (its absence meaning that there are no recognised local users), if it is specified, then the referenced file must exist.
Each line consists of a username, followed by a colon, followed by the password. The password may be absent, which means that messages can be delivered to that mailbox, but the user cannot log on to retrieve them.
A username in this sense is effectively the mailbox part of an email address, so continuing with the above example in the domains section, one of the lines in this file would be firstname.lastname

aliases
This is an optional setting which specifies a file that contains a list of local aliases, one per line.
Although this item is optional (its absence meaning that no aliases are in effect), if it is specified, then the referenced file must exist.
Each entry consists of an alias, followed by a colon, followed by a colon-separated list of one or more recipients.
The alias part can be a simple alias, or it can be a full email address, and the most specific match for a given recipient will be selected, when processing an incoming message.
The recipients can be either a local username (which MUST exist in the users file) or another fully qualified remote email address.

virtualusers
This is an optional field which defaults to Yes, and refers to whether the usernames defined for the Directory (whether defined by the Directory or looked up elsewhere) correspond to actual user accounts on the underlying OS, or are an independent namespace maintained by Mailismus, which serves purely to allocate and identify mailboxes.
The distinction between real and virtual users is of importance in setting the ownership and permissions of the mailboxes and their messages.
Mailismus will perform better with virtual users, ie. mailboxes it manages itself and which do not correspond to the OS platform's native mail folders.

plainpass
This specifies whether user passwords are exposed by the Directory provider, and if so, whether they are stored in plain or hashed form.
The default is No, meaning they are either not exposed or stored in hashed format.

The Directory supports the DIRECTORY_RELOAD NAFMAN command, which tells it to reload its backend data (ie. the files described above).
You can enable periodic reloads by scheduling this command at the desired intervals (eg. via Cron), using a batch-mode HTTP client such as wget
         wget -q HOSTNAME:13000/DIRECTORY_RELOAD?st=cmdstatus

To put all the above into practice as an example, if you have:
• local domains: mydomain1.com and mydomain2.com
• local users: username1 and username2
Then given the following aliases file:

info@mydomain1.com : username1
info : username2
support: username1 : fred@gmail.com

• Messages addressed to info@mydomain1.com will get delivered to the mailbox of username1,
• Messages addressed to info@mydomain2.com (or info@any.other.local.domain) will get delivered to the mailbox of username2.
• Messages addressed to support @ any local domain will be delivered to a distribution list consisting of the local mailbox for username1 and the remote address fred@gmail.com

The special alias . (dot) is referred to as the "sink" alias, and means messages addressed to that recipient will be silently discarded (although it will appear as if they were accepted ok).
If the sink alias is used, it must be the sole entry on the right hand side.

For all three Directory files, white space is ignored, as are blank lines or lines beginning with # (hash sign) which can be used for comments.