1LOCAL(8)                    System Manager's Manual                   LOCAL(8)
2
3
4

NAME

6       local - Postfix local mail delivery
7

SYNOPSIS

9       local [generic Postfix daemon options]
10

DESCRIPTION

12       The  local(8) daemon processes delivery requests from the Postfix queue
13       manager to deliver mail to local  recipients.   Each  delivery  request
14       specifies  a  queue file, a sender address, a domain or host to deliver
15       to, and one or more recipients.  This program expects to  be  run  from
16       the master(8) process manager.
17
18       The  local(8)  daemon  updates queue files and marks recipients as fin‐
19       ished, or it informs the queue manager that delivery  should  be  tried
20       again  at  a  later  time.  Delivery  status  reports  are  sent to the
21       bounce(8), defer(8) or trace(8) daemon as appropriate.
22

CASE FOLDING

24       All delivery decisions are made using the bare recipient name (i.e. the
25       address  localpart),  folded  to  lower  case.   See also under ADDRESS
26       EXTENSION below for a few exceptions.
27

SYSTEM-WIDE AND USER-LEVEL ALIASING

29       The system administrator can set up one or more  system-wide  sendmail-
30       style alias databases.  Users can have sendmail-style ~/.forward files.
31       Mail for name is delivered  to  the  alias  name,  to  destinations  in
32       ~name/.forward,  to  the  mailbox owned by the user name, or it is sent
33       back as undeliverable.
34
35       The system administrator can specify a comma/space  separated  list  of
36       ~/.forward like files through the forward_path configuration parameter.
37       Upon delivery, the local delivery agent tries each pathname in the list
38       until a file is found.
39
40       Delivery via ~/.forward files is done with the privileges of the recip‐
41       ient.  Thus, ~/.forward like files must be readable by  the  recipient,
42       and  their  parent directory needs to have "execute" permission for the
43       recipient.
44
45       The forward_path parameter is subject to interpolation of $user (recip‐
46       ient  username),  $home  (recipient  home directory), $shell (recipient
47       shell), $recipient (complete recipient address), $extension  (recipient
48       address  extension), $domain (recipient domain), $local (entire recipi‐
49       ent   address   localpart)   and   $recipient_delimiter.   The    forms
50       ${name?value}  and  ${name:value}  expand  conditionally  to value when
51       $name is (is not) defined.  Characters that may have special meaning to
52       the  shell  or  file  system  are replaced by underscores.  The list of
53       acceptable characters is specified  with  the  forward_expansion_filter
54       configuration parameter.
55
56       An  alias  or ~/.forward file may list any combination of external com‐
57       mands, destination file names, :include: directives, or mail addresses.
58       See  aliases(5)  for a precise description. Each line in a user's .for‐
59       ward file has the same syntax as the right-hand part of an alias.
60
61       When an address is found in its own alias expansion, delivery  is  made
62       to the user instead. When a user is listed in the user's own ~/.forward
63       file, delivery is made to the user's mailbox instead.  An empty ~/.for‐
64       ward file means do not forward mail.
65
66       In  order to prevent the mail system from using up unreasonable amounts
67       of memory, input records read from :include: or from  ~/.forward  files
68       are broken up into chunks of length line_length_limit.
69
70       While  expanding  aliases,  ~/.forward  files,  and  so on, the program
71       attempts to avoid duplicate deliveries. The duplicate_filter_limit con‐
72       figuration parameter limits the number of remembered recipients.
73

MAIL FORWARDING

75       For  the  sake  of reliability, forwarded mail is re-submitted as a new
76       message, so that each recipient has a separate on-file delivery  status
77       record.
78
79       In  order  to  stop  mail  forwarding loops early, the software adds an
80       optional  Delivered-To:  header  with  the  final  envelope   recipient
81       address.  If  mail  arrives for a recipient that is already listed in a
82       Delivered-To: header, the message is bounced.
83

MAILBOX DELIVERY

