Patrick Welche <prlw1@cam.ac.uk>
[netbsd-mini2440.git] / external / ibm-public / postfix / dist / html / qmgr.8.html
blobde1b0c0bfce6ae157290cdfb064af9698f615e30
1 <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
3 <html> <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
5 <title> Postfix manual - qmgr(8) </title>
6 </head> <body> <pre>
7 QMGR(8) QMGR(8)
9 <b>NAME</b>
10 qmgr - Postfix queue manager
12 <b>SYNOPSIS</b>
13 <b>qmgr</b> [generic Postfix daemon options]
15 <b>DESCRIPTION</b>
16 The <a href="qmgr.8.html"><b>qmgr</b>(8)</a> daemon awaits the arrival of incoming mail and
17 arranges for its delivery via Postfix delivery processes.
18 The actual mail routing strategy is delegated to the <a href="trivial-rewrite.8.html"><b>triv-</b></a>
19 <a href="trivial-rewrite.8.html"><b>ial-rewrite</b>(8)</a> daemon. This program expects to be run
20 from the <a href="master.8.html"><b>master</b>(8)</a> process manager.
22 Mail addressed to the local <b>double-bounce</b> address is
23 logged and discarded. This stops potential loops caused
24 by undeliverable bounce notifications.
26 <b>MAIL QUEUES</b>
27 The <a href="qmgr.8.html"><b>qmgr</b>(8)</a> daemon maintains the following queues:
29 <b>incoming</b>
30 Inbound mail from the network, or mail picked up by
31 the local <a href="pickup.8.html"><b>pickup</b>(8)</a> daemon from the <b>maildrop</b> direc-
32 tory.
34 <b>active</b> Messages that the queue manager has opened for
35 delivery. Only a limited number of messages is
36 allowed to enter the <b>active</b> queue (leaky bucket
37 strategy, for a fixed delivery rate).
39 <b>deferred</b>
40 Mail that could not be delivered upon the first
41 attempt. The queue manager implements exponential
42 backoff by doubling the time between delivery
43 attempts.
45 <b>corrupt</b>
46 Unreadable or damaged queue files are moved here
47 for inspection.
49 <b>hold</b> Messages that are kept "on hold" are kept here
50 until someone sets them free.
52 <b>DELIVERY STATUS REPORTS</b>
53 The <a href="qmgr.8.html"><b>qmgr</b>(8)</a> daemon keeps an eye on per-message delivery
54 status reports in the following directories. Each status
55 report file has the same name as the corresponding message
56 file:
58 <b>bounce</b> Per-recipient status information about why mail is
59 bounced. These files are maintained by the
60 <a href="bounce.8.html"><b>bounce</b>(8)</a> daemon.
62 <b>defer</b> Per-recipient status information about why mail is
63 delayed. These files are maintained by the
64 <a href="defer.8.html"><b>defer</b>(8)</a> daemon.
66 <b>trace</b> Per-recipient status information as requested with
67 the Postfix "<b>sendmail -v</b>" or "<b>sendmail -bv</b>" com-
68 mand. These files are maintained by the <a href="trace.8.html"><b>trace</b>(8)</a>
69 daemon.
71 The <a href="qmgr.8.html"><b>qmgr</b>(8)</a> daemon is responsible for asking the
72 <a href="bounce.8.html"><b>bounce</b>(8)</a>, <a href="defer.8.html"><b>defer</b>(8)</a> or <a href="trace.8.html"><b>trace</b>(8)</a> daemons to send delivery
73 reports.
75 <b>STRATEGIES</b>
76 The queue manager implements a variety of strategies for
77 either opening queue files (input) or for message delivery
78 (output).
80 <b>leaky bucket</b>
81 This strategy limits the number of messages in the
82 <b>active</b> queue and prevents the queue manager from
83 running out of memory under heavy load.
85 <b>fairness</b>
86 When the <b>active</b> queue has room, the queue manager
87 takes one message from the <a href="QSHAPE_README.html#incoming_queue"><b>incoming</b> queue</a> and one
88 from the <b>deferred</b> queue. This prevents a large mail
89 backlog from blocking the delivery of new mail.
91 <b>slow start</b>
92 This strategy eliminates "thundering herd" problems
93 by slowly adjusting the number of parallel deliver-
94 ies to the same destination.
96 <b>round robin</b>
97 The queue manager sorts delivery requests by desti-
98 nation. Round-robin selection prevents one desti-
99 nation from dominating deliveries to other destina-
100 tions.
102 <b>exponential backoff</b>
103 Mail that cannot be delivered upon the first
104 attempt is deferred. The time interval between
105 delivery attempts is doubled after each attempt.
107 <b>destination status cache</b>
108 The queue manager avoids unnecessary delivery
109 attempts by maintaining a short-term, in-memory
110 list of unreachable destinations.
112 <b>preemptive message scheduling</b>
113 The queue manager attempts to minimize the average
114 per-recipient delay while still preserving the cor-
115 rect per-message delays, using a sophisticated pre-
116 emptive message scheduling.
118 <b>TRIGGERS</b>
119 On an idle system, the queue manager waits for the arrival
120 of trigger events, or it waits for a timer to go off. A
121 trigger is a one-byte message. Depending on the message
122 received, the queue manager performs one of the following
123 actions (the message is followed by the symbolic constant
124 used internally by the software):
126 <b>D (QMGR_REQ_SCAN_DEFERRED)</b>
127 Start a <a href="QSHAPE_README.html#deferred_queue">deferred queue</a> scan. If a deferred queue
128 scan is already in progress, that scan will be
129 restarted as soon as it finishes.
131 <b>I (QMGR_REQ_SCAN_INCOMING)</b>
132 Start an <a href="QSHAPE_README.html#incoming_queue">incoming queue</a> scan. If an incoming queue
133 scan is already in progress, that scan will be
134 restarted as soon as it finishes.
136 <b>A (QMGR_REQ_SCAN_ALL)</b>
137 Ignore <a href="QSHAPE_README.html#deferred_queue">deferred queue</a> file time stamps. The request
138 affects the next <a href="QSHAPE_README.html#deferred_queue">deferred queue</a> scan.
140 <b>F (QMGR_REQ_FLUSH_DEAD)</b>
141 Purge all information about dead transports and
142 destinations.
144 <b>W (TRIGGER_REQ_WAKEUP)</b>
145 Wakeup call, This is used by the master server to
146 instantiate servers that should not go away for-
147 ever. The action is to start an <a href="QSHAPE_README.html#incoming_queue">incoming queue</a>
148 scan.
150 The <a href="qmgr.8.html"><b>qmgr</b>(8)</a> daemon reads an entire buffer worth of trig-
151 gers. Multiple identical trigger requests are collapsed
152 into one, and trigger requests are sorted so that <b>A</b> and <b>F</b>
153 precede <b>D</b> and <b>I</b>. Thus, in order to force a <a href="QSHAPE_README.html#deferred_queue">deferred queue</a>
154 run, one would request <b>A F D</b>; in order to notify the queue
155 manager of the arrival of new mail one would request <b>I</b>.
157 <b>STANDARDS</b>
158 <a href="http://tools.ietf.org/html/rfc3463">RFC 3463</a> (Enhanced status codes)
159 <a href="http://tools.ietf.org/html/rfc3464">RFC 3464</a> (Delivery status notifications)
161 <b>SECURITY</b>
162 The <a href="qmgr.8.html"><b>qmgr</b>(8)</a> daemon is not security sensitive. It reads
163 single-character messages from untrusted local users, and
164 thus may be susceptible to denial of service attacks. The
165 <a href="qmgr.8.html"><b>qmgr</b>(8)</a> daemon does not talk to the outside world, and it
166 can be run at fixed low privilege in a chrooted environ-
167 ment.
169 <b>DIAGNOSTICS</b>
170 Problems and transactions are logged to the syslog daemon.
171 Corrupted message files are saved to the <b>corrupt</b> queue for
172 further inspection.
174 Depending on the setting of the <b><a href="postconf.5.html#notify_classes">notify_classes</a></b> parameter,
175 the postmaster is notified of bounces and of other trou-
176 ble.
178 <b>BUGS</b>
179 A single queue manager process has to compete for disk
180 access with multiple front-end processes such as
181 <a href="cleanup.8.html"><b>cleanup</b>(8)</a>. A sudden burst of inbound mail can negatively
182 impact outbound delivery rates.
184 <b>CONFIGURATION PARAMETERS</b>
185 Changes to <a href="postconf.5.html"><b>main.cf</b></a> are not picked up automatically as
186 <a href="qmgr.8.html"><b>qmgr</b>(8)</a> is a persistent process. Use the "<b>postfix reload</b>"
187 command after a configuration change.
189 The text below provides only a parameter summary. See
190 <a href="postconf.5.html"><b>postconf</b>(5)</a> for more details including examples.
192 In the text below, <i>transport</i> is the first field in a <b>mas-</b>
193 <b>ter.cf</b> entry.
195 <b>COMPATIBILITY CONTROLS</b>
196 Available before Postfix version 2.5:
198 <b><a href="postconf.5.html#allow_min_user">allow_min_user</a> (no)</b>
199 Allow a sender or recipient address to have `-' as
200 the first character.
202 <b>ACTIVE QUEUE CONTROLS</b>
203 <b><a href="postconf.5.html#qmgr_clog_warn_time">qmgr_clog_warn_time</a> (300s)</b>
204 The minimal delay between warnings that a specific
205 destination is clogging up the Postfix active
206 queue.
208 <b><a href="postconf.5.html#qmgr_message_active_limit">qmgr_message_active_limit</a> (20000)</b>
209 The maximal number of messages in the <a href="QSHAPE_README.html#active_queue">active queue</a>.
211 <b><a href="postconf.5.html#qmgr_message_recipient_limit">qmgr_message_recipient_limit</a> (20000)</b>
212 The maximal number of recipients held in memory by
213 the Postfix queue manager, and the maximal size of
214 the size of the short-term, in-memory "dead" desti-
215 nation status cache.
217 <b><a href="postconf.5.html#qmgr_message_recipient_minimum">qmgr_message_recipient_minimum</a> (10)</b>
218 The minimal number of in-memory recipients for any
219 message.
221 <b><a href="postconf.5.html#default_recipient_limit">default_recipient_limit</a> (20000)</b>
222 The default per-transport upper limit on the number
223 of in-memory recipients.
225 <b><a href="postconf.5.html#transport_recipient_limit"><i>transport</i>_recipient_limit</a> ($<a href="postconf.5.html#default_recipient_limit">default_recipient_limit</a>)</b>
226 Idem, for delivery via the named message <i>transport</i>.
228 <b><a href="postconf.5.html#default_extra_recipient_limit">default_extra_recipient_limit</a> (1000)</b>
229 The default value for the extra per-transport limit
230 imposed on the number of in-memory recipients.
232 <b><a href="postconf.5.html#transport_extra_recipient_limit"><i>transport</i>_extra_recipient_limit</a> ($<a href="postconf.5.html#default_extra_recipient_limit">default_extra_recipi</a>-</b>
233 <b><a href="postconf.5.html#default_extra_recipient_limit">ent_limit</a>)</b>
234 Idem, for delivery via the named message <i>transport</i>.
236 Available in Postfix version 2.4 and later:
238 <b><a href="postconf.5.html#default_recipient_refill_limit">default_recipient_refill_limit</a> (100)</b>
239 The default per-transport limit on the number of
240 recipients refilled at once.
242 <b><a href="postconf.5.html#transport_recipient_refill_limit"><i>transport</i>_recipient_refill_limit</a> ($<a href="postconf.5.html#default_recipient_refill_limit">default_recipi</a>-</b>
243 <b><a href="postconf.5.html#default_recipient_refill_limit">ent_refill_limit</a>)</b>
244 Idem, for delivery via the named message <i>transport</i>.
246 <b><a href="postconf.5.html#default_recipient_refill_delay">default_recipient_refill_delay</a> (5s)</b>
247 The default per-transport maximum delay between
248 recipients refills.
250 <b><a href="postconf.5.html#transport_recipient_refill_delay"><i>transport</i>_recipient_refill_delay</a> ($<a href="postconf.5.html#default_recipient_refill_delay">default_recipi</a>-</b>
251 <b><a href="postconf.5.html#default_recipient_refill_delay">ent_refill_delay</a>)</b>
252 Idem, for delivery via the named message <i>transport</i>.
254 <b>DELIVERY CONCURRENCY CONTROLS</b>
255 <b><a href="postconf.5.html#initial_destination_concurrency">initial_destination_concurrency</a> (5)</b>
256 The initial per-destination concurrency level for
257 parallel delivery to the same destination.
259 <b><a href="postconf.5.html#default_destination_concurrency_limit">default_destination_concurrency_limit</a> (20)</b>
260 The default maximal number of parallel deliveries
261 to the same destination.
263 <b><a href="postconf.5.html#transport_destination_concurrency_limit"><i>transport</i>_destination_concurrency_limit</a> ($<a href="postconf.5.html#default_destination_concurrency_limit">default_destina</a>-</b>
264 <b><a href="postconf.5.html#default_destination_concurrency_limit">tion_concurrency_limit</a>)</b>
265 Idem, for delivery via the named message <i>transport</i>.
267 Available in Postfix version 2.5 and later:
269 <b><a href="postconf.5.html#transport_initial_destination_concurrency"><i>transport</i>_initial_destination_concurrency</a> ($<a href="postconf.5.html#initial_destination_concurrency">initial_desti</a>-</b>
270 <b><a href="postconf.5.html#initial_destination_concurrency">nation_concurrency</a>)</b>
271 Initial concurrency for delivery via the named mes-
272 sage <i>transport</i>.
274 <b><a href="postconf.5.html#default_destination_concurrency_failed_cohort_limit">default_destination_concurrency_failed_cohort_limit</a> (1)</b>
275 How many pseudo-cohorts must suffer connection or
276 handshake failure before a specific destination is
277 considered unavailable (and further delivery is
278 suspended).
280 <b><a href="postconf.5.html#transport_destination_concurrency_failed_cohort_limit"><i>transport</i>_destination_concurrency_failed_cohort_limit</a></b>
281 <b>($<a href="postconf.5.html#default_destination_concurrency_failed_cohort_limit">default_destination_concurrency_failed_cohort_limit</a>)</b>
282 Idem, for delivery via the named message <i>transport</i>.
284 <b><a href="postconf.5.html#default_destination_concurrency_negative_feedback">default_destination_concurrency_negative_feedback</a> (1)</b>
285 The per-destination amount of delivery concurrency
286 negative feedback, after a delivery completes with
287 a connection or handshake failure.
289 <b><a href="postconf.5.html#transport_destination_concurrency_negative_feedback"><i>transport</i>_destination_concurrency_negative_feedback</a></b>
290 <b>($<a href="postconf.5.html#default_destination_concurrency_negative_feedback">default_destination_concurrency_negative_feedback</a>)</b>
291 Idem, for delivery via the named message <i>transport</i>.
293 <b><a href="postconf.5.html#default_destination_concurrency_positive_feedback">default_destination_concurrency_positive_feedback</a> (1)</b>
294 The per-destination amount of delivery concurrency
295 positive feedback, after a delivery completes with-
296 out connection or handshake failure.
298 <b><a href="postconf.5.html#transport_destination_concurrency_positive_feedback"><i>transport</i>_destination_concurrency_positive_feedback</a></b>
299 <b>($<a href="postconf.5.html#default_destination_concurrency_positive_feedback">default_destination_concurrency_positive_feedback</a>)</b>
300 Idem, for delivery via the named message <i>transport</i>.
302 <b><a href="postconf.5.html#destination_concurrency_feedback_debug">destination_concurrency_feedback_debug</a> (no)</b>
303 Make the queue manager's feedback algorithm verbose
304 for performance analysis purposes.
306 <b>RECIPIENT SCHEDULING CONTROLS</b>
307 <b><a href="postconf.5.html#default_destination_recipient_limit">default_destination_recipient_limit</a> (50)</b>
308 The default maximal number of recipients per mes-
309 sage delivery.
311 <b><a href="postconf.5.html#transport_destination_recipient_limit"><i>transport</i>_destination_recipient_limit</a> ($<a href="postconf.5.html#default_destination_recipient_limit">default_destina</a>-</b>
312 <b><a href="postconf.5.html#default_destination_recipient_limit">tion_recipient_limit</a>)</b>
313 Idem, for delivery via the named message <i>transport</i>.
315 <b>MESSAGE SCHEDULING CONTROLS</b>
316 <b><a href="postconf.5.html#default_delivery_slot_cost">default_delivery_slot_cost</a> (5)</b>
317 How often the Postfix queue manager's scheduler is
318 allowed to preempt delivery of one message with
319 another.
321 <b><a href="postconf.5.html#transport_delivery_slot_cost"><i>transport</i>_delivery_slot_cost</a> ($<a href="postconf.5.html#default_delivery_slot_cost">default_delivery_slot_cost</a>)</b>
322 Idem, for delivery via the named message <i>transport</i>.
324 <b><a href="postconf.5.html#default_minimum_delivery_slots">default_minimum_delivery_slots</a> (3)</b>
325 How many recipients a message must have in order to
326 invoke the Postfix queue manager's scheduling algo-
327 rithm at all.
329 <b><a href="postconf.5.html#transport_minimum_delivery_slots"><i>transport</i>_minimum_delivery_slots</a> ($<a href="postconf.5.html#default_minimum_delivery_slots">default_minimum_deliv</a>-</b>
330 <b><a href="postconf.5.html#default_minimum_delivery_slots">ery_slots</a>)</b>
331 Idem, for delivery via the named message <i>transport</i>.
333 <b><a href="postconf.5.html#default_delivery_slot_discount">default_delivery_slot_discount</a> (50)</b>
334 The default value for transport-specific _deliv-
335 ery_slot_discount settings.
337 <b><a href="postconf.5.html#transport_delivery_slot_discount"><i>transport</i>_delivery_slot_discount</a> ($<a href="postconf.5.html#default_delivery_slot_discount">default_deliv</a>-</b>
338 <b><a href="postconf.5.html#default_delivery_slot_discount">ery_slot_discount</a>)</b>
339 Idem, for delivery via the named message <i>transport</i>.
341 <b><a href="postconf.5.html#default_delivery_slot_loan">default_delivery_slot_loan</a> (3)</b>
342 The default value for transport-specific _deliv-
343 ery_slot_loan settings.
345 <b><a href="postconf.5.html#transport_delivery_slot_loan"><i>transport</i>_delivery_slot_loan</a> ($<a href="postconf.5.html#default_delivery_slot_loan">default_delivery_slot_loan</a>)</b>
346 Idem, for delivery via the named message <i>transport</i>.
348 <b>OTHER RESOURCE AND RATE CONTROLS</b>
349 <b><a href="postconf.5.html#minimal_backoff_time">minimal_backoff_time</a> (300s)</b>
350 The minimal time between attempts to deliver a
351 deferred message; prior to Postfix 2.4 the default
352 value was 1000s.
354 <b><a href="postconf.5.html#maximal_backoff_time">maximal_backoff_time</a> (4000s)</b>
355 The maximal time between attempts to deliver a
356 deferred message.
358 <b><a href="postconf.5.html#maximal_queue_lifetime">maximal_queue_lifetime</a> (5d)</b>
359 The maximal time a message is queued before it is
360 sent back as undeliverable.
362 <b><a href="postconf.5.html#queue_run_delay">queue_run_delay</a> (300s)</b>
363 The time between <a href="QSHAPE_README.html#deferred_queue">deferred queue</a> scans by the queue
364 manager; prior to Postfix 2.4 the default value was
365 1000s.
367 <b><a href="postconf.5.html#transport_retry_time">transport_retry_time</a> (60s)</b>
368 The time between attempts by the Postfix queue man-
369 ager to contact a malfunctioning message delivery
370 transport.
372 Available in Postfix version 2.1 and later:
374 <b><a href="postconf.5.html#bounce_queue_lifetime">bounce_queue_lifetime</a> (5d)</b>
375 The maximal time a bounce message is queued before
376 it is considered undeliverable.
378 Available in Postfix version 2.5 and later:
380 <b><a href="postconf.5.html#default_destination_rate_delay">default_destination_rate_delay</a> (0s)</b>
381 The default amount of delay that is inserted
382 between individual deliveries to the same destina-
383 tion; with per-destination recipient limit &gt; 1, a
384 destination is a domain, otherwise it is a recipi-
385 ent.
387 <b><a href="postconf.5.html#transport_destination_rate_delay"><i>transport</i>_destination_rate_delay</a> $<a href="postconf.5.html#default_destination_rate_delay">default_destina</a>-</b>
388 <b><a href="postconf.5.html#default_destination_rate_delay">tion_rate_delay</a></b>
389 Idem, for delivery via the named message <i>transport</i>.
391 <b>MISCELLANEOUS CONTROLS</b>
392 <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
393 The default location of the Postfix <a href="postconf.5.html">main.cf</a> and
394 <a href="master.5.html">master.cf</a> configuration files.
396 <b><a href="postconf.5.html#defer_transports">defer_transports</a> (empty)</b>
397 The names of message delivery transports that
398 should not deliver mail unless someone issues
399 "<b>sendmail -q</b>" or equivalent.
401 <b><a href="postconf.5.html#delay_logging_resolution_limit">delay_logging_resolution_limit</a> (2)</b>
402 The maximal number of digits after the decimal
403 point when logging sub-second delay values.
405 <b><a href="postconf.5.html#helpful_warnings">helpful_warnings</a> (yes)</b>
406 Log warnings about problematic configuration set-
407 tings, and provide helpful suggestions.
409 <b><a href="postconf.5.html#ipc_timeout">ipc_timeout</a> (3600s)</b>
410 The time limit for sending or receiving information
411 over an internal communication channel.
413 <b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b>
414 The process ID of a Postfix command or daemon
415 process.
417 <b><a href="postconf.5.html#process_name">process_name</a> (read-only)</b>
418 The process name of a Postfix command or daemon
419 process.
421 <b><a href="postconf.5.html#queue_directory">queue_directory</a> (see 'postconf -d' output)</b>
422 The location of the Postfix top-level queue direc-
423 tory.
425 <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b>
426 The syslog facility of Postfix logging.
428 <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b>
429 The mail system name that is prepended to the
430 process name in syslog records, so that "smtpd"
431 becomes, for example, "postfix/smtpd".
433 <b>FILES</b>
434 /var/spool/postfix/incoming, <a href="QSHAPE_README.html#incoming_queue">incoming queue</a>
435 /var/spool/postfix/active, <a href="QSHAPE_README.html#active_queue">active queue</a>
436 /var/spool/postfix/deferred, <a href="QSHAPE_README.html#deferred_queue">deferred queue</a>
437 /var/spool/postfix/bounce, non-delivery status
438 /var/spool/postfix/defer, non-delivery status
439 /var/spool/postfix/trace, delivery status
441 <b>SEE ALSO</b>
442 <a href="trivial-rewrite.8.html">trivial-rewrite(8)</a>, address routing
443 <a href="bounce.8.html">bounce(8)</a>, delivery status reports
444 <a href="postconf.5.html">postconf(5)</a>, configuration parameters
445 <a href="master.5.html">master(5)</a>, generic daemon options
446 <a href="master.8.html">master(8)</a>, process manager
447 syslogd(8), system logging
449 <b>README FILES</b>
450 <a href="SCHEDULER_README.html">SCHEDULER_README</a>, scheduling algorithm
451 <a href="QSHAPE_README.html">QSHAPE_README</a>, Postfix queue analysis
453 <b>LICENSE</b>
454 The Secure Mailer license must be distributed with this
455 software.
457 <b>AUTHOR(S)</b>
458 Wietse Venema
459 IBM T.J. Watson Research
460 P.O. Box 704
461 Yorktown Heights, NY 10598, USA
463 Preemptive scheduler enhancements:
464 Patrik Rak
465 Modra 6
466 155 00, Prague, Czech Republic
468 QMGR(8)
469 </pre> </body> </html>