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  send‐
30       mail-style  alias  databases.  Users can have sendmail-style ~/.forward
31       files.  Mail for name is delivered to the alias name,  to  destinations
32       in ~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
258       Return-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) or postlogd(8).
283       Corrupted message files are marked so that the queue manager  can  move
284       them to the corrupt 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
327              "owner-aliasname"  companion  alias,  set  the  envelope  sender
328              address to the expansion of the "owner-aliasname" alias.
329
330       owner_request_special (yes)
331              Enable  special  treatment  for  owner-listname  entries  in the
332              aliases(5)  file,  and  don't  split  owner-listname  and  list‐
333              name-request  address localparts when the recipient_delimiter is
334              set to "-".
335
336       sun_mailtool_compatibility (no)
337              Obsolete SUN mailtool compatibility feature.
338
339       Available in Postfix version 2.3 and later:
340
341       frozen_delivered_to (yes)
342              Update the local(8) delivery agent's idea of  the  Delivered-To:
343              address  (see  prepend_delivered_header) only once, at the start
344              of a delivery attempt; do not update the  Delivered-To:  address
345              while expanding aliases or .forward files.
346
347       Available in Postfix version 2.5.3 and later:
348
349       strict_mailbox_ownership (yes)
350              Defer  delivery  when a mailbox file is not owned by its recipi‐
351              ent.
352
353       reset_owner_alias (no)
354              Reset the local(8) delivery  agent's  idea  of  the  owner-alias
355              attribute,  when  delivering mail to a child alias that does not
356              have its own owner alias.
357
358       Available in Postfix version 3.0 and later:
359
360       local_delivery_status_filter ($default_delivery_status_filter)
361              Optional filter for the local(8) delivery agent  to  change  the
362              status  code  or  explanatory text of successful or unsuccessful
363              deliveries.
364

DELIVERY METHOD CONTROLS

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

MAILBOX LOCKING CONTROLS

423       deliver_lock_attempts (20)
424              The maximal number of attempts to acquire an exclusive lock on a
425              mailbox file or bounce(8) logfile.
426
427       deliver_lock_delay (1s)
428              The  time  between  attempts  to  acquire an exclusive lock on a
429              mailbox file or bounce(8) logfile.
430
431       stale_lock_time (500s)
432              The time after which  a  stale  exclusive  mailbox  lockfile  is
433              removed.
434
435       mailbox_delivery_lock (see 'postconf -d' output)
436              How  to  lock  a  UNIX-style  local(8) mailbox before attempting
437              delivery.
438

RESOURCE AND RATE CONTROLS

