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


The aliasfile director

The `aliasfile' director expands local parts by consulting a file of aliases. The expansion may safely contain the same local part as the input, because a director is automatically skipped if any ancestor of a local part has the same name and was processed by that director.

The alias file can be a text file that is searched linearly, a DBM direct-access database, a NIS or NIS+ map, or any other kind of lookup supported by Exim (see chapter "File and database lookups").

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.

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 "File and database lookups").

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 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 &&s may also appear following a comma in an item list, in which case everything after the &&s is ignored.

Other forms of alias file (DBM, NIS, etc.) involve lookups using the local part as a key on files and databases. The value returned is a list of address, file, or pipe items separated by commas or newlines.

In all cases, 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.

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 one currently under consideration, because any director is automatically skipped if any ancestor has the same local part and was processed by that director.

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.

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.

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.

Specifying transports for aliasfile

If the generic `transport' option is specified for this director, then the message is directed to that transport for any local part which is found in the file, any data in the file that is associated with the local part being ignored (so it isn't really `aliasing' in this case). Thus the same processing can be done for any local part that is listed in the file. For example, a file containing a list of cancelled users can be used to direct messages addressed to them to a particular script.

A common use of `aliasfile' with a transport is for handling local deliveries without reference to `/etc/passwd'. Local parts are validated by looking 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.

There are also a number of private options that specify transports for use in certain cases, for example, when a local part is aliased directly to a file name, or to a pipe command.

Aliasfile private options

check_ancestor (aliasfile) option

Option: check_ancestor
Type: boolean
Default: false

When this option is set, if a generated address is the same as any ancestor of the current address, then it is not used, but instead the current address gets passed on to subsequent directors. In the default case, this happens only if the ancestor was processed by the current director. See the `check_ancestor' option on the `forwardfile' director for more details.

current_directory (aliasfile) option

Option: current_directory
Type: string
Default: unset

This option associates a current directory with any address that `aliasfile' directs to a local transport. This can happen either because a transport is explicitly configured for the director, or because it generates a delivery to a file or a pipe. The option string is expanded and is set as the current directory during the delivery process, unless overridden by a setting on the transport. See chapter "Environment for running local transports" for details of the local delivery environment.

directory (aliasfile) option

Option: directory
Type: string
Default: unset

This option is obsolete, having been replaced by `current_directory' and `home_directory'. If used, it sets the value of `home_directory'.

directory_transport (aliasfile) option

Option: directory_transport
Type: string
Default: unset

An `aliasfile' director sets up a direct delivery to a directory when a path name ending with a slash is specified as a new `address' (see chapter "Default transports"). The transport used is taken from the global option `address_directory', unless this option is set to override it. The string, after expansion, must be the name of a configured transport.

directory2_transport (aliasfile) option

Option: directory2_transport
Type: string
Default: unset

An `aliasfile' director sets up a direct delivery to a directory when a path name ending with two slashes is specified as a new `address' (see chapter "Default transports"). The transport used is taken from the global option `address_directory2', unless this option is set to override it. The string, after expansion, must be the name of a configured transport.

errors_to (aliasfile) option

Option: errors_to
Type: string
Default: unset

This used to exist as an option specific to this director, but it is now a generic option that can be used on any director or router (see chapter "Common generic options for directors and routers").

expand (aliasfile) option

Option: expand
Type: boolean
Default: false

If this option is set true, then 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) option

Option: file
Type: string
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 "File and database lookups" 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.

file_transport (aliasfile) option

Option: file_transport
Type: string
Default: unset

An `aliasfile' director sets up a direct delivery to a file when a path name not ending in a slash is specified as a new `address' (see chapter "Default transports"). The transport used is taken from the global option `address_file', unless this option is set to override it. The string, after expansion, must be the name of a configured transport.

forbid_file (aliasfile) option

Option: forbid_file
Type: boolean
Default: false

If this option is true, then this director may not generate a new address which specifies delivery to a local file or directory. If it attempts to do so, a delivery failure occurs.

forbid_pipe (aliasfile) option

Option: forbid_pipe
Type: boolean
Default: false

If this option is true, then this director may not generate a new address which specifies delivery to a pipe. If it attempts to do so, a delivery failure occurs.

freeze_missing_include (aliasfile) option

Option: freeze_missing_include
Type: boolean
Default: true

If a file named by the `include' mechanism fails to open, delivery is frozen if this option is true. Otherwise, delivery is just deferred. Unsetting this option can be useful if included files are NFS mounted and may not always be available.

