Exim Specification - 22. Options common to the aliasfile and forwardfile directors

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

# 22. Options common to the aliasfile and forwardfile directors

The aliasfile and forwardfile directors have a lot in common. Each of them generates a list of new destinations from an incoming address; the main difference is in the way the list is obtained. As Exim has developed, they have grown more and more similar, and one day they may merge into a single director. There are a substantial number of private options that are identical in both these directors, so in order to avoid too much duplication, these common options are described separately in this chapter.

### check_ancestor

Type: boolean
Default: false

This option is concerned with handling generated addresses which are the same as some address in the list of aliasing or forwarding ancestors of the current address. Although it is turned off by default in the code, it is set in the default configuration file for handling users' ``.forward'` files. It is recommended for this use of the forwardfile director, but is not commonly set for aliasfile.

When check_ancestor is set, if a generated address is the same as any ancestor of the current address, it is not used, but instead a copy of the current address is passed on to subsequent directors. This helps in the case where local part A is aliased to B, and B has a ``.forward'` file pointing back to A. For example: `Joe.Bloggs' is aliased to `jb' and ~jb/.forward contains:

    \Joe.Bloggs, <other item(s)>

Without the check_ancestor setting, either local part (`jb' or `joe.bloggs') gets processed once by each director and so ends up as it was originally. If `jb' is the real mailbox name, mail to `jb' gets delivered (having been turned into `joe.bloggs' by the ``.forward'` file and back to `jb' by the alias), but mail to `joe.bloggs' fails. Setting check_ancestor on the forwardfile director prevents it from turning `jb' back into `joe.bloggs' when that was the original address.

### directory_transport

Type: string, expanded
Default: unset

An aliasfile or forwardfile director sets up a direct delivery to a directory when a path name ending with a slash is specified as a new `address'. The transport used is specified by this option, which, after expansion, must be the name of a configured transport.

### directory2_transport

Type: string, expanded
Default: unset

An aliasfile or forwardfile director sets up an alternative direct delivery to a directory when a path name ending with two slashes is specified as a new `address'. The transport used is specified by this option, which, after expansion, must be the name of a configured transport.

### file_transport

Type: string, expanded
Default: unset

An aliasfile or forwardfile director sets up a direct delivery to a file when a path name not ending in a slash is specified as a new `address'. The transport used is specified by this option, which, after expansion, must be the name of a configured transport.

### forbid_file

Type: boolean
Default: false

If this option is true, 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_include

Type: boolean
Default: false

If this option is true, items of the form

    :include:<path name>

are not permitted in alias or forward files, and if one is encountered, the message is frozen.

### forbid_pipe

Type: boolean
Default: false

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

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.

### hide_child_in_errmsg

Type: boolean
Default: false

If this option is set true, it prevents Exim from quoting a child address if it generates a bounce or delay message for it. Instead it says `an address generated from <the top level address>'. Of course, this applies only to bounces generated locally. If a message is forwarded to another host, its bounce may well quote the generated address.

### modemask

Type: octal integer
Default: 022

This specifies mode bits which must not be set for a forward file, or for an alias file which is an actual file. It does not apply when aliases are being looked up using a database query. If any of the forbidden bits is set, delivery is deferred.

### one_time

Type: boolean
Default: false

Sometimes the fact that Exim re-evaluates aliases and reprocesses forward files 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 or forwarding does not happen again at the next delivery attempt. To ensure that the director generates only addresses (as opposed to pipe or file deliveries or auto-replies) forbid_file and forbid_pipe must also be set, and for forwardfile with filter set, forbid_reply 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.

### owners

Type: string list
Default: unset

This specifies a list of permitted owners for a forward file, or for an alias file which is an actual file. It does not apply when aliases are being looked up using a database query. In the case of forwardfile, this list is in addition to the local user when check_local_user is set. If owners is unset (and check_local_user is false for forwardfile), no check on the ownership is done. If the file is not correctly owned, delivery is deferred and the message is frozen.

### owngroups

Type: string list
Default: unset

This specifies a list of permitted groups for a forward file, or for an alias file which is an actual file. It does not apply when aliases are being looked up using a database query. In the case of forwardfile, the list is addition to the local user's group in the case when check_local_user is set. However, group ownership of forward files is checked only when check_group (an option private to forwardfile) is set. If owngroups is unset, no check on the file's group is done. If the file's group is incorrect, the delivery is deferred and the message is frozen.

### pipe_transport

Type: string, expanded
Default: unset

An aliasfile or forwardfile director sets up a direct delivery to a pipe when a string starting with a vertical bar character is specified as a new `address'. The transport used is specified by this option, which, after expansion, must be the name of a configured transport.

### 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.

### 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.

### skip_syntax_errors

Type: boolean
Default: false

If skip_syntax_errors is set, a malformed address in an alias list or a non-filter forward file 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.

For aliasfile, Exim always considers it to be an error if no addresses at all are generated, even if this option is set. However, for forwardfile, if all the addresses in the list are malformed, the original address is passed on to subsequent directors.

If skip_syntax_errors is set for an Exim filter file, any syntax error in the filter file causes filtering to be abandoned, the incident is logged, and the address is passed on to the next director.

### syntax_errors_text

Type: string, expanded
Default: unset

See syntax_errors_to.

### 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.