85       The default per-user mailbox is a file in the UNIX mail spool directory
86       (/var/mail/user or /var/spool/mail/user); the location can be specified
87       with the mail_spool_directory configuration parameter. Specify  a  name
88       ending in / for qmail-compatible maildir delivery.
89
90       Alternatively,  the  per-user  mailbox can be a file in the user's home
91       directory with a name  specified  via  the  home_mailbox  configuration
92       parameter. Specify a relative path name. Specify a name ending in / for
93       qmail-compatible maildir delivery.
94
95       Mailbox delivery can be delegated to an external command specified with
96       the  mailbox_command_maps and mailbox_command configuration parameters.
97       The command executes with the privileges of the recipient user  (excep‐
98       tions:  secondary  groups are not enabled; in case of delivery as root,
99       the command executes with the privileges of default_privs).
100
101       Mailbox delivery can be delegated  to  alternative  message  transports
102       specified  in the master.cf file.  The mailbox_transport_maps and mail‐
103       box_transport configuration  parameters  specify  an  optional  message
104       transport  that  is  to be used for all local recipients, regardless of
105       whether they  are  found  in  the  UNIX  passwd  database.   The  fall‐
106       back_transport_maps   and   fallback_transport  parameters  specify  an
107       optional message transport for recipients that are  not  found  in  the
108       aliases(5) or UNIX passwd database.
109
110       In  the  case  of  UNIX-style  mailbox  delivery,  the  local(8) daemon
111       prepends a "From sender time_stamp" envelope header  to  each  message,
112       prepends  an  X-Original-To: header with the recipient address as given
113       to Postfix, prepends an optional Delivered-To: header  with  the  final
114       envelope  recipient  address,  prepends  a Return-Path: header with the
115       envelope sender address, prepends a > character to lines beginning with
116       "From  ",  and appends an empty line.  The mailbox is locked for exclu‐
117       sive access while delivery is in progress.  In  case  of  problems,  an
118       attempt is made to truncate the mailbox to its original length.
119
120       In  the case of maildir delivery, the local daemon prepends an optional
121       Delivered-To:  header  with  the  final  envelope  recipient   address,
122       prepends  an  X-Original-To: header with the recipient address as given
123       to Postfix, and prepends a Return-Path: header with the envelope sender
124       address.
125

EXTERNAL COMMAND DELIVERY

