1LOCAL(8) System Manager's Manual LOCAL(8)
2
6 local - Postfix local mail delivery
7
9 local [generic Postfix daemon options]
10
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 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
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 EX‐
26 TENSION below for a few exceptions.
27
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 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 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 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}} (Postfix 3.0 and later) expand condi‐
51 tionally to value when $name is defined, and the forms ${name:value}
52 ${name:{value}} (Postfix 3.0 and later) expand conditionally to value
53 when $name is not defined. The form ${name?{value1}:{value2}} (Postfix
54 3.0 and later) expands conditionally to value1 when $name is defined,
55 or value2 otherwise. Characters that may have special meaning to the
56 shell or file system are replaced with underscores. The list of accept‐
57 able characters is specified with the forward_expansion_filter configu‐
58 ration parameter.
59 An alias or ~/.forward file may list any combination of external com‐
61 mands, destination file names, :include: directives, or mail addresses.
62 See aliases(5) for a precise description. Each line in a user's .for‐
63 ward file has the same syntax as the right-hand part of an alias.
64 When an address is found in its own alias expansion, delivery is made
66 to the user instead. When a user is listed in the user's own ~/.forward
67 file, delivery is made to the user's mailbox instead. An empty ~/.for‐
68 ward file means do not forward mail.
69 In order to prevent the mail system from using up unreasonable amounts
71 of memory, input records read from :include: or from ~/.forward files
72 are broken up into chunks of length line_length_limit.
73 While expanding aliases, ~/.forward files, and so on, the program at‐
75 tempts to avoid duplicate deliveries. The duplicate_filter_limit con‐
76 figuration parameter limits the number of remembered recipients.
77
79 For the sake of reliability, forwarded mail is re-submitted as a new
80 message, so that each recipient has a separate on-file delivery status
81 record.
82 In order to stop mail forwarding loops early, the software adds an op‐
84 tional Delivered-To: header with the final envelope recipient address.
85 If mail arrives for a recipient that is already listed in a Deliv‐
86 ered-To: header, the message is bounced.
87
89 The default per-user mailbox is a file in the UNIX mail spool directory
90 (/var/mail/user or /var/spool/mail/user); the location can be specified
91 with the mail_spool_directory configuration parameter. Specify a name
92 ending in / for qmail-compatible maildir delivery.
93 Alternatively, the per-user mailbox can be a file in the user's home
95 directory with a name specified via the home_mailbox configuration pa‐
96 rameter. Specify a relative path name. Specify a name ending in / for
97 qmail-compatible maildir delivery.
98 Mailbox delivery can be delegated to an external command specified with
100 the mailbox_command_maps and mailbox_command configuration parameters.
101 The command executes with the privileges of the recipient user (excep‐
102 tions: secondary groups are not enabled; in case of delivery as root,
103 the command executes with the privileges of default_privs).
104 Mailbox delivery can be delegated to alternative message transports
106 specified in the master.cf file. The mailbox_transport_maps and mail‐
107 box_transport configuration parameters specify an optional message
108 transport that is to be used for all local recipients, regardless of
109 whether they are found in the UNIX passwd database. The fall‐
110 back_transport_maps and fallback_transport parameters specify an op‐
111 tional message transport for recipients that are not found in the
112 aliases(5) or UNIX passwd database.
113 In the case of UNIX-style mailbox delivery, the local(8) daemon
115 prepends a "From sender time_stamp" envelope header to each message,
116 prepends an X-Original-To: header with the recipient address as given
117 to Postfix, prepends an optional Delivered-To: header with the final
118 envelope recipient address, prepends a Return-Path: header with the en‐
119 velope sender address, prepends a > character to lines beginning with
120 "From ", and appends an empty line. The mailbox is locked for exclu‐
121 sive access while delivery is in progress. In case of problems, an at‐
122 tempt is made to truncate the mailbox to its original length.
123 In the case of maildir delivery, the local daemon prepends an optional
125 Delivered-To: header with the final envelope recipient address,
126 prepends an X-Original-To: header with the recipient address as given
127 to Postfix, and prepends a Return-Path: header with the envelope sender
128 address.
129
131 The allow_mail_to_commands configuration parameter restricts delivery
132 to external commands. The default setting (alias, forward) forbids com‐
133 mand destinations in :include: files.
134 Optionally, the process working directory is changed to the path speci‐
136 fied with command_execution_directory (Postfix 2.2 and later). Failure
137 to change directory causes mail to be deferred.
138 The command_execution_directory parameter value is subject to interpo‐
140 lation of $user (recipient username), $home (recipient home directory),
141 $shell (recipient shell), $recipient (complete recipient address), $ex‐
142 tension (recipient address extension), $domain (recipient domain), $lo‐
143 cal (entire recipient address localpart) and $recipient_delimiter. The
144 forms ${name?value} and ${name?{value}} (Postfix 3.0 and later) expand
145 conditionally to value when $name is defined, and the forms
146 ${name:value} and ${name:{value}} (Postfix 3.0 and later) expand condi‐
147 tionally to value when $name is not defined. The form
148 ${name?{value1}:{value2}} (Postfix 3.0 and later) expands conditionally
149 to value1 when $name is defined, or value2 otherwise. Characters that
150 may have special meaning to the shell or file system are replaced with
151 underscores. The list of acceptable characters is specified with the
152 execution_directory_expansion_filter configuration parameter.
153 The command is executed directly where possible. Assistance by the
155 shell (/bin/sh on UNIX systems) is used only when the command contains
156 shell magic characters, or when the command invokes a shell built-in
157 command.
158 A limited amount of command output (standard output and standard error)
160 is captured for inclusion with non-delivery status reports. A command
161 is forcibly terminated if it does not complete within com‐
162 mand_time_limit seconds. Command exit status codes are expected to
163 follow the conventions defined in <sysexits.h>. Exit status 0 means
164 normal successful completion.
165 Postfix version 2.3 and later support RFC 3463-style enhanced status
167 codes. If a command terminates with a non-zero exit status, and the
168 command output begins with an enhanced status code, this status code
169 takes precedence over the non-zero exit status.
170 A limited amount of message context is exported via environment vari‐
172 ables. Characters that may have special meaning to the shell are re‐
173 placed with underscores. The list of acceptable characters is speci‐
174 fied with the command_expansion_filter configuration parameter.
175 SHELL The recipient user's login shell.
177 HOME The recipient user's home directory.
179 USER The bare recipient name.
181 EXTENSION
183 The optional recipient address extension.
184 DOMAIN The recipient address domain part.
186 LOGNAME
188 The bare recipient name.
189 LOCAL The entire recipient address localpart (text to the left of the
191 rightmost @ character).
192 ORIGINAL_RECIPIENT
194 The entire recipient address, before any address rewriting or
195 aliasing (Postfix 2.5 and later).
196 RECIPIENT
198 The entire recipient address.
199 SENDER The entire sender address.
201 Additional remote client information is made available via the follow‐
203 ing environment variables:
204 CLIENT_ADDRESS
206 Remote client network address. Available as of Postfix 2.2.
207 CLIENT_HELO
209 Remote client EHLO command parameter. Available as of Postfix
210 2.2.
211 CLIENT_HOSTNAME
213 Remote client hostname. Available as of Postfix 2.2.
214 CLIENT_PROTOCOL
216 Remote client protocol. Available as of Postfix 2.2.
217 SASL_METHOD
219 SASL authentication method specified in the remote client AUTH
220 command. Available as of Postfix 2.2.
221 SASL_SENDER
223 SASL sender address specified in the remote client MAIL FROM
224 command. Available as of Postfix 2.2.
225 SASL_USERNAME
227 SASL username specified in the remote client AUTH command.
228 Available as of Postfix 2.2.
229 The PATH environment variable is always reset to a system-dependent de‐
231 fault path, and environment variables whose names are blessed by the
232 export_environment configuration parameter are exported unchanged.
233 The current working directory is the mail queue directory.
235 The local(8) daemon prepends a "From sender time_stamp" envelope header
237 to each message, prepends an X-Original-To: header with the recipient
238 address as given to Postfix, prepends an optional Delivered-To: header
239 with the final recipient envelope address, prepends a Return-Path:
240 header with the sender envelope address, and appends no empty line.
241
243 The delivery format depends on the destination filename syntax. The
244 default is to use UNIX-style mailbox format. Specify a name ending in
245 / for qmail-compatible maildir delivery.
246 The allow_mail_to_files configuration parameter restricts delivery to
248 external files. The default setting (alias, forward) forbids file des‐
249 tinations in :include: files.
250 In the case of UNIX-style mailbox delivery, the local(8) daemon
252 prepends a "From sender time_stamp" envelope header to each message,
253 prepends an X-Original-To: header with the recipient address as given
254 to Postfix, prepends an optional Delivered-To: header with the final
255 recipient envelope address, prepends a > character to lines beginning
256 with "From ", and appends an empty line. The envelope sender address
257 is available in the Return-Path: header. When the destination is a
258 regular file, it is locked for exclusive access while delivery is in
259 progress. In case of problems, an attempt is made to truncate a regular
260 file to its original length.
261 In the case of maildir delivery, the local daemon prepends an optional
263 Delivered-To: header with the final envelope recipient address, and
264 prepends an X-Original-To: header with the recipient address as given
265 to Postfix. The envelope sender address is available in the Re‐
266 turn-Path: header.
267
269 The optional recipient_delimiter configuration parameter specifies how
270 to separate address extensions from local recipient names.
271 For example, with "recipient_delimiter = +", mail for name+foo is de‐
273 livered to the alias name+foo or to the alias name, to the destinations
274 listed in ~name/.forward+foo or in ~name/.forward, to the mailbox owned
275 by the user name, or it is sent back as undeliverable.
276
278 Deliveries to external files and external commands are made with the
279 rights of the receiving user on whose behalf the delivery is made. In
280 the absence of a user context, the local(8) daemon uses the owner
281 rights of the :include: file or alias database. When those files are
282 owned by the superuser, delivery is made with the rights specified with
283 the default_privs configuration parameter.
284
286 RFC 822 (ARPA Internet Text Messages)
287 RFC 3463 (Enhanced status codes)
288
290 Problems and transactions are logged to syslogd(8) or postlogd(8).
291 Corrupted message files are marked so that the queue manager can move
292 them to the corrupt queue afterwards.
293 Depending on the setting of the notify_classes parameter, the postmas‐
295 ter is notified of bounces and of other trouble.
296
298 The local(8) delivery agent needs a dual personality 1) to access the
299 private Postfix queue and IPC mechanisms, 2) to impersonate the recipi‐
300 ent and deliver to recipient-specified files or commands. It is there‐
301 fore security sensitive.
302 The local(8) delivery agent disallows regular expression substitution
304 of $1 etc. in alias_maps, because that would open a security hole.
305 The local(8) delivery agent will silently ignore requests to use the
307 proxymap(8) server within alias_maps. Instead it will open the table
308 directly. Before Postfix version 2.2, the local(8) delivery agent will
309 terminate with a fatal error.
310
312 For security reasons, the message delivery status of external commands
313 or of external files is never checkpointed to file. As a result, the
314 program may occasionally deliver more than once to a command or exter‐
315 nal file. Better safe than sorry.
316 Mutually-recursive aliases or ~/.forward files are not detected early.
318 The resulting mail forwarding loop is broken by the use of the Deliv‐
319 ered-To: message header.
320
322 Changes to main.cf are picked up automatically, as local(8) processes
323 run for only a limited amount of time. Use the command "postfix reload"
324 to speed up a change.
325 The text below provides only a parameter summary. See postconf(5) for
327 more details including examples.
328
330 biff (yes)
331 Whether or not to use the local biff service.
332 expand_owner_alias (no)
334 When delivering to an alias "aliasname" that has an
335 "owner-aliasname" companion alias, set the envelope sender ad‐
336 dress to the expansion of the "owner-aliasname" alias.
337 owner_request_special (yes)
339 Enable special treatment for owner-listname entries in the
340 aliases(5) file, and don't split owner-listname and listname-re‐
341 quest address localparts when the recipient_delimiter is set to
342 "-".
343 sun_mailtool_compatibility (no)
345 Obsolete SUN mailtool compatibility feature.
346 Available in Postfix version 2.3 and later:
348 frozen_delivered_to (yes)
350 Update the local(8) delivery agent's idea of the Delivered-To:
351 address (see prepend_delivered_header) only once, at the start
352 of a delivery attempt; do not update the Delivered-To: address
353 while expanding aliases or .forward files.
354 Available in Postfix version 2.5.3 and later:
356 strict_mailbox_ownership (yes)
358 Defer delivery when a mailbox file is not owned by its recipi‐
359 ent.
360 reset_owner_alias (no)
362 Reset the local(8) delivery agent's idea of the owner-alias at‐
363 tribute, when delivering mail to a child alias that does not
364 have its own owner alias.
365 Available in Postfix version 3.0 and later:
367 local_delivery_status_filter ($default_delivery_status_filter)
369 Optional filter for the local(8) delivery agent to change the
370 status code or explanatory text of successful or unsuccessful
371 deliveries.
372
374 The precedence of local(8) delivery methods from high to low is:
375 aliases, .forward files, mailbox_transport_maps, mailbox_transport,
376 mailbox_command_maps, mailbox_command, home_mailbox, mail_spool_direc‐
377 tory, fallback_transport_maps, fallback_transport, and luser_relay.
378 alias_maps (see 'postconf -d' output)
380 The alias databases that are used for local(8) delivery.
381 forward_path (see 'postconf -d' output)
383 The local(8) delivery agent search list for finding a .forward
384 file with user-specified delivery methods.
385 mailbox_transport_maps (empty)
387 Optional lookup tables with per-recipient message delivery
388 transports to use for local(8) mailbox delivery, whether or not
389 the recipients are found in the UNIX passwd database.
390 mailbox_transport (empty)
392 Optional message delivery transport that the local(8) delivery
393 agent should use for mailbox delivery to all local recipients,
394 whether or not they are found in the UNIX passwd database.
395 mailbox_command_maps (empty)
397 Optional lookup tables with per-recipient external commands to
398 use for local(8) mailbox delivery.
399 mailbox_command (empty)
401 Optional external command that the local(8) delivery agent
402 should use for mailbox delivery.
403 home_mailbox (empty)
405 Optional pathname of a mailbox file relative to a local(8)
406 user's home directory.
407 mail_spool_directory (see 'postconf -d' output)
409 The directory where local(8) UNIX-style mailboxes are kept.
410 fallback_transport_maps (empty)
412 Optional lookup tables with per-recipient message delivery
413 transports for recipients that the local(8) delivery agent could
414 not find in the aliases(5) or UNIX password database.
415 fallback_transport (empty)
417 Optional message delivery transport that the local(8) delivery
418 agent should use for names that are not found in the aliases(5)
419 or UNIX password database.
420 luser_relay (empty)
422 Optional catch-all destination for unknown local(8) recipients.
423 Available in Postfix version 2.2 and later:
425 command_execution_directory (empty)
427 The local(8) delivery agent working directory for delivery to
428 external commands.
429
431 deliver_lock_attempts (20)
432 The maximal number of attempts to acquire an exclusive lock on a
433 mailbox file or bounce(8) logfile.
434 deliver_lock_delay (1s)
436 The time between attempts to acquire an exclusive lock on a
437 mailbox file or bounce(8) logfile.
438 stale_lock_time (500s)
440 The time after which a stale exclusive mailbox lockfile is re‐
441 moved.
442 mailbox_delivery_lock (see 'postconf -d' output)
444 How to lock a UNIX-style local(8) mailbox before attempting de‐
445 livery.
446
448 command_time_limit (1000s)
449 Time limit for delivery to external commands.
450 duplicate_filter_limit (1000)
452 The maximal number of addresses remembered by the address dupli‐
453 cate filter for aliases(5) or virtual(5) alias expansion, or for
454 showq(8) queue displays.
455 mailbox_size_limit (51200000)
457 The maximal size of any local(8) individual mailbox or maildir
458 file, or zero (no limit).
459 Implemented in the qmgr(8) daemon:
461 local_destination_concurrency_limit (2)
463 The maximal number of parallel deliveries via the local mail de‐
464 livery transport to the same recipient (when "local_destina‐
465 tion_recipient_limit = 1") or the maximal number of parallel de‐
466 liveries to the same local domain (when "local_destination_re‐
467 cipient_limit > 1").
468 local_destination_recipient_limit (1)
470 The maximal number of recipients per message delivery via the
471 local mail delivery transport.
472
474 allow_mail_to_commands (alias, forward)
475 Restrict local(8) mail delivery to external commands.
476 allow_mail_to_files (alias, forward)
478 Restrict local(8) mail delivery to external files.
479 command_expansion_filter (see 'postconf -d' output)
481 Restrict the characters that the local(8) delivery agent allows
482 in $name expansions of $mailbox_command and $command_execu‐
483 tion_directory.
484 default_privs (nobody)
486 The default rights used by the local(8) delivery agent for de‐
487 livery to an external file or command.
488 forward_expansion_filter (see 'postconf -d' output)
490 Restrict the characters that the local(8) delivery agent allows
491 in $name expansions of $forward_path.
492 Available in Postfix version 2.2 and later:
494 execution_directory_expansion_filter (see 'postconf -d' output)
496 Restrict the characters that the local(8) delivery agent allows
497 in $name expansions of $command_execution_directory.
498 Available in Postfix version 2.5.3 and later:
500 strict_mailbox_ownership (yes)
502 Defer delivery when a mailbox file is not owned by its recipi‐
503 ent.
504
506 config_directory (see 'postconf -d' output)
507 The default location of the Postfix main.cf and master.cf con‐
508 figuration files.
509 daemon_timeout (18000s)
511 How much time a Postfix daemon process may take to handle a re‐
512 quest before it is terminated by a built-in watchdog timer.
513 delay_logging_resolution_limit (2)
515 The maximal number of digits after the decimal point when log‐
516 ging sub-second delay values.
517 export_environment (see 'postconf -d' output)
519 The list of environment variables that a Postfix process will
520 export to non-Postfix processes.
521 ipc_timeout (3600s)
523 The time limit for sending or receiving information over an in‐
524 ternal communication channel.
525 local_command_shell (empty)
527 Optional shell program for local(8) delivery to non-Postfix com‐
528 mands.
529 max_idle (100s)
531 The maximum amount of time that an idle Postfix daemon process
532 waits for an incoming connection before terminating voluntarily.
533 max_use (100)
535 The maximal number of incoming connections that a Postfix daemon
536 process will service before terminating voluntarily.
537 prepend_delivered_header (command, file, forward)
539 The message delivery contexts where the Postfix local(8) deliv‐
540 ery agent prepends a Delivered-To: message header with the ad‐
541 dress that the mail was delivered to.
542 process_id (read-only)
544 The process ID of a Postfix command or daemon process.
545 process_name (read-only)
547 The process name of a Postfix command or daemon process.
548 propagate_unmatched_extensions (canonical, virtual)
550 What address lookup tables copy an address extension from the
551 lookup key to the lookup result.
552 queue_directory (see 'postconf -d' output)
554 The location of the Postfix top-level queue directory.
555 recipient_delimiter (empty)
557 The set of characters that can separate an email address local‐
558 part, user name, or a .forward file name from its extension.
559 require_home_directory (no)
561 Require that a local(8) recipient's home directory exists before
562 mail delivery is attempted.
563 syslog_facility (mail)
565 The syslog facility of Postfix logging.
566 syslog_name (see 'postconf -d' output)
568 A prefix that is prepended to the process name in syslog
569 records, so that, for example, "smtpd" becomes "prefix/smtpd".
570 Available in Postfix version 3.3 and later:
572 enable_original_recipient (yes)
574 Enable support for the original recipient address after an ad‐
575 dress is rewritten to a different address (for example with
576 aliasing or with canonical mapping).
577 service_name (read-only)
579 The master.cf service name of a Postfix daemon process.
580 Available in Postfix 3.5 and later:
582 info_log_address_format (external)
584 The email address form that will be used in non-debug logging
585 (info, warning, etc.).
586
588 The following are examples; details differ between systems.
589 $HOME/.forward, per-user aliasing
590 /etc/aliases, system-wide alias database
591 /var/spool/mail, system mailboxes
592
594 qmgr(8), queue manager
595 bounce(8), delivery status reports
596 newaliases(1), create/update alias database
597 postalias(1), create/update alias database
598 aliases(5), format of alias database
599 postconf(5), configuration parameters
600 master(5), generic daemon options
601 postlogd(8), Postfix logging
602 syslogd(8), system logging
603
605 The Secure Mailer license must be distributed with this software.
606
608 The Delivered-To: message header appears in the qmail system by Daniel
609 Bernstein.
610 The maildir structure appears in the qmail system by Daniel Bernstein.
612
614 Wietse Venema
615 IBM T.J. Watson Research
616 P.O. Box 704
617 Yorktown Heights, NY 10598, USA
618 Wietse Venema
620 Google, Inc.
621 111 8th Avenue
622 New York, NY 10011, USA
623 LOCAL(8)