1QMGR(8) System Manager's Manual QMGR(8)
2
6 qmgr - Postfix queue manager
7
9 qmgr [generic Postfix daemon options]
10
12 The qmgr(8) daemon awaits the arrival of incoming mail and arranges for
13 its delivery via Postfix delivery processes. The actual mail routing
14 strategy is delegated to the trivial-rewrite(8) daemon. This program
15 expects to be run from the master(8) process manager.
16 Mail addressed to the local double-bounce address is logged and dis‐
18 carded. This stops potential loops caused by undeliverable bounce
19 notifications.
20
22 The qmgr(8) daemon maintains the following queues:
23 incoming
25 Inbound mail from the network, or mail picked up by the local
26 pickup(8) daemon from the maildrop directory.
27 active Messages that the queue manager has opened for delivery. Only a
29 limited number of messages is allowed to enter the active queue
30 (leaky bucket strategy, for a fixed delivery rate).
31 deferred
33 Mail that could not be delivered upon the first attempt. The
34 queue manager implements exponential backoff by doubling the
35 time between delivery attempts.
36 corrupt
38 Unreadable or damaged queue files are moved here for inspection.
39 hold Messages that are kept "on hold" are kept here until someone
41 sets them free.
42
44 The qmgr(8) daemon keeps an eye on per-message delivery status reports
45 in the following directories. Each status report file has the same name
46 as the corresponding message file:
47 bounce Per-recipient status information about why mail is bounced.
49 These files are maintained by the bounce(8) daemon.
50 defer Per-recipient status information about why mail is delayed.
52 These files are maintained by the defer(8) daemon.
53 trace Per-recipient status information as requested with the Postfix
55 "sendmail -v" or "sendmail -bv" command. These files are main‐
56 tained by the trace(8) daemon.
57 The qmgr(8) daemon is responsible for asking the bounce(8), defer(8) or
59 trace(8) daemons to send delivery reports.
60
62 The queue manager implements a variety of strategies for either opening
63 queue files (input) or for message delivery (output).
64 leaky bucket
66 This strategy limits the number of messages in the active queue
67 and prevents the queue manager from running out of memory under
68 heavy load.
69 fairness
71 When the active queue has room, the queue manager takes one mes‐
72 sage from the incoming queue and one from the deferred queue.
73 This prevents a large mail backlog from blocking the delivery of
74 new mail.
75 slow start
77 This strategy eliminates "thundering herd" problems by slowly
78 adjusting the number of parallel deliveries to the same destina‐
79 tion.
80 round robin
82 The queue manager sorts delivery requests by destination.
83 Round-robin selection prevents one destination from dominating
84 deliveries to other destinations.
85 exponential backoff
87 Mail that cannot be delivered upon the first attempt is
88 deferred. The time interval between delivery attempts is dou‐
89 bled after each attempt.
90 destination status cache
92 The queue manager avoids unnecessary delivery attempts by main‐
93 taining a short-term, in-memory list of unreachable destina‐
94 tions.
95 preemptive message scheduling
97 The queue manager attempts to minimize the average per-recipient
98 delay while still preserving the correct per-message delays,
99 using a sophisticated preemptive message scheduling.
100
102 On an idle system, the queue manager waits for the arrival of trigger
103 events, or it waits for a timer to go off. A trigger is a one-byte mes‐
104 sage. Depending on the message received, the queue manager performs
105 one of the following actions (the message is followed by the symbolic
106 constant used internally by the software):
107 D (QMGR_REQ_SCAN_DEFERRED)
109 Start a deferred queue scan. If a deferred queue scan is
110 already in progress, that scan will be restarted as soon as it
111 finishes.
112 I (QMGR_REQ_SCAN_INCOMING)
114 Start an incoming queue scan. If an incoming queue scan is
115 already in progress, that scan will be restarted as soon as it
116 finishes.
117 A (QMGR_REQ_SCAN_ALL)
119 Ignore deferred queue file time stamps. The request affects the
120 next deferred queue scan.
121 F (QMGR_REQ_FLUSH_DEAD)
123 Purge all information about dead transports and destinations.
124 W (TRIGGER_REQ_WAKEUP)
126 Wakeup call, This is used by the master server to instantiate
127 servers that should not go away forever. The action is to start
128 an incoming queue scan.
129 The qmgr(8) daemon reads an entire buffer worth of triggers. Multiple
131 identical trigger requests are collapsed into one, and trigger requests
132 are sorted so that A and F precede D and I. Thus, in order to force a
133 deferred queue run, one would request A F D; in order to notify the
134 queue manager of the arrival of new mail one would request I.
135
137 RFC 3463 (Enhanced status codes)
138 RFC 3464 (Delivery status notifications)
139
141 The qmgr(8) daemon is not security sensitive. It reads single-character
142 messages from untrusted local users, and thus may be susceptible to
143 denial of service attacks. The qmgr(8) daemon does not talk to the out‐
144 side world, and it can be run at fixed low privilege in a chrooted
145 environment.
146
148 Problems and transactions are logged to syslogd(8) or postlogd(8).
149 Corrupted message files are saved to the corrupt queue for further
150 inspection.
151 Depending on the setting of the notify_classes parameter, the postmas‐
153 ter is notified of bounces and of other trouble.
154
156 A single queue manager process has to compete for disk access with mul‐
157 tiple front-end processes such as cleanup(8). A sudden burst of inbound
158 mail can negatively impact outbound delivery rates.
159
161 Changes to main.cf are not picked up automatically as qmgr(8) is a per‐
162 sistent process. Use the "postfix reload" command after a configuration
163 change.
164 The text below provides only a parameter summary. See postconf(5) for
166 more details including examples.
167 In the text below, transport is the first field in a master.cf entry.
169
171 Available before Postfix version 2.5:
172 allow_min_user (no)
174 Allow a sender or recipient address to have `-' as the first
175 character.
176 Available with Postfix version 2.7 and later:
178 default_filter_nexthop (empty)
180 When a content_filter or FILTER request specifies no explicit
181 next-hop destination, use $default_filter_nexthop instead; when
182 that value is empty, use the domain in the recipient address.
183
185 qmgr_clog_warn_time (300s)
186 The minimal delay between warnings that a specific destination
187 is clogging up the Postfix active queue.
188 qmgr_message_active_limit (20000)
190 The maximal number of messages in the active queue.
191 qmgr_message_recipient_limit (20000)
193 The maximal number of recipients held in memory by the Postfix
194 queue manager, and the maximal size of the short-term, in-memory
195 "dead" destination status cache.
196 qmgr_message_recipient_minimum (10)
198 The minimal number of in-memory recipients for any message.
199 default_recipient_limit (20000)
201 The default per-transport upper limit on the number of in-memory
202 recipients.
203 transport_recipient_limit ($default_recipient_limit)
205 A transport-specific override for the default_recipient_limit
206 parameter value, where transport is the master.cf name of the
207 message delivery transport.
208 default_extra_recipient_limit (1000)
210 The default value for the extra per-transport limit imposed on
211 the number of in-memory recipients.
212 transport_extra_recipient_limit ($default_extra_recipient_limit)
214 A transport-specific override for the default_extra_recipi‐
215 ent_limit parameter value, where transport is the master.cf name
216 of the message delivery transport.
217 Available in Postfix version 2.4 and later:
219 default_recipient_refill_limit (100)
221 The default per-transport limit on the number of recipients
222 refilled at once.
223 transport_recipient_refill_limit ($default_recipient_refill_limit)
225 A transport-specific override for the default_recipi‐
226 ent_refill_limit parameter value, where transport is the mas‐
227 ter.cf name of the message delivery transport.
228 default_recipient_refill_delay (5s)
230 The default per-transport maximum delay between recipients
231 refills.
232 transport_recipient_refill_delay ($default_recipient_refill_delay)
234 A transport-specific override for the default_recipi‐
235 ent_refill_delay parameter value, where transport is the mas‐
236 ter.cf name of the message delivery transport.
237
239 initial_destination_concurrency (5)
240 The initial per-destination concurrency level for parallel
241 delivery to the same destination.
242 default_destination_concurrency_limit (20)
244 The default maximal number of parallel deliveries to the same
245 destination.
246 transport_destination_concurrency_limit ($default_destination_concur‐
248 rency_limit)
249 A transport-specific override for the default_destination_con‐
250 currency_limit parameter value, where transport is the master.cf
251 name of the message delivery transport.
252 Available in Postfix version 2.5 and later:
254 transport_initial_destination_concurrency ($initial_destination_concur‐
256 rency)
257 A transport-specific override for the initial_destination_con‐
258 currency parameter value, where transport is the master.cf name
259 of the message delivery transport.
260 default_destination_concurrency_failed_cohort_limit (1)
262 How many pseudo-cohorts must suffer connection or handshake
263 failure before a specific destination is considered unavailable
264 (and further delivery is suspended).
265 transport_destination_concurrency_failed_cohort_limit ($default_desti‐
267 nation_concurrency_failed_cohort_limit)
268 A transport-specific override for the default_destination_con‐
269 currency_failed_cohort_limit parameter value, where transport is
270 the master.cf name of the message delivery transport.
271 default_destination_concurrency_negative_feedback (1)
273 The per-destination amount of delivery concurrency negative
274 feedback, after a delivery completes with a connection or hand‐
275 shake failure.
276 transport_destination_concurrency_negative_feedback ($default_destina‐
278 tion_concurrency_negative_feedback)
279 A transport-specific override for the default_destination_con‐
280 currency_negative_feedback parameter value, where transport is
281 the master.cf name of the message delivery transport.
282 default_destination_concurrency_positive_feedback (1)
284 The per-destination amount of delivery concurrency positive
285 feedback, after a delivery completes without connection or hand‐
286 shake failure.
287 transport_destination_concurrency_positive_feedback ($default_destina‐
289 tion_concurrency_positive_feedback)
290 A transport-specific override for the default_destination_con‐
291 currency_positive_feedback parameter value, where transport is
292 the master.cf name of the message delivery transport.
293 destination_concurrency_feedback_debug (no)
295 Make the queue manager's feedback algorithm verbose for perfor‐
296 mance analysis purposes.
297
299 default_destination_recipient_limit (50)
300 The default maximal number of recipients per message delivery.
301 transport_destination_recipient_limit ($default_destination_recipi‐
303 ent_limit)
304 A transport-specific override for the default_destination_recip‐
305 ient_limit parameter value, where transport is the master.cf
306 name of the message delivery transport.
307
309 default_delivery_slot_cost (5)
310 How often the Postfix queue manager's scheduler is allowed to
311 preempt delivery of one message with another.
312 transport_delivery_slot_cost ($default_delivery_slot_cost)
314 A transport-specific override for the default_delivery_slot_cost
315 parameter value, where transport is the master.cf name of the
316 message delivery transport.
317 default_minimum_delivery_slots (3)
319 How many recipients a message must have in order to invoke the
320 Postfix queue manager's scheduling algorithm at all.
321 transport_minimum_delivery_slots ($default_minimum_delivery_slots)
323 A transport-specific override for the default_minimum_deliv‐
324 ery_slots parameter value, where transport is the master.cf name
325 of the message delivery transport.
326 default_delivery_slot_discount (50)
328 The default value for transport-specific _delivery_slot_discount
329 settings.
330 transport_delivery_slot_discount ($default_delivery_slot_discount)
332 A transport-specific override for the default_delivery_slot_dis‐
333 count parameter value, where transport is the master.cf name of
334 the message delivery transport.
335 default_delivery_slot_loan (3)
337 The default value for transport-specific _delivery_slot_loan
338 settings.
339 transport_delivery_slot_loan ($default_delivery_slot_loan)
341 A transport-specific override for the default_delivery_slot_loan
342 parameter value, where transport is the master.cf name of the
343 message delivery transport.
344
346 minimal_backoff_time (300s)
347 The minimal time between attempts to deliver a deferred message;
348 prior to Postfix 2.4 the default value was 1000s.
349 maximal_backoff_time (4000s)
351 The maximal time between attempts to deliver a deferred message.
352 maximal_queue_lifetime (5d)
354 Consider a message as undeliverable, when delivery fails with a
355 temporary error, and the time in the queue has reached the maxi‐
356 mal_queue_lifetime limit.
357 queue_run_delay (300s)
359 The time between deferred queue scans by the queue manager;
360 prior to Postfix 2.4 the default value was 1000s.
361 transport_retry_time (60s)
363 The time between attempts by the Postfix queue manager to con‐
364 tact a malfunctioning message delivery transport.
365 Available in Postfix version 2.1 and later:
367 bounce_queue_lifetime (5d)
369 Consider a bounce message as undeliverable, when delivery fails
370 with a temporary error, and the time in the queue has reached
371 the bounce_queue_lifetime limit.
372 Available in Postfix version 2.5 and later:
374 default_destination_rate_delay (0s)
376 The default amount of delay that is inserted between individual
377 message deliveries to the same destination and over the same
378 message delivery transport.
379 transport_destination_rate_delay ($default_destination_rate_delay)
381 A transport-specific override for the default_destina‐
382 tion_rate_delay parameter value, where transport is the mas‐
383 ter.cf name of the message delivery transport.
384 Available in Postfix version 3.1 and later:
386 default_transport_rate_delay (0s)
388 The default amount of delay that is inserted between individual
389 message deliveries over the same message delivery transport,
390 regardless of destination.
391 transport_transport_rate_delay ($default_transport_rate_delay)
393 A transport-specific override for the default_trans‐
394 port_rate_delay parameter value, where the initial transport in
395 the parameter name is the master.cf name of the message delivery
396 transport.
397
399 qmgr_daemon_timeout (1000s)
400 How much time a Postfix queue manager process may take to handle
401 a request before it is terminated by a built-in watchdog timer.
402 qmgr_ipc_timeout (60s)
404 The time limit for the queue manager to send or receive informa‐
405 tion over an internal communication channel.
406 Available in Postfix version 3.1 and later:
408 address_verify_pending_request_limit (see 'postconf -d' output)
410 A safety limit that prevents address verification requests from
411 overwhelming the Postfix queue.
412
414 config_directory (see 'postconf -d' output)
415 The default location of the Postfix main.cf and master.cf con‐
416 figuration files.
417 defer_transports (empty)
419 The names of message delivery transports that should not deliver
420 mail unless someone issues "sendmail -q" or equivalent.
421 delay_logging_resolution_limit (2)
423 The maximal number of digits after the decimal point when log‐
424 ging sub-second delay values.
425 helpful_warnings (yes)
427 Log warnings about problematic configuration settings, and pro‐
428 vide helpful suggestions.
429 process_id (read-only)
431 The process ID of a Postfix command or daemon process.
432 process_name (read-only)
434 The process name of a Postfix command or daemon process.
435 queue_directory (see 'postconf -d' output)
437 The location of the Postfix top-level queue directory.
438 syslog_facility (mail)
440 The syslog facility of Postfix logging.
441 syslog_name (see 'postconf -d' output)
443 A prefix that is prepended to the process name in syslog
444 records, so that, for example, "smtpd" becomes "prefix/smtpd".
445 Available in Postfix version 3.0 and later:
447 confirm_delay_cleared (no)
449 After sending a "your message is delayed" notification, inform
450 the sender when the delay clears up.
451 Available in Postfix 3.3 and later:
453 service_name (read-only)
455 The master.cf service name of a Postfix daemon process.
456
458 /var/spool/postfix/incoming, incoming queue
459 /var/spool/postfix/active, active queue
460 /var/spool/postfix/deferred, deferred queue
461 /var/spool/postfix/bounce, non-delivery status
462 /var/spool/postfix/defer, non-delivery status
463 /var/spool/postfix/trace, delivery status
464
466 trivial-rewrite(8), address routing
467 bounce(8), delivery status reports
468 postconf(5), configuration parameters
469 master(5), generic daemon options
470 master(8), process manager
471 postlogd(8), Postfix logging
472 syslogd(8), system logging
473
475 Use "postconf readme_directory" or "postconf html_directory" to locate
476 this information.
477 SCHEDULER_README, scheduling algorithm
478 QSHAPE_README, Postfix queue analysis
479
481 The Secure Mailer license must be distributed with this software.
482
484 Wietse Venema
485 IBM T.J. Watson Research
486 P.O. Box 704
487 Yorktown Heights, NY 10598, USA
488 Preemptive scheduler enhancements:
490 Patrik Rak
491 Modra 6
492 155 00, Prague, Czech Republic
493 Wietse Venema
495 Google, Inc.
496 111 8th Avenue
497 New York, NY 10011, USA
498 QMGR(8)