127       The  allow_mail_to_commands  configuration parameter restricts delivery
128       to external commands. The default setting (alias, forward) forbids com‐
129       mand destinations in :include: files.
130
131       Optionally, the process working directory is changed to the path speci‐
132       fied with command_execution_directory (Postfix 2.2 and later).  Failure
133       to change directory causes mail to be deferred.
134
135       The  command_execution_directory parameter value is subject to interpo‐
136       lation of $user (recipient username), $home (recipient home directory),
137       $shell  (recipient  shell),  $recipient  (complete  recipient address),
138       $extension (recipient address extension), $domain  (recipient  domain),
139       $local  (entire  recipient address localpart) and $recipient_delimiter.
140       The forms ${name?value} and ${name:value} expand conditionally to value
141       when $name is (is not) defined.  Characters that may have special mean‐
142       ing to the shell or file system are replaced by underscores.  The  list
143       of   acceptable  characters  is  specified  with  the  execution_direc‐
144       tory_expansion_filter configuration parameter.
145
146       The command is executed directly  where  possible.  Assistance  by  the
147       shell  (/bin/sh on UNIX systems) is used only when the command contains
148       shell magic characters, or when the command invokes  a  shell  built-in
149       command.
150
151       A limited amount of command output (standard output and standard error)
152       is captured for inclusion with non-delivery status reports.  A  command
153       is   forcibly   terminated   if   it  does  not  complete  within  com‐
154       mand_time_limit seconds.  Command exit status  codes  are  expected  to
155       follow  the  conventions  defined in <sysexits.h>.  Exit status 0 means
156       normal successful completion.
157
158       Postfix version 2.3 and later support RFC  3463-style  enhanced  status
159       codes.   If  a  command terminates with a non-zero exit status, and the
160       command output begins with an enhanced status code,  this  status  code
161       takes precedence over the non-zero exit status.
162
163       A  limited  amount of message context is exported via environment vari‐
164       ables. Characters that may  have  special  meaning  to  the  shell  are
165       replaced  by  underscores.  The list of acceptable characters is speci‐
166       fied with the command_expansion_filter configuration parameter.
167
168       SHELL  The recipient user's login shell.
169
170       HOME   The recipient user's home directory.
171
172       USER   The bare recipient name.
173
174       EXTENSION
175              The optional recipient address extension.
176
177       DOMAIN The recipient address domain part.
178
179       LOGNAME
180              The bare recipient name.
181
182       LOCAL  The entire recipient address localpart (text to the left of  the
183              rightmost @ character).
184
185       ORIGINAL_RECIPIENT
186              The  entire  recipient  address, before any address rewriting or
187              aliasing (Postfix 2.5 and later).
188
189       RECIPIENT
190              The entire recipient address.
191
192       SENDER The entire sender address.
193
194       Additional remote client information is made available via the  follow‐
195       ing environment variables:
196
197       CLIENT_ADDRESS
198              Remote client network address. Available as of Postfix 2.2.
199
200       CLIENT_HELO
201              Remote  client  EHLO  command parameter. Available as of Postfix
202              2.2.
203
204       CLIENT_HOSTNAME
205              Remote client hostname. Available as of Postfix 2.2.
206
207       CLIENT_PROTOCOL
208              Remote client protocol. Available as of Postfix 2.2.
209
210       SASL_METHOD
211              SASL authentication method specified in the remote  client  AUTH
212              command. Available as of Postfix 2.2.
213
214       SASL_SENDER
215              SASL  sender  address  specified  in the remote client MAIL FROM
216              command. Available as of Postfix 2.2.
217
218       SASL_USERNAME
219              SASL username specified  in  the  remote  client  AUTH  command.
220              Available as of Postfix 2.2.
221
222       The  PATH  environment  variable  is always reset to a system-dependent
223       default path, and environment variables whose names are blessed by  the
224       export_environment configuration parameter are exported unchanged.
225
226       The current working directory is the mail queue directory.
227
228       The local(8) daemon prepends a "From sender time_stamp" envelope header
229       to each message, prepends an X-Original-To: header with  the  recipient
230       address  as given to Postfix, prepends an optional Delivered-To: header
231       with the final recipient  envelope  address,  prepends  a  Return-Path:
232       header with the sender envelope address, and appends no empty line.
233

EXTERNAL FILE DELIVERY

235       The  delivery  format  depends on the destination filename syntax.  The
236       default is to use UNIX-style mailbox format.  Specify a name ending  in
237       / for qmail-compatible maildir delivery.
238
239       The  allow_mail_to_files  configuration parameter restricts delivery to
240       external files. The default setting (alias, forward) forbids file  des‐
241       tinations in :include: files.
242
243       In  the  case  of  UNIX-style  mailbox  delivery,  the  local(8) daemon
244       prepends a "From sender time_stamp" envelope header  to  each  message,
245       prepends  an  X-Original-To: header with the recipient address as given
246       to Postfix, prepends an optional Delivered-To: header  with  the  final
247       recipient  envelope  address, prepends a > character to lines beginning
248       with "From ", and appends an empty line.  The envelope  sender  address
249       is  available  in  the  Return-Path: header.  When the destination is a
250       regular file, it is locked for exclusive access while  delivery  is  in
251       progress. In case of problems, an attempt is made to truncate a regular
252       file to its original length.
253
254       In the case of maildir delivery, the local daemon prepends an  optional
255       Delivered-To:  header  with  the  final envelope recipient address, and
256       prepends an X-Original-To: header with the recipient address  as  given
257       to  Postfix.   The  envelope sender address is available in the Return-
258       Path: header.
259

ADDRESS EXTENSION