440       command_time_limit (1000s)
441              Time limit for delivery to external commands.
442
443       duplicate_filter_limit (1000)
444              The maximal number of addresses remembered by the address dupli‐
445              cate filter for aliases(5) or virtual(5) alias expansion, or for
446              showq(8) queue displays.
447
448       mailbox_size_limit (51200000)
449              The maximal size of any local(8) individual mailbox  or  maildir
450              file, or zero (no limit).
451
452       Implemented in the qmgr(8) daemon:
453
454       local_destination_concurrency_limit (2)
455              The  maximal  number  of  parallel deliveries via the local mail
456              delivery transport to the same recipient  (when  "local_destina‐
457              tion_recipient_limit  =  1")  or  the maximal number of parallel
458              deliveries  to  the  same  local  domain  (when  "local_destina‐
459              tion_recipient_limit > 1").
460
461       local_destination_recipient_limit (1)
462              The  maximal  number  of recipients per message delivery via the
463              local mail delivery transport.
464

SECURITY CONTROLS

466       allow_mail_to_commands (alias, forward)
467              Restrict local(8) mail delivery to external commands.
468
469       allow_mail_to_files (alias, forward)
470              Restrict local(8) mail delivery to external files.
471
472       command_expansion_filter (see 'postconf -d' output)
473              Restrict the characters that the local(8) delivery agent  allows
474              in  $name  expansions  of  $mailbox_command  and $command_execu‐
475              tion_directory.
476
477       default_privs (nobody)
478              The default rights used  by  the  local(8)  delivery  agent  for
479              delivery to external file or command.
480
481       forward_expansion_filter (see 'postconf -d' output)
482              Restrict  the characters that the local(8) delivery agent allows
483              in $name expansions of $forward_path.
484
485       Available in Postfix version 2.2 and later:
486
487       execution_directory_expansion_filter (see 'postconf -d' output)
488              Restrict the characters that the local(8) delivery agent  allows
489              in $name expansions of $command_execution_directory.
490
491       Available in Postfix version 2.5.3 and later:
492
493       strict_mailbox_ownership (yes)
494              Defer  delivery  when a mailbox file is not owned by its recipi‐
495              ent.
496

MISCELLANEOUS CONTROLS

498       config_directory (see 'postconf -d' output)
499              The default location of the Postfix main.cf and  master.cf  con‐
500              figuration files.
501
502       daemon_timeout (18000s)
503              How  much  time  a  Postfix  daemon process may take to handle a
504              request before it is terminated by a built-in watchdog timer.
505
506       delay_logging_resolution_limit (2)
507              The maximal number of digits after the decimal point  when  log‐
508              ging sub-second delay values.
509
510       export_environment (see 'postconf -d' output)
511              The  list  of  environment variables that a Postfix process will
512              export to non-Postfix processes.
513
514       ipc_timeout (3600s)
515              The time limit for sending  or  receiving  information  over  an
516              internal communication channel.
517
518       local_command_shell (empty)
519              Optional shell program for local(8) delivery to non-Postfix com‐
520              mand.
521
522       max_idle (100s)
523              The maximum amount of time that an idle Postfix  daemon  process
524              waits for an incoming connection before terminating voluntarily.
525
526       max_use (100)
527              The maximal number of incoming connections that a Postfix daemon
528              process will service before terminating voluntarily.
529
530       prepend_delivered_header (command, file, forward)
531              The message delivery contexts where the Postfix local(8)  deliv‐
532              ery  agent  prepends  a  Delivered-To:   message header with the
533              address that the mail was delivered to.
534
535       process_id (read-only)
536              The process ID of a Postfix command or daemon process.
537
538       process_name (read-only)
539              The process name of a Postfix command or daemon process.
540
541       propagate_unmatched_extensions (canonical, virtual)
542              What address lookup tables copy an address  extension  from  the
543              lookup key to the lookup result.
544
545       queue_directory (see 'postconf -d' output)
546              The location of the Postfix top-level queue directory.
547
548       recipient_delimiter (empty)
549              The  set  of  characters  that can separate a user name from its
550              extension (example: user+foo), or a .forward file name from  its
551              extension (example: .forward+foo).
552
553       require_home_directory (no)
554              Require that a local(8) recipient's home directory exists before
555              mail delivery is attempted.
556
557       syslog_facility (mail)
558              The syslog facility of Postfix logging.
559
560       syslog_name (see 'postconf -d' output)
561              A prefix that  is  prepended  to  the  process  name  in  syslog
562              records, so that, for example, "smtpd" becomes "prefix/smtpd".
563
564       Available in Postfix version 3.3 and later:
565
566       enable_original_recipient (yes)
567              Enable  support  for  the  original  recipient  address after an
568              address is rewritten to a different address  (for  example  with
569              aliasing or with canonical mapping).
570
571       service_name (read-only)
572              The master.cf service name of a Postfix daemon process.
573
574       Available in Postfix 3.5 and later:
575
576       info_log_address_format (external)
577              The  email  address  form that will be used in non-debug logging
578              (info, warning, etc.).
579

FILES

581       The following are examples; details differ between systems.
582       $HOME/.forward, per-user aliasing
583       /etc/aliases, system-wide alias database
584       /var/spool/mail, system mailboxes
585

SEE ALSO

587       qmgr(8), queue manager
588       bounce(8), delivery status reports
589       newaliases(1), create/update alias database
590       postalias(1), create/update alias database
591       aliases(5), format of alias database
592       postconf(5), configuration parameters
593       master(5), generic daemon options
594       postlogd(8), Postfix logging
595       syslogd(8), system logging
596

LICENSE

598       The Secure Mailer license must be distributed with this software.
599

HISTORY

601       The Delivered-To: message header appears in the qmail system by  Daniel
602       Bernstein.
603
604       The maildir structure appears in the qmail system by Daniel Bernstein.
605

AUTHOR(S)

607       Wietse Venema
608       IBM T.J. Watson Research
609       P.O. Box 704
610       Yorktown Heights, NY 10598, USA
611
612       Wietse Venema
613       Google, Inc.
614       111 8th Avenue
615       New York, NY 10011, USA
616
617
618
619                                                                      LOCAL(8)
Impressum