Go to the first, previous, next, last section, table of contents.

23. The aliasfile director

The aliasfile director expands local parts by consulting a file or database of aliases. An incoming local part is looked up, and the result is a list of one or more replacement addresses, file names, pipe commands or certain special items. The expansion may safely contain the same local part as the input as one of its items, because a director is automatically skipped if it has an identical ancestor that was processed by that director. For the case of a new alias address that is identical to the input address, this rule means in effect that it starts its processing at the following director.

The alias list can be obtained from a text file that is searched linearly, a DBM direct-access file, a NIS or NIS+ map, an LDAP database, or any other kind of lookup supported by Exim (see chapter 6).

Unless the locally_caseless option has been set false, local parts are forced to lower case, and so the keys in alias files should normally be in lower case. For linearly searched files this isn't in fact necessary, because the searching is done in a case-independent manner, but it is relevant for other forms of alias lookup. The exim_dbmbuild utility can be used to convert a text file into a DBM database; the keys are lower-cased by default.

23.1 Specifying a transport for aliasfile

The generic transport option must not be specified for aliasfile when it is fulfilling a traditional aliasing function. If transport is specified, the director behaves differently, and doesn't really `alias' at all. Its lookup facilities are used as a means of validating the incoming address, but if it is successful, the message is directed to the given transport while retaining the original address. The data that is returned from the lookup is not used. For example, a file containing a list of cancelled users can be used to direct messages addressed to them to a particular script.

Another common use of aliasfile with a transport is for handling local deliveries without reference to /etc/passwd. Local parts are validated by using aliasfile to look them up in a file or database, which can also be used to hold information for use during delivery (for example, the uid to use, or the location of the mailbox). There is a sample configuration that gives more detail.

23.2 Alias file format

A textual alias file to be searched linearly consists of entries that start with the alias name, terminated by a colon or white space. However, a colon must be used if data for the alias starts with a colon, because white space is permitted between the alias name and its terminating colon. This is Exim's standard lsearch format (see chapter 6).

The remainder of the entry, up to the end of the line, consists of a list of addresses, file names, pipe commands, or certain special items (see below). The items in the list are separated by commas. The list can be continued over several lines by starting each of the continuation lines with white space. A single space is retained at each junction. However, a comma is still required following an item that ends at the end of a line, because the lsearch lookup code removes newlines from the string it returns.

Lines in textual alias files that start with a # character are comments, and are ignored, and a # may also appear following a comma in an item list, in which case everything after the # is ignored. Other forms of alias file (DBM, NIS, LDAP, etc.) involve lookups using the local part as a key on files and databases. The value returned is a list of items separated by commas or newlines. The returned list is normally used exactly as it stands, but if the expand option is set, it is first passed through the string expansion mechanism.

By default, alias names are simple local parts such as `postmaster', but if the include_domain option is set, they must contain both a local part and a domain, thus allowing aliases for more than one domain to be held in a single file.

It is possible to set up a default in an alias file that uses a single-key lookup type. This matches incoming local parts that do not match any other entry when the lookup type name is followed by an asterisk, for example dbm* (see section 6.6). For query-style lookups, the queries option specifies a list of queries to be tried.

23.3 Types of alias item

If an item is entirely enclosed in double quotes, these are removed. Otherwise double quotes are retained because some forms of mail address require their use (but never to enclose the entire address). In the following description, `item' refers to what remains after any surrounding double quotes have been removed. An item may safely be the same as the local part currently under consideration, because any director is automatically skipped if any ancestor has the same local part and was processed by that director.

23.4 Duplicate addresses

Exim removes duplicate addresses from the list to which it is delivering, so as to deliver just one copy to each address. This does not apply to deliveries directed at pipes by different immediate parent addresses, but an indirect aliasing scheme of the type

pipe:       |/some/command ${local_part}
localpart1: pipe
localpart2: pipe

