7
Postfix local mail delivery
11
\fBlocal\fR [generic Postfix daemon options]
15
The \fBlocal\fR daemon processes delivery requests from the
16
Postfix queue manager to deliver mail to local recipients.
17
Each delivery request specifies a queue file, a sender address,
18
a domain or host to deliver to, and one or more recipients.
19
This program expects to be run from the \fBmaster\fR(8) process
22
The \fBlocal\fR daemon updates queue files and marks recipients
23
as finished, or it informs the queue manager that delivery should
24
be tried again at a later time. Delivery status reports are sent
25
to the \fBbounce\fR(8), \fBdefer\fR(8) or \fBtrace\fR(8) daemon as
27
.SH "SYSTEM-WIDE AND USER-LEVEL ALIASING"
32
The system administrator can set up one or more system-wide
33
\fBsendmail\fR-style alias databases.
34
Users can have \fBsendmail\fR-style ~/.\fBforward\fR files.
35
Mail for \fIname\fR is delivered to the alias \fIname\fR, to
36
destinations in ~\fIname\fR/.\fBforward\fR, to the mailbox owned
37
by the user \fIname\fR, or it is sent back as undeliverable.
39
The system administrator can specify a comma/space separated list
40
of ~\fR/.\fBforward\fR like files through the \fBforward_path\fR
41
configuration parameter. Upon delivery, the local delivery agent
42
tries each pathname in the list until a file is found.
43
The \fBforward_path\fR parameter is subject to interpolation of
44
\fB$user\fR (recipient username), \fB$home\fR (recipient home
45
directory), \fB$shell\fR (recipient shell), \fB$recipient\fR
46
(complete recipient address), \fB$extension\fR (recipient address
47
extension), \fB$domain\fR (recipient domain), \fBlocal\fR
48
(entire recipient address localpart) and
49
\fB$recipient_delimiter.\fR The forms \fI${name?value}\fR and
50
\fI${name:value}\fR expand conditionally to \fIvalue\fR when
51
\fI$name\fR is (is not) defined.
52
Characters that may have special meaning to the shell or file system
53
are replaced by underscores. The list of acceptable characters
54
is specified with the \fBforward_expansion_filter\fR configuration
57
An alias or ~/.\fBforward\fR file may list any combination of external
58
commands, destination file names, \fB:include:\fR directives, or
60
See \fBaliases\fR(5) for a precise description. Each line in a
61
user's .\fBforward\fR file has the same syntax as the right-hand part
64
When an address is found in its own alias expansion, delivery is
65
made to the user instead. When a user is listed in the user's own
66
~/.\fBforward\fR file, delivery is made to the user's mailbox instead.
67
An empty ~/.\fBforward\fR file means do not forward mail.
69
In order to prevent the mail system from using up unreasonable
70
amounts of memory, input records read from \fB:include:\fR or from
71
~/.\fBforward\fR files are broken up into chunks of length
72
\fBline_length_limit\fR.
74
While expanding aliases, ~/.\fBforward\fR files, and so on, the
75
program attempts to avoid duplicate deliveries. The
76
\fBduplicate_filter_limit\fR configuration parameter limits the
77
number of remembered recipients.
83
For the sake of reliability, forwarded mail is re-submitted as
84
a new message, so that each recipient has a separate on-file
85
delivery status record.
87
In order to stop mail forwarding loops early, the software adds an
89
\fBDelivered-To:\fR header with the final envelope recipient address. If
90
mail arrives for a recipient that is already listed in a
91
\fBDelivered-To:\fR header, the message is bounced.
92
.SH "MAILBOX DELIVERY"
97
The default per-user mailbox is a file in the UNIX mail spool
98
directory (\fB/var/mail/\fIuser\fR or \fB/var/spool/mail/\fIuser\fR);
99
the location can be specified with the \fBmail_spool_directory\fR
100
configuration parameter. Specify a name ending in \fB/\fR for
101
\fBqmail\fR-compatible \fBmaildir\fR delivery.
103
Alternatively, the per-user mailbox can be a file in the user's home
104
directory with a name specified via the \fBhome_mailbox\fR
105
configuration parameter. Specify a relative path name. Specify a name
106
ending in \fB/\fR for \fBqmail\fR-compatible \fBmaildir\fR delivery.
108
Mailbox delivery can be delegated to an external command specified
109
with the \fBmailbox_command\fR configuration parameter. The command
110
executes with the privileges of the recipient user (exception: in
111
case of delivery as root, the command executes with the privileges
112
of \fBdefault_privs\fR).
114
Mailbox delivery can be delegated to alternative message transports
115
specified in the \fBmaster.cf\fR file.
116
The \fBmailbox_transport\fR configuration parameter specifies a
117
message transport that is to be used for all local recipients,
118
regardless of whether they are found in the UNIX passwd database.
119
The \fBfallback_transport\fR parameter specifies a message transport
120
for recipients that are not found in the UNIX passwd database.
122
In the case of UNIX-style mailbox delivery,
123
the \fBlocal\fR daemon prepends a "\fBFrom \fIsender time_stamp\fR"
124
envelope header to each message, prepends an
125
\fBX-Original-To:\fR header with the recipient address as given to
127
optional \fBDelivered-To:\fR header
128
with the final envelope recipient address, prepends a \fBReturn-Path:\fR
129
header with the envelope sender address, prepends a \fB>\fR character
130
to lines beginning with "\fBFrom \fR", and appends an empty line.
131
The mailbox is locked for exclusive access while delivery is in
132
progress. In case of problems, an attempt is made to truncate the
133
mailbox to its original length.
135
In the case of \fBmaildir\fR delivery, the local daemon prepends
137
\fBDelivered-To:\fR header with the final envelope recipient address,
139
\fBX-Original-To:\fR header with the recipient address as given to
141
and prepends a \fBReturn-Path:\fR header with the envelope sender
143
.SH "EXTERNAL COMMAND DELIVERY"
148
The \fBallow_mail_to_commands\fR configuration parameter restricts
149
delivery to external commands. The default setting (\fBalias,
150
forward\fR) forbids command destinations in \fB:include:\fR files.
152
The command is executed directly where possible. Assistance by the
153
shell (\fB/bin/sh\fR on UNIX systems) is used only when the command
154
contains shell magic characters, or when the command invokes a shell
157
A limited amount of command output (standard output and standard
158
error) is captured for inclusion with non-delivery status reports.
159
A command is forcibly terminated if it does not complete within
160
\fBcommand_time_limit\fR seconds. Command exit status codes are
161
expected to follow the conventions defined in <\fBsysexits.h\fR>.
163
A limited amount of message context is exported via environment
164
variables. Characters that may have special meaning to the shell
165
are replaced by underscores. The list of acceptable characters
166
is specified with the \fBcommand_expansion_filter\fR configuration
169
The recipient user's login shell.
171
The recipient user's home directory.
173
The bare recipient name.
175
The optional recipient address extension.
177
The recipient address domain part.
179
The bare recipient name.
181
The entire recipient address localpart (text to the left of the
182
rightmost @ character).
184
The entire recipient address.
186
The entire sender address.
188
The \fBPATH\fR environment variable is always reset to a
189
system-dependent default path, and environment variables
190
whose names are blessed by the \fBexport_environment\fR
191
configuration parameter are exported unchanged.
193
The current working directory is the mail queue directory.
195
The \fBlocal\fR daemon prepends a "\fBFrom \fIsender time_stamp\fR"
196
envelope header to each message, prepends an
197
\fBX-Original-To:\fR header with the recipient address as given to
199
optional \fBDelivered-To:\fR
200
header with the final recipient envelope address, prepends a
201
\fBReturn-Path:\fR header with the sender envelope address,
202
and appends no empty line.
203
.SH "EXTERNAL FILE DELIVERY"
208
The delivery format depends on the destination filename syntax.
209
The default is to use UNIX-style mailbox format. Specify a name
210
ending in \fB/\fR for \fBqmail\fR-compatible \fBmaildir\fR delivery.
212
The \fBallow_mail_to_files\fR configuration parameter restricts
213
delivery to external files. The default setting (\fBalias,
214
forward\fR) forbids file destinations in \fB:include:\fR files.
216
In the case of UNIX-style mailbox delivery,
217
the \fBlocal\fR daemon prepends a "\fBFrom \fIsender time_stamp\fR"
218
envelope header to each message, prepends an
219
\fBX-Original-To:\fR header with the recipient address as given to
221
optional \fBDelivered-To:\fR
222
header with the final recipient envelope address, prepends a \fB>\fR
223
character to lines beginning with "\fBFrom \fR", and appends an
225
The envelope sender address is available in the \fBReturn-Path:\fR
227
When the destination is a regular file, it is locked for exclusive
228
access while delivery is in progress. In case of problems, an attempt
229
is made to truncate a regular file to its original length.
231
In the case of \fBmaildir\fR delivery, the local daemon prepends
233
\fBDelivered-To:\fR header with the final envelope recipient address,
235
\fBX-Original-To:\fR header with the recipient address as given to
237
The envelope sender address is available in the \fBReturn-Path:\fR
239
.SH "ADDRESS EXTENSION"
244
The optional \fBrecipient_delimiter\fR configuration parameter
245
specifies how to separate address extensions from local recipient
248
For example, with "\fBrecipient_delimiter = +\fR", mail for
249
\fIname\fR+\fIfoo\fR is delivered to the alias \fIname\fR+\fIfoo\fR
250
or to the alias \fIname\fR, to the destinations listed in
251
~\fIname\fR/.\fBforward\fR+\fIfoo\fR or in ~\fIname\fR/.\fBforward\fR,
252
to the mailbox owned by the user \fIname\fR, or it is sent back as
255
In all cases the \fBlocal\fR daemon prepends an optional
256
`\fBDelivered-To:\fR header line with the final recipient
258
.SH "DELIVERY RIGHTS"
263
Deliveries to external files and external commands are made with
264
the rights of the receiving user on whose behalf the delivery is made.
265
In the absence of a user context, the \fBlocal\fR daemon uses the
266
owner rights of the \fB:include:\fR file or alias database.
267
When those files are owned by the superuser, delivery is made with
268
the rights specified with the \fBdefault_privs\fR configuration
273
RFC 822 (ARPA Internet Text Messages)
277
Problems and transactions are logged to \fBsyslogd\fR(8).
278
Corrupted message files are marked so that the queue
279
manager can move them to the \fBcorrupt\fR queue afterwards.
281
Depending on the setting of the \fBnotify_classes\fR parameter,
282
the postmaster is notified of bounces and of other trouble.
286
For security reasons, the message delivery status of external commands
287
or of external files is never checkpointed to file. As a result,
288
the program may occasionally deliver more than once to a command or
289
external file. Better safe than sorry.
291
Mutually-recursive aliases or ~/.\fBforward\fR files are not detected
292
early. The resulting mail forwarding loop is broken by the use of the
293
\fBDelivered-To:\fR message header.
294
.SH "CONFIGURATION PARAMETERS"
299
Changes to \fBmain.cf\fR are picked up automatically, as local(8)
300
processes run for only a limited amount of time. Use the command
301
"\fBpostfix reload\fR" to speed up a change.
303
The text below provides only a parameter summary. See
304
postconf(5) for more details including examples.
305
.SH "COMPATIBILITY CONTROLS"
310
.IP "\fBbiff (yes)\fR"
311
Whether or not to use the local biff service.
312
.IP "\fBexpand_owner_alias (no)\fR"
313
When delivering to an alias "aliasname" that has an "owner-aliasname"
314
companion alias, set the envelope sender address to the expansion
315
of the "owner-aliasname" alias.
316
.IP "\fBowner_request_special (yes)\fR"
317
Give special treatment to owner-listname and listname-request
318
address localparts: don't don't split such addresses when the
319
recipient_delimiter is set to "-".
320
.IP "\fBsun_mailtool_compatibility (no)\fR"
321
Obsolete SUN mailtool compatibility feature.
322
.SH "DELIVERY METHOD CONTROLS"
327
The precedence of local(8) delivery methods from high to low is:
328
aliases, .forward files, mailbox_transport, mailbox_command_maps,
329
mailbox_command, home_mailbox, mail_spool_directory, fallback_transport
331
.IP "\fBalias_maps (see 'postconf -d' output)\fR"
332
The alias databases that are used for local(8) delivery.
333
.IP "\fBforward_path (see 'postconf -d' output)\fR"
334
The local(8) delivery agent search list for finding a .forward
335
file with user-specified delivery methods.
336
.IP "\fBmailbox_transport (empty)\fR"
337
Optional message delivery transport that the local(8) delivery
338
agent should use for mailbox delivery to all local recipients,
339
whether or not they are found in the UNIX passwd database.
340
.IP "\fBmailbox_command_maps (empty)\fR"
341
Optional lookup tables with per-recipient external commands to use
342
for local(8) mailbox delivery.
343
.IP "\fBmailbox_command (empty)\fR"
344
Optional external command that the local(8) delivery agent should
345
use for mailbox delivery.
346
.IP "\fBhome_mailbox (empty)\fR"
347
Optional pathname of a mailbox file relative to a local(8) user's
349
.IP "\fBmail_spool_directory (see 'postconf -d' output)\fR"
350
The directory where local(8) UNIX-style mailboxes are kept.
351
.IP "\fBfallback_transport (empty)\fR"
352
Optional message delivery transport that the local(8) delivery
353
agent should use for names that are not found in the aliases(5)
354
database or in the UNIX passwd database.
355
.IP "\fBluser_relay (empty)\fR"
356
Optional catch-all destination for unknown local(8) recipients.
357
.SH "MAILBOX LOCKING CONTROLS"
362
.IP "\fBdeliver_lock_attempts (20)\fR"
363
The maximal number of attempts to acquire an exclusive lock on a
364
mailbox file or bounce(8) logfile.
365
.IP "\fBdeliver_lock_delay (1s)\fR"
366
The time between attempts to acquire an exclusive lock on a mailbox
367
file or bounce(8) logfile.
368
.IP "\fBstale_lock_time (500s)\fR"
369
The time after which a stale exclusive mailbox lockfile is removed.
370
.IP "\fBmailbox_delivery_lock (see 'postconf -d' output)\fR"
371
How to lock a UNIX-style local(8) mailbox before attempting delivery.
372
.SH "RESOURCE AND RATE CONTROLS"
377
.IP "\fBcommand_time_limit (1000s)\fR"
378
Time limit for delivery to external commands.
379
.IP "\fBduplicate_filter_limit (1000)\fR"
380
The maximal number of addresses remembered by the address
381
duplicate filter for aliases(5) or virtual(5) alias expansion, or
382
for showq(8) queue displays.
383
.IP "\fBlocal_destination_concurrency_limit (2)\fR"
384
The maximal number of parallel deliveries via the local mail
385
delivery transport to the same recipient (when
386
"local_destination_recipient_limit = 1") or the maximal number of
387
parallel deliveries to the same local domain (when
388
"local_destination_recipient_limit > 1").
389
.IP "\fBlocal_destination_recipient_limit (1)\fR"
390
The maximal number of recipients per message delivery via the
391
local mail delivery transport.
392
.IP "\fBmailbox_size_limit (51200000)\fR"
393
The maximal size of any local(8) individual mailbox or maildir
394
file, or zero (no limit).
395
.SH "SECURITY CONTROLS"
400
.IP "\fBallow_mail_to_commands (alias, forward)\fR"
401
Restrict local(8) mail delivery to external commands.
402
.IP "\fBallow_mail_to_files (alias, forward)\fR"
403
Restrict local(8) mail delivery to external files.
404
.IP "\fBcommand_expansion_filter (see 'postconf -d' output)\fR"
405
Restrict the characters that the local(8) delivery agent allows in
406
$name expansions of $mailbox_command.
407
.IP "\fBdefault_privs (nobody)\fR"
408
The default rights used by the local(8) delivery agent for delivery
409
to external file or command.
410
.IP "\fBforward_expansion_filter (see 'postconf -d' output)\fR"
411
Restrict the characters that the local(8) delivery agent allows in
412
$name expansions of $forward_path.
413
.SH "MISCELLANEOUS CONTROLS"
418
.IP "\fBconfig_directory (see 'postconf -d' output)\fR"
419
The default location of the Postfix main.cf and master.cf
421
.IP "\fBdaemon_timeout (18000s)\fR"
422
How much time a Postfix daemon process may take to handle a
423
request before it is terminated by a built-in watchdog timer.
424
.IP "\fBexport_environment (see 'postconf -d' output)\fR"
425
The list of environment variables that a Postfix process will export
426
to non-Postfix processes.
427
.IP "\fBipc_timeout (3600s)\fR"
428
The time limit for sending or receiving information over an internal
429
communication channel.
430
.IP "\fBlocal_command_shell (empty)\fR"
431
Optional shell program for local(8) delivery to non-Postfix command.
432
.IP "\fBmax_idle (100s)\fR"
433
The maximum amount of time that an idle Postfix daemon process
434
waits for the next service request before exiting.
435
.IP "\fBmax_use (100)\fR"
436
The maximal number of connection requests before a Postfix daemon
438
.IP "\fBprepend_delivered_header (command, file, forward)\fR"
439
The message delivery contexts where the Postfix local(8) delivery
440
agent prepends a Delivered-To: message header.
441
.IP "\fBprocess_id (read-only)\fR"
442
The process ID of a Postfix command or daemon process.
443
.IP "\fBprocess_name (read-only)\fR"
444
The process name of a Postfix command or daemon process.
445
.IP "\fBpropagate_unmatched_extensions (canonical, virtual)\fR"
446
What address lookup tables copy an address extension from the lookup
447
key to the lookup result.
448
.IP "\fBqueue_directory (see 'postconf -d' output)\fR"
449
The location of the Postfix top-level queue directory.
450
.IP "\fBrecipient_delimiter (empty)\fR"
451
The separator between user names and address extensions (user+foo).
452
.IP "\fBrequire_home_directory (no)\fR"
453
Whether or not a local(8) recipient's home directory must exist
454
before mail delivery is attempted.
455
.IP "\fBsyslog_facility (mail)\fR"
456
The syslog facility of Postfix logging.
457
.IP "\fBsyslog_name (postfix)\fR"
458
The mail system name that is prepended to the process name in syslog
459
records, so that "smtpd" becomes, for example, "postfix/smtpd".
463
The following are examples; details differ between systems.
464
$HOME/.forward, per-user aliasing
465
/etc/aliases, sytem-wide alias database
466
/var/spool/mail, system mailboxes
470
qmgr(8), queue manager
471
bounce(8), delivery status reports
472
newaliases(1), create/update alias database
473
postalias(1), create/update alias database
474
aliases(5), format of alias database
475
postconf(5), configuration parameters
476
syslogd(8), system logging
482
The Secure Mailer license must be distributed with this software.
488
The \fBDelivered-To:\fR message header appears in the \fBqmail\fR
489
system by Daniel Bernstein.
491
The \fImaildir\fR structure appears in the \fBqmail\fR system
497
IBM T.J. Watson Research
499
Yorktown Heights, NY 10598, USA
added
removed
man/man8/local.8
