exim (8) - Linux Manuals
exim: a Mail Transfer Agent
NAME
exim - a Mail Transfer AgentSYNOPSIS
exim [options] arguments ... mailq [options] arguments ... rsmtp [options] arguments ... rmail [options] arguments ... runq [options] arguments ... newaliases [options] arguments ...
DESCRIPTION
Exim is a mail transfer agent (MTA) developed at the University of Cambridge. It is a large program with very many facilities. For a full specification, see the reference manual. This man page contains only a description of the command line options. It has been automatically generated from the reference manual source, hopefully without too much mangling.
Like other MTAs, Exim replaces Sendmail, and is normally called by user agents (MUAs) using the path /usr/sbin/sendmail when they submit messages for delivery (some operating systems use /usr/lib/sendmail). This path is normally set up as a symbolic link to the Exim binary. It may also be used by boot scripts to start the Exim daemon. Many of Exim's command line options are compatible with Sendmail so that it can act as a drop-in replacement.
DEFAULT ACTION
If no options are present that require a specific action (such as starting the daemon or a queue runner, testing an address, receiving a message in a specific format, or listing the queue), and there are no arguments on the command line, Exim outputs a brief message about itself and exits.
However, if there is at least one command line argument, -bm (accept a local message on the standard input, with the arguments specifying the recipients) is assumed. Thus, for example, if Exim is installed in /usr/sbin, you can send a message from the command line like this:
The -i option prevents a line containing just a dot from terminating
the message. Only an end-of-file (generated by typing CTRL-D if the input is
from a terminal) does so.
If an Exim binary is called using one of the names listed in this section
(typically via a symbolic link), certain options are assumed.
The -bd option can be used only by an admin user. If either of the -d
(debugging) or -v (verifying) options are set, the daemon does not
disconnect from the controlling terminal. When running this way, it can be
stopped by pressing ctrl-C.
By default, Exim listens for incoming connections to the standard SMTP port on
all the host's running interfaces. However, it is possible to listen on other
ports, on multiple ports, and only on specific interfaces.
When a listening daemon
is started without the use of -oX (that is, without overriding the normal
configuration), it writes its process id to a file called exim-daemon.pid
in Exim's spool directory. This location can be overridden by setting
PID_FILE_PATH in Local/Makefile. The file is written while Exim is still
running as root.
When -oX is used on the command line to start a listening daemon, the
process id is not written to the normal pid file path. However, -oP can be
used to specify a path on the command line if a pid file is required.
The SIGHUP signal
can be used to cause the daemon to re-execute itself. This should be done
whenever Exim's configuration file, or any file that is incorporated into it by
means of the .include facility, is changed, and also whenever a new version
of Exim is installed. It is not necessary to do this when other files that are
referenced from the configuration (for example, alias files) are changed,
because these are reread each time they are used.
If Exim was built with USE_READLINE=yes in Local/Makefile, it tries
to load the libreadline library dynamically whenever the -be option is
used without command line arguments. If successful, it uses the readline()
function, which provides extensive line-editing facilities, for reading the
test data. A line history is supported.
Long expansion expressions can be split over several lines by using backslash
continuations. As in Exim's run time configuration, white space at the start of
continuation lines is ignored. Each argument or data line is passed through the
string expansion mechanism, and the result is output. Variable values from the
configuration file (for example, $qualify_domain) are available, but no
message-specific values (such as $message_exim_id) are set, because no message
is being processed (but see -bem and -Mset).
Note: If you use this mechanism to test lookups, and you change the data
files or databases you are using, you must exit and restart Exim before trying
the same lookup again. Otherwise, because each Exim process caches the results
of lookups, you will just get the same result as before.
The file is read as a message (as if receiving a locally-submitted non-SMTP
message) before any of the test expansions are done. Thus, message-specific
variables such as $message_size and $header_from: are available. However,
no Received: header is added to the message. If the -t option is set,
recipients are read from the headers in the normal way, and are shown in the
$recipients variable. Note that recipients cannot be given on the command
line, because further arguments are taken as strings to expand (just like
-be).
If you want to test a system filter file, use -bF instead of -bf. You
can use both -bF and -bf on the same command, in order to test a system
filter and a user filter in the same run. For example:
This is helpful when the system filter adds header lines or sets filter
variables that are used by the user filter.
If the test filter file does not begin with one of the special lines
it is taken to be a normal .forward file, and is tested for validity under
that interpretation.
The result of an Exim command that uses -bf, provided no errors are
detected, is a list of the actions that Exim would try to take if presented
with the message for real. More details of filter testing are given in the
separate document entitled Exim's interfaces to mail filtering.
When testing a filter file,
the envelope sender can be set by the -f option,
or by a "From " line at the start of the test message. Various parameters
that would normally be taken from the envelope recipient address of the message
can be set by means of additional command line options (see the next four
options).
When an IPv6 address is given, it is converted into canonical form. In the case
of the second example above, the value of $sender_host_address after
conversion to the canonical form is
fe80:0000:0000:0a00:20ff:fe86:a061.5678.
Comments as to what is going on are written to the standard error file. These
include lines beginning with "LOG" for anything that would have been logged.
This facility is provided for testing configuration options for incoming
messages, to make sure they implement the required policy. For example, you can
test your relay controls using -bh.
Warning 1:
You can test features of the configuration that rely on ident (RFC 1413)
information by using the -oMt option. However, Exim cannot actually perform
an ident callout when testing using -bh because there is no incoming SMTP
connection.
Warning 2: Address verification callouts
are also skipped when testing using -bh. If you want these callouts to
occur, use -bhc instead.
Messages supplied during the testing session are discarded, and nothing is
written to any of the real log files. There may be pauses when DNS (and other)
lookups are taking place, and of course these may time out. The -oMi option
can be used to specify a specific IP interface and port if this is important,
and -oMaa and -oMai can be used to set parameters as if the SMTP
session were authenticated.
The exim_checkaccess utility is a "packaged" version of -bh whose
output just states whether a given recipient address from a given host is
acceptable or not.
Features such as authentication and encryption, where the client input is not
plain text, cannot easily be tested with -bh. Instead, you should use a
specialized SMTP test program such as
swaks.
If -bi is encountered, the command specified by the bi_command
configuration option is run, under the uid and gid of the caller of Exim. If
the -oA option is used, its value is passed to the command as an argument.
The command set by bi_command may not contain arguments. The command can
use the exim_dbmbuild utility, or some other means, to rebuild alias files
if this is required. If the bi_command option is not set, calling Exim with
-bi is a no-op.
If any addresses in the message are unqualified (have no domain), they are
qualified by the values of the qualify_domain or qualify_recipient
options, as appropriate. The -bnq option (see below) provides a way of
suppressing this for special cases.
Policy checks on the contents of local messages can be enforced by means of
the non-SMTP ACL.
The return code is zero if the message is successfully accepted. Otherwise, the
action is controlled by the -oex option setting - see below.
The format
of the message must be as defined in RFC 2822, except that, for
compatibility with Sendmail and Smail, a line in one of the forms
(with the weekday optional, and possibly with additional text after the date)
is permitted to appear at the start of the message. There appears to be no
authoritative specification of the format of this line. Exim recognizes it by
matching against the regular expression defined by the uucp_from_pattern
option, which can be changed if necessary.
The specified sender is treated as if it were given as the argument to the
-f option, but if a -f option is also present, its argument is used in
preference to the address taken from the message. The caller of Exim must be a
trusted user for the sender of a message to be set in this way.
Exim will have changed working directory before resolving the filename, so
using fully qualified pathnames is advisable. Exim will be running as the Exim
user when it tries to open the file, rather than as the invoking user.
This option requires admin privileges.
The -bmalware option will not be extended to be more generally useful,
there are better tools for file-scanning. This option exists to help
administrators verify their Exim and AV scanner configuration.
Sometimes, qualification is not wanted. For example, if -bS (batch SMTP) is
being used to re-submit messages that originally came from remote hosts after
content scanning, you probably do not want to qualify unqualified addresses in
header lines. (Such lines will be present only if you have not enabled a header
syntax check in the appropriate ACL.)
The -bnq option suppresses all qualification of unqualified addresses in
messages that originate on the local host. When this is used, unqualified
addresses in the envelope provoke errors (causing message rejection) and
unqualified addresses in header lines are left alone.
However, any option setting that is preceded by the word "hide" in the
configuration file is not shown in full, except to an admin user. For other
users, the output is as in this example:
If config is given as an argument, the config is
output, as it was parsed, any include file resolved, any comment removed.
If config_file is given as an argument, the name of the run time
configuration file is output. (configure_file works too, for
backward compatibility.)
If a list of configuration files was supplied, the value that is output here
is the name of the file that was actually used.
If the -n flag is given, then for most modes of -bP operation the
name will not be output.
If log_file_path or pid_file_path are given, the names of the
directories where log files and daemon pid files are written are output,
respectively. If these values are unset, log files are written in a
sub-directory of the spool directory called log, and the pid file is
written directly into the spool directory.
If -bP is followed by a name preceded by +, for example,
it searches for a matching named list of any type (domain, host, address, or
local part) and outputs what it finds.
If one of the words router, transport, or authenticator is given,
followed by the name of an appropriate driver instance, the option settings for
that driver are output. For example:
The generic driver options are output first, followed by the driver's private
options. A list of the names of drivers of a particular type can be obtained by
using one of the words router_list, transport_list, or
authenticator_list, and a complete list of all drivers with their option
settings can be obtained by using routers, transports, or
authenticators.
If environment is given as an argument, the set of environment
variables is output, line by line. Using the -n flag suppresses the value of the
variables.
If invoked by an admin user, then macro, macro_list and macros
are available, similarly to the drivers. Because macros are sometimes used
for storing passwords, this option is restricted.
The output format is one item per line.
Each message on the queue is displayed as in the following example:
The first line contains the length of time the message has been on the queue
(in this case 25 minutes), the size of the message (2.9K), the unique local
identifier for the message, and the message sender, as contained in the
envelope. For bounce messages, the sender address is empty, and appears as
"<>". If the message was submitted locally by an untrusted user who overrode
the default sender address, the user's login name is shown in parentheses
before the sender address.
If the message is frozen (attempts to deliver it are suspended) then the text
"*** frozen ***" is displayed at the end of this line.
The recipients of the message (taken from the envelope, not the headers) are
displayed on subsequent lines. Those addresses to which the message has already
been delivered are marked with the letter D. If an original address gets
expanded into several addresses via an alias or forward file, the original is
displayed with a D only when deliveries for all of its child addresses are
complete.
The message itself is read from the standard input, in SMTP format (leading
dots doubled), terminated by a line containing just a single dot. An error is
provoked if the terminating dot is missing. A further message may then follow.
As for other local message submissions, the contents of incoming batch SMTP
messages can be checked using the non-SMTP ACL.
Unqualified addresses are automatically qualified using qualify_domain and
qualify_recipient, as appropriate, unless the -bnq option is used.
Some other SMTP commands are recognized in the input. HELO and EHLO act
as RSET; VRFY, EXPN, ETRN, and HELP act as NOOP;
QUIT quits, ignoring the rest of the standard input.
If any error is encountered, reports are written to the standard output and
error streams, and Exim gives up immediately. The return code is 0 if no error
was detected; it is 1 if one or more messages were accepted before the error
was detected; otherwise it is 2.
In
this usage, if the caller of Exim is trusted, or untrusted_set_sender is
set, the senders of messages are taken from the SMTP MAIL commands.
Otherwise the content of these commands is ignored and the sender is set up as
the calling user. Unqualified addresses are automatically qualified using
qualify_domain and qualify_recipient, as appropriate, unless the
-bnq option is used.
The
-bs option is also used to run Exim from inetd, as an alternative to
using a listening daemon. Exim can distinguish the two cases by checking
whether the standard input is a TCP/IP socket. When Exim is called from
inetd, the source of the mail is assumed to be remote, and the comments
above concerning senders and qualification do not apply. In this situation,
Exim behaves in exactly the same way as it does when receiving a message via
the listening daemon.
If no arguments are given, Exim runs in an interactive manner, prompting with a
right angle bracket for addresses to be tested.
Unlike the -be test option, you cannot arrange for Exim to use the
readline() function, because it is running as root and there are
security issues.
Each address is handled as if it were the recipient address of a message
(compare the -bv option). It is passed to the routers and the result is
written to the standard output. However, any router that has
no_address_test set is bypassed. This can make -bt easier to use for
genuine routing tests if your first router passes everything to a scanner
program.
The return code is 2 if any address failed outright; it is 1 if no address
failed outright but at least one could not be resolved for some reason. Return
code 0 is given only when all addresses succeed.
Note: When actually delivering a message, Exim removes duplicate recipient
addresses after routing is complete, so that only one delivery takes place.
This does not happen when testing with -bt; the full results of routing are
always shown.
Warning: -bt can only do relatively simple testing. If any of the
routers in the configuration makes any tests on the sender address of a
message,
you can use the -f option to set an appropriate sender when running
-bt tests. Without it, the sender is assumed to be the calling user at the
default qualifying domain. However, if you have set up (for example) routers
whose behaviour depends on the contents of an incoming message, you cannot test
those conditions using -bt. The -N option provides a possible way of
doing such tests.
As part of its operation, -bV causes Exim to read and syntax check its
configuration file. However, this is a static check only. It cannot check
values that are to be expanded. For example, although a misspelt ACL verb is
detected, an error in the verb's arguments is not. You cannot rely on -bV
alone to discover (for example) all the typos in the configuration; some
realistic testing is needed. The -bh and -N options provide more
dynamic testing facilities.
If verification fails, and the caller is not an admin user, no details of the
failure are output, because these might contain sensitive information such as
usernames and passwords for database lookups.
If no arguments are given, Exim runs in an interactive manner, prompting with a
right angle bracket for addresses to be verified.
Unlike the -be test option, you cannot arrange for Exim to use the
readline() function, because it is running as exim and there are
security issues.
Verification differs from address testing (the -bt option) in that routers
that have no_verify set are skipped, and if the address is accepted by a
router that has fail_verify set, verification fails. The address is
verified as a recipient if -bv is used; to test verification for a sender
address, -bvs should be used.
If the -v option is not set, the output consists of a single line for each
address, stating whether it was verified or not, and giving a reason in the
latter case. Without -v, generating more than one address by redirection
causes verification to end successfully, without considering the generated
addresses. However, if just one address is generated, processing continues,
and the generated address must verify successfully for the overall verification
to succeed.
When -v is set, more details are given of how the address has been handled,
and in the case of address redirection, all the generated addresses are also
considered. Verification may succeed for some and fail for others.
The
return code is 2 if any address failed outright; it is 1 if no address
failed outright but at least one could not be resolved for some reason. Return
code 0 is given only when all addresses succeed.
If any of the routers in the configuration makes any tests on the sender
address of a message, you should use the -f option to set an appropriate
sender when running -bv tests. Without it, the sender is assumed to be the
calling user at the default qualifying domain.
In this mode, Exim expects to be passed a socket as fd 0 (stdin) which is
listening for connections. This permits the system to start up and have
inetd (or equivalent) listen on the SMTP ports, starting an Exim daemon for
each port only when the first connection is received.
If the option is given as -bw<time> then the time is a timeout, after
which the daemon will exit, which should cause inetd to listen once more.
When this option is used by a caller other than root, and the list is different
from the compiled-in list, Exim gives up its root privilege immediately, and
runs with the real and effective uid and gid set to those of the caller.
However, if a TRUSTED_CONFIG_LIST file is defined in Local/Makefile, that
file contains a list of full pathnames, one per line, for configuration files
which are trusted. Root privilege is retained for any configuration file so
listed, as long as the caller is the Exim user (or the user specified in the
CONFIGURE_OWNER option, if any), and as long as the configuration file is
not writeable by inappropriate users or groups.
Leaving TRUSTED_CONFIG_LIST unset precludes the possibility of testing a
configuration using -C right through message reception and delivery,
even if the caller is root. The reception works, but by that time, Exim is
running as the Exim user, so when it re-executes to regain privilege for the
delivery, the use of -C causes privilege to be lost. However, root can
test reception and delivery using two separate commands (one to put a message
on the queue, using -odq, and another to do the delivery, using -M).
If ALT_CONFIG_PREFIX is defined in Local/Makefile, it specifies a
prefix string with which any file named in a -C command line option
must start. In addition, the file name must not contain the sequence /../.
However, if the value of the -C option is identical to the value of
CONFIGURE_FILE in Local/Makefile, Exim ignores -C and proceeds as
usual. There is no default setting for ALT_CONFIG_PREFIX; when it is
unset, any file name can be used with -C.
ALT_CONFIG_PREFIX can be used to confine alternative configuration files
to a directory to which only root has access. This prevents someone who has
broken into the Exim account from running a privileged Exim with an arbitrary
configuration file.
The -C facility is useful for ensuring that configuration files are
syntactically correct, but cannot be used for test deliveries, unless the
caller is privileged, or unless it is an exotic configuration that does not
require privilege. No check is made on the owner or group of the files
specified by this option.
If WHITELIST_D_MACROS is defined in Local/Makefile then it should be a
colon-separated list of macros which are considered safe and, if -D only
supplies macros from this list, and the values are acceptable, then Exim will
not give up root privilege if the caller is root, the Exim run-time user, or
the CONFIGURE_OWNER, if set. This is a transition mechanism and is expected
to be removed in the future. Acceptable values for the macros satisfy the
regexp: ^[A-Za-z0-9_/.-]*$
The entire option (including equals sign if present) must all be within one
command line item. -D can be used to set the value of a macro to the empty
string, in which case the equals sign is optional. These two commands are
synonymous:
To include spaces in a macro definition item, quotes must be used. If you use
quotes, spaces are permitted around the macro name and the equals sign. For
example:
-D may be repeated up to 10 times on a command line.
Only macro names up to 22 letters long can be set.
When -d is used, -v is assumed. If -d is given on its own, a lot of
standard debugging data is output. This can be reduced, or increased to include
some more rarely needed information, by directly following -d with a string
made up of names preceded by plus or minus characters. These add or remove sets
of debugging data, respectively. For example, -d+filter adds filter
debugging, whereas -d-all+filter selects only filter debugging. Note that
no spaces are allowed in the debug setting. The available debugging categories
are:
SETTING OPTIONS BY PROGRAM NAME
OPTIONS