261       The optional recipient_delimiter configuration parameter specifies  how
262       to separate address extensions from local recipient names.
263
264       For  example,  with  "recipient_delimiter  =  +",  mail for name+foo is
265       delivered to the alias name+foo or to the alias name, to  the  destina‐
266       tions listed in ~name/.forward+foo or in ~name/.forward, to the mailbox
267       owned by the user name, or it is sent back as undeliverable.
268

DELIVERY RIGHTS

270       Deliveries to external files and external commands are  made  with  the
271       rights  of the receiving user on whose behalf the delivery is made.  In
272       the absence of a user context,  the  local(8)  daemon  uses  the  owner
273       rights  of  the :include: file or alias database.  When those files are
274       owned by the superuser, delivery is made with the rights specified with
275       the default_privs configuration parameter.
276

STANDARDS

278       RFC 822 (ARPA Internet Text Messages)
279       RFC 3463 (Enhanced status codes)
280

DIAGNOSTICS

282       Problems  and transactions are logged to syslogd(8).  Corrupted message
283       files are marked so that the queue manager can move them to the corrupt
284       queue afterwards.
285
286       Depending  on the setting of the notify_classes parameter, the postmas‐
287       ter is notified of bounces and of other trouble.
288

SECURITY

290       The local(8) delivery agent needs a dual personality 1) to  access  the
291       private Postfix queue and IPC mechanisms, 2) to impersonate the recipi‐
292       ent and deliver to recipient-specified files or commands. It is  there‐
293       fore security sensitive.
294
295       The  local(8)  delivery agent disallows regular expression substitution
296       of $1 etc. in alias_maps, because that would open a security hole.
297
298       The local(8) delivery agent will silently ignore requests  to  use  the
299       proxymap(8)  server  within  alias_maps. Instead it will open the table
300       directly.  Before Postfix version 2.2, the local(8) delivery agent will
301       terminate with a fatal error.
302

BUGS

304       For  security reasons, the message delivery status of external commands
305       or of external files is never checkpointed to file. As  a  result,  the
306       program  may occasionally deliver more than once to a command or exter‐
307       nal file. Better safe than sorry.
308
309       Mutually-recursive aliases or ~/.forward files are not detected  early.
310       The  resulting  mail forwarding loop is broken by the use of the Deliv‐
311       ered-To: message header.
312

CONFIGURATION PARAMETERS

314       Changes to main.cf are picked up automatically, as  local(8)  processes
315       run for only a limited amount of time. Use the command "postfix reload"
316       to speed up a change.
317
318       The text below provides only a parameter summary. See  postconf(5)  for
319       more details including examples.
320

COMPATIBILITY CONTROLS

322       biff (yes)
323              Whether or not to use the local biff service.
324
325       expand_owner_alias (no)
326              When  delivering  to  an  alias  "aliasname" that has an "owner-
327              aliasname" companion alias, set the envelope sender  address  to
328              the expansion of the "owner-aliasname" alias.
329
330       owner_request_special (yes)
331              Give  special  treatment  to owner-listname and listname-request
332              address localparts: don't split such addresses when the  recipi‐
333              ent_delimiter is set to "-".
334
335       sun_mailtool_compatibility (no)
336              Obsolete SUN mailtool compatibility feature.
337
338       Available in Postfix version 2.3 and later:
339
340       frozen_delivered_to (yes)
341              Update  the  local(8) delivery agent's idea of the Delivered-To:
342              address (see prepend_delivered_header) only once, at  the  start
343              of  a  delivery attempt; do not update the Delivered-To: address
344              while expanding aliases or .forward files.
345
346       Available in Postfix version 2.5.3 and later:
347
348       strict_mailbox_ownership (yes)
349              Defer delivery when a mailbox file is not owned by  its  recipi‐
350              ent.
351

DELIVERY METHOD CONTROLS