does not work with a message that is addressed to both local parts, because when the second is aliased to the intermediate local part `pipe' it gets discarded as being the same as a previously handled address. However, a scheme such as

localpart1: |/some/command ${local_part}
localpart2: |/some/command ${local_part}

does result in two different pipe deliveries, because the immediate parents of the pipes are distinct.

23.5 Repeated alias expansion

When a message cannot be delivered to all of its recipients immediately, leading to two or more delivery attempts, alias expansion is carried out afresh each time for those addresses whose children were not all previously delivered. If an alias is being used as a mailing list, this can lead to new members of the list receiving copies of old messages. The one_time option can be used to avoid this.

23.6 Errors in alias files

If skip_syntax_errors is set, a malformed address that causes a parsing error is skipped, and an entry is written to the main log. This may be useful for mailing lists that are automatically managed, but note the inherent danger. Otherwise, if an error is detected while generating the list of new addresses, the message is frozen, except for the special case of inability to open an included file, when no_freeze_missing_include is set. In this case, delivery is simply deferred.

23.7 Aliasfile private options

This section lists the private options that aliasfile does not have in common with forwardfile. Those that they share are given in chapter 22.

expand (aliasfile)

Type: boolean
Default: false

If this option is set true, the text obtained by looking up the local part is passed through the string expansion mechanism before being interpreted as a list of alias items. Addresses that are subsequently added by means of the `include' mechanism are not expanded.

file (aliasfile)

Type: string, expanded
Default: unset

This option specifies the name of the alias file, and it must be set if search_type specifies a single-key lookup; if it does not, an error occurs. (For query-style lookups, query must be set instead.) See chapter 6 for details of different lookup styles. The string is expanded before use; if expansion fails, Exim panics. The resulting string must be an absolute path for linear search and DBM lookups. If the original string does not start with `/' or `$' in these cases, Exim gives a configuration error when it starts up; otherwise, if an expanded string does not begin with `/' delivery is frozen.

forbid_special (aliasfile)

Type: boolean
Default: false

If this option is set, the special items :defer:, :fail:, :blackhole: and :unknown: are forbidden. If any are encountered, delivery is deferred.

include_domain (aliasfile)

Type: boolean
Default: false

Setting this option true causes the key that is looked up to be `local-part@domain' instead of just `local-part'. Thus a single file can be used to hold aliases for many local domains. This option has no effect if the search type specifies a query-style lookup.

If you want include defaults for each domain in an alias file in the form

*@domain1:  default@domain1
*@domain2:  default@domain2

then you need to include `*@' in the search type (for example, dbm*@). See section 6.1 for details of this kind of search.

optional (aliasfile)

Type: boolean
Default: false

For a single-key lookup type, if the file cannot be opened because it does not exist (the ENOENT error) and this option is set, the director simply declines to handle the address. Otherwise any failure to open the file causes an entry to be written to the log and delivery to be deferred.

For a query-style lookup type, optional causes the director to decline if no query can be completed (for example, all databases are down). Without optional, delivery is deferred.

queries (aliasfile)

Type: string, expanded
Default: unset

This option is an alternative to query; the two options are mutually exclusive. The difference is that queries contains a colon-separated list of queries, which are tried in order until one succeeds or defers, or all fail. Any colon characters actually required in an individual query must be doubled, in order that they not be treated as query separators.

query (aliasfile)

Type: string, expanded
Default: unset

This option specifies a database query, and either it or queries must be set if search_type specifies a query-style lookup; if neither is set, an error occurs. (For single-key lookups, file must be set instead.) See chapter 6 for details of different lookup styles. The query is expanded before use, and would normally contain a reference to the local part. For example,

search_type = nisplus
query = [alias=${local_part}],mail_aliases.org_dir:expansion

could be used for a NIS+ lookup. Sometimes a lookup cannot be completed (for example, a NIS+ database might be inaccessible) and in this case the director causes delivery to be deferred.

search_type (aliasfile)

Type: string
Default: unset

This option must be set to the name of a supported search type (`lsearch', `dbm', etc.), specifying the type of data lookup. For query-style lookups, the query option specifies the search query, and file must not be set. For the other search types, file is required and query must not be set. See chapter 6 for details of the different lookup styles.

Single-key search types for aliasfile can be preceded by `partial-' and/or followed by `*'. The former isn't likely to be useful very often, but the latter provides a default facility. Note, however, that if two addresses in the same message provoke the use of the default, only one copy gets delivered, but any added Envelope-to: header contains all the original addresses. Exceptions to the default can be set up by aliasing them to :unknown:.

Go to the first, previous, next, last section, table of contents.