home_directory (aliasfile) option

Option: home_directory
Type: string
Default: unset

This option associates a home directory with any address that `aliasfile' directs to a local transport. This can happen either because a transport is explicitly configured for the director, or because it generates a delivery to a file or a pipe. The option string is expanded and is set as the home directory during the delivery process, unless overridden by a setting on the transport. See chapter "Environment for running local transports" for details of the local delivery environment. This means that the expansion variable `$home' does not take on this value at directing time. In particular, it cannot be used in the `require_files' option.

include_domain (aliasfile) option

Option: include_domain
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 "Single-key lookup types" in chapter "File and database lookups" for details of this kind of search.

modemask (aliasfile) option

Option: modemask
Type: "octal
Default: integer" 022

This specifies mode bits which must not be set for the alias file. If they are set, the director fails and the message is frozen.

one_time (aliasfile) option

Option: one_time
Type: boolean
Default: false

Sometimes the fact that Exim re-evaluates aliases each time it tries to deliver a message causes problems. This is particularly true in the case of mailing lists and so is more likely to be a problem with forward files than with alias files.

If `one_time' is set and any addresses generated by the director fail to deliver at the first attempt, the failing addresses are added to the message as `top level' addresses, and the parent address that generated them is marked `delivered'. Thus aliasing does not happen again at the next delivery attempt. To ensure that `aliasfile' generates only addresses (as opposed to pipe or file deliveries) `forbid_file' and `forbid_pipe' must also be set.

The original top-level address is remembered with each of the generated addresses, and is output in any log messages. However, any intermediate parent addresses are not recorded. This makes a difference to the log only if `log_all_parents' is set. It is expected that `one_time' will typically be used for mailing lists, where there is normally just one level of expansion.

optional (aliasfile) option

Option: optional
Type: boolean
Default: false

If the file cannot be opened because it does not exist (the ENOENT error) and this option is set, the director simply fails to match the address. Otherwise any failure to open the file causes an entry to be written to the log and delivery to be deferred.

owners (aliasfile) option

Option: owners
Type: string-list
Default: unset

This specifies a list of permitted owners for the alias file. If it is unset, no check on the ownership is done. If the file is not owned by a user in the list, the director fails and the message is frozen.

owngroups (aliasfile) option

Option: owngroups
Type: string-list
Default: unset

This specifies a list of permitted groups for the alias file. If it is unset, no check on the file's group is done. If the file's group is not in the list, the director fails and the message is frozen.

pipe_transport (aliasfile) option

Option: pipe_transport
Type: string
Default: unset

An `aliasfile' director sets up a direct delivery to a pipe when a string starting with a vertical bar character is specified as a new `address' (see chapter "Default transports"). The transport used is taken from the global option `address_pipe', unless this option is set to override it. The string, after expansion, must be the name of a configured transport.

qualify_preserve_domain (aliasfile) option

Option: qualify_preserve_domain
Type: boolean
Default: false

If this is set and an unqualified address (one without a domain) is generated, it is qualified with the domain of the incoming address instead of the global setting in `qualify_recipient'.

queries (aliasfile) option

Option: queries
Type: string
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) option

Option: query
Type: string
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 "File and database lookups" 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.

rewrite (aliasfile) option

Option: rewrite
Type: boolean
Default: true

If this option is set false, addresses generated by the director are not subject to address rewriting. Otherwise, they are treated like new addresses.

search_type (aliasfile) option

Option: search_type
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 "File and database lookups" 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:'.

skip_syntax_errors (aliasfile) option

Option: skip_syntax_errors
Type: boolean
Default: false

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. Exim always considers it to be an error if no addresses at all are generated, even if this option is set.

syntax_errors_text (aliasfile) option

Option: syntax_errors_text
Type: string
Default: unset

See `syntax_errors_to'.

syntax_errors_to (aliasfile) option

Option: syntax_errors_to
Type: string
Default: unset

This option applies only when `skip_syntax_errors' is set. If any addresses are skipped because of syntax errors, a mail message is sent to the address specified by `syntax_errors_to', giving details of the failing address(es). If `syntax_errors_text' is set, its contents are expanded and placed at the head of the error message. Often it will be appropriate to set `syntax_errors_to' to be the same address as the generic `errors_to' option.


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