353       The  precedence  of  local(8)  delivery  methods  from  high to low is:
354       aliases,  .forward  files,  mailbox_transport_maps,  mailbox_transport,
355       mailbox_command_maps,  mailbox_command, home_mailbox, mail_spool_direc‐
356       tory, fallback_transport_maps, fallback_transport, and luser_relay.
357
358       alias_maps (see 'postconf -d' output)
359              The alias databases that are used for local(8) delivery.
360
361       forward_path (see 'postconf -d' output)
362              The local(8) delivery agent search list for finding  a  .forward
363              file with user-specified delivery methods.
364
365       mailbox_transport_maps (empty)
366              Optional  lookup  tables  with  per-recipient  message  delivery
367              transports to use for local(8) mailbox delivery, whether or  not
368              the recipients are found in the UNIX passwd database.
369
370       mailbox_transport (empty)
371              Optional  message  delivery transport that the local(8) delivery
372              agent should use for mailbox delivery to all  local  recipients,
373              whether or not they are found in the UNIX passwd database.
374
375       mailbox_command_maps (empty)
376              Optional  lookup  tables with per-recipient external commands to
377              use for local(8) mailbox delivery.
378
379       mailbox_command (empty)
380              Optional external  command  that  the  local(8)  delivery  agent
381              should use for mailbox delivery.
382
383       home_mailbox (empty)
384              Optional  pathname  of  a  mailbox  file  relative to a local(8)
385              user's home directory.
386
387       mail_spool_directory (see 'postconf -d' output)
388              The directory where local(8) UNIX-style mailboxes are kept.
389
390       fallback_transport_maps (empty)
391              Optional  lookup  tables  with  per-recipient  message  delivery
392              transports for recipients that the local(8) delivery agent could
393              not find in the aliases(5) or UNIX password database.
394
395       fallback_transport (empty)
396              Optional message delivery transport that the  local(8)  delivery
397              agent  should use for names that are not found in the aliases(5)
398              or UNIX password database.
399
400       luser_relay (empty)
401              Optional catch-all destination for unknown local(8) recipients.
402
403       Available in Postfix version 2.2 and later:
404
405       command_execution_directory (empty)
406              The local(8) delivery agent working directory  for  delivery  to
407              external command.
408

MAILBOX LOCKING CONTROLS

410       deliver_lock_attempts (20)
411              The maximal number of attempts to acquire an exclusive lock on a
412              mailbox file or bounce(8) logfile.
413
414       deliver_lock_delay (1s)
415              The time between attempts to acquire  an  exclusive  lock  on  a
416              mailbox file or bounce(8) logfile.
417
418       stale_lock_time (500s)
419              The  time  after  which  a  stale  exclusive mailbox lockfile is
420              removed.
421
422       mailbox_delivery_lock (see 'postconf -d' output)
423              How to lock a  UNIX-style  local(8)  mailbox  before  attempting
424              delivery.
425

RESOURCE AND RATE CONTROLS

