Exim Specification - 21. Additional generic options for directors

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

# 21. Additional generic options for directors

The following additional generic options apply to all directors, in addition to the generic options common to both directors and routers which are described in chapter 20. Directors are concerned with addresses whose domains match something in local_domains, or which have been explicitly determined to be local by a router.

### current_directory (director)

Type: string, expanded
Default: unset

This option associates a current directory with any address that a director 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. During the delivery process (that is, at transport time), this option string is expanded and is set as the current directory, unless overridden by a setting on the transport. See chapter 13 for details of the local delivery environment. The forwardfile director handles this option in a special way (see section 24.6).

### expn (director)

Type: boolean
Default: true

If this option is turned off, the director is skipped when testing an address as a result of processing an SMTP EXPN command. You might, for example, want to turn it off on a director for users' ``.forward'` files, while leaving it on for the system alias file. The use of the SMTP EXPN command is permitted only from hosts that match the smtp_expn_hosts main configuration option.

This option is specific to directors because EXPN applies only to local addresses, so no address that is an argument to EXPN is ever passed to any router. When Exim is running an EXPN command, it is similar to testing an address with -bt. Compare VRFY, whose counterpart is -bv.

### home_directory (director)

Type: string, expanded
Default: unset

This option associates a home directory with any address that a director 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. During the delivery process (that is, at transport time), the option string is expanded and is set as the home directory, unless overridden by a setting on the transport. 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. See chapter 13 for details of the local delivery environment. The forwardfile and localuser directors handle this option in a special way (see section 24.6).

### new_director (director)

Type: string
Default: unset

Sometimes an administrator knows that it is pointless to reprocess addresses generated from alias or forward files with the same director again. For example, if an alias file translates real names into login ids there is no point searching the alias file again, especially if it is a large file.

The new_director option can be set to the name of any director instance. It causes the directing of any generated local addresses to start at the named director instead of the first director. The named director can be any configured director. This option has no effect if the director in which it is set does not generate new addresses, or if such addresses are not in local domains.

### prefix (director)

Type: string list
Default: unset

If this option is set, the director is skipped unless the local part starts with one of the given strings, or the prefix_optional option is true. The list is scanned from left to right, and the first prefix that matches is used. A limited form of wildcard is available; if the prefix begins with an asterisk, it matches the longest possible sequence of arbitrary characters at the start of the local part. An asterisk should therefore always be followed by some character that does not occur in normal local parts. Wildcarding can be used to set up multiple user mailboxes, as described in chapter 41.

While the director is running, the prefix is removed from the local part, and is available in the expansion variable local_part_prefix. If the director succeeds, this remains true during subsequent delivery.

The prefix facility is commonly used to handle local parts of the form owner-something. Another common use is to support local parts of the form real-username to bypass a user's ``.forward'` file -- helpful when trying to tell a user their forwarding is broken -- by placing a director like this one immediately before the director that handles ``.forward'` files:

    real_localuser:
      driver = localuser
      transport = local_delivery
      prefix = real-

If both prefix and suffix are set for a director, both conditions must be met if not optional. Care must be taken if wildcards are used in both a prefix and a suffix on the same director. Different separator characters must be used to avoid ambiguity.

### prefix_optional (director)

Type: boolean
Default: false

See prefix above.

### suffix (director)

Type: string list
Default: unset

This option operates in the same way as prefix, except that the local part must end (rather than start) with the given string, the suffix_optional option determines whether the suffix is mandatory, and the wildcard * character, if present, must be the last character of the suffix. This option facility is commonly used to handle local parts of the form something-request and multiple user mailboxes of the form username-foo.

### suffix_optional (director)

Type: boolean
Default: false

See suffix above.

## 21.1 Skipping directors

Section 20.1 above describes the circumstances in which the generic options that are common to both directors and routers cause a driver to be skipped. Directors have additional generic options which impose some further condition.

The new_director generic option causes the directing of a generated local address to start at a particular director, thus skipping those above it for that address.

Processing of the prefix and suffix options does not happen until after the check of local_parts is done, so the local part that is checked at that stage is the full local part. If you want to select a director based on a partial local part, you can use a regular expression, or make use of the condition option to do more complicated processing (such as looking up a prefix-stripped local part in a file).

The following additional conditions, which are applied after the initial checks on the domain etc., prevent the current director from being run:

- An SMTP EXPN command is being processed and the director's expn option is turned off, or
- There is a prefix or suffix mismatch, or
- The address was generated by aliasing or forwarding and is identical to an ancestor address that was processed by this director. This restriction breaks addressing loops.

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