1LOCAL(8) System Manager's Manual LOCAL(8)
2
3
4
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
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
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
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
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
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
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
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
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
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
278 RFC 822 (ARPA Internet Text Messages)
279 RFC 3463 (Enhanced status codes)
280
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
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
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
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
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
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
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
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
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
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
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
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
598 The Secure Mailer license must be distributed with this software.
599
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
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)