427       command_time_limit (1000s)
428              Time limit for delivery to external commands.
429
430       duplicate_filter_limit (1000)
431              The maximal number of addresses remembered by the address dupli‐
432              cate filter for aliases(5) or virtual(5) alias expansion, or for
433              showq(8) queue displays.
434
435       local_destination_concurrency_limit (2)
436              The  maximal  number  of  parallel deliveries via the local mail
437              delivery transport to the same recipient  (when  "local_destina‐
438              tion_recipient_limit  =  1")  or  the maximal number of parallel
439              deliveries  to  the  same  local  domain  (when  "local_destina‐
440              tion_recipient_limit > 1").
441
442       local_destination_recipient_limit (1)
443              The  maximal  number  of recipients per message delivery via the
444              local mail delivery transport.
445
446       mailbox_size_limit (51200000)
447              The maximal size of any local(8) individual mailbox  or  maildir
448              file, or zero (no limit).
449

SECURITY CONTROLS

451       allow_mail_to_commands (alias, forward)
452              Restrict local(8) mail delivery to external commands.
453
454       allow_mail_to_files (alias, forward)
455              Restrict local(8) mail delivery to external files.
456
457       command_expansion_filter (see 'postconf -d' output)
458              Restrict  the characters that the local(8) delivery agent allows
459              in $name  expansions  of  $mailbox_command  and  $command_execu‐
460              tion_directory.
461
462       default_privs (nobody)
463              The  default  rights  used  by  the  local(8) delivery agent for
464              delivery to external file or command.
465
466       forward_expansion_filter (see 'postconf -d' output)
467              Restrict the characters that the local(8) delivery agent  allows
468              in $name expansions of $forward_path.
469
470       Available in Postfix version 2.2 and later:
471
472       execution_directory_expansion_filter (see 'postconf -d' output)
473              Restrict  the characters that the local(8) delivery agent allows
474              in $name expansions of $command_execution_directory.
475
476       Available in Postfix version 2.5.3 and later:
477
478       strict_mailbox_ownership (yes)
479              Defer delivery when a mailbox file is not owned by  its  recipi‐
480              ent.
481

MISCELLANEOUS CONTROLS

483       config_directory (see 'postconf -d' output)
484              The  default  location of the Postfix main.cf and master.cf con‐
485              figuration files.
486
487       daemon_timeout (18000s)
488              How much time a Postfix daemon process  may  take  to  handle  a
489              request before it is terminated by a built-in watchdog timer.
490
491       delay_logging_resolution_limit (2)
492              The  maximal  number of digits after the decimal point when log‐
493              ging sub-second delay values.
494
495       export_environment (see 'postconf -d' output)
496              The list of environment variables that a  Postfix  process  will
497              export to non-Postfix processes.
498
499       ipc_timeout (3600s)
500              The  time  limit  for  sending  or receiving information over an
501              internal communication channel.
502
503       local_command_shell (empty)
504              Optional shell program for local(8) delivery to non-Postfix com‐
505              mand.
506
507       max_idle (100s)
508              The  maximum  amount of time that an idle Postfix daemon process
509              waits for an incoming connection before terminating voluntarily.
510
511       max_use (100)
512              The maximal number of incoming connections that a Postfix daemon
513              process will service before terminating voluntarily.
514
515       prepend_delivered_header (command, file, forward)
516              The  message delivery contexts where the Postfix local(8) deliv‐
517              ery agent prepends a  Delivered-To:   message  header  with  the
518              address that the mail was delivered to.
519
520       process_id (read-only)
521              The process ID of a Postfix command or daemon process.
522
523       process_name (read-only)
524              The process name of a Postfix command or daemon process.
525
526       propagate_unmatched_extensions (canonical, virtual)
527              What  address  lookup  tables copy an address extension from the
528              lookup key to the lookup result.
529
530       queue_directory (see 'postconf -d' output)
531              The location of the Postfix top-level queue directory.
532
533       recipient_delimiter (empty)
534              The  separator  between  user  names  and   address   extensions
535              (user+foo).
536
537       require_home_directory (no)
538              Whether  or not a local(8) recipient's home directory must exist
539              before mail delivery is attempted.
540
541       syslog_facility (mail)
542              The syslog facility of Postfix logging.
543
544       syslog_name (see 'postconf -d' output)
545              The mail system name that is prepended to the  process  name  in
546              syslog  records,  so  that  "smtpd" becomes, for example, "post‐
547              fix/smtpd".
548

FILES

550       The following are examples; details differ between systems.
551       $HOME/.forward, per-user aliasing
552       /etc/aliases, system-wide alias database
553       /var/spool/mail, system mailboxes
554

SEE ALSO

556       qmgr(8), queue manager
557       bounce(8), delivery status reports
558       newaliases(1), create/update alias database
559       postalias(1), create/update alias database
560       aliases(5), format of alias database
561       postconf(5), configuration parameters
562       master(5), generic daemon options
563       syslogd(8), system logging
564

LICENSE

566       The Secure Mailer license must be distributed with this software.
567

HISTORY

569       The Delivered-To: message header appears in the qmail system by  Daniel
570       Bernstein.
571
572       The maildir structure appears in the qmail system by Daniel Bernstein.
573

AUTHOR(S)

575       Wietse Venema
576       IBM T.J. Watson Research
577       P.O. Box 704
578       Yorktown Heights, NY 10598, USA
579
580
581
582                                                                      LOCAL(8)
Impressum