postfix-master/nqmgr.8.html

   1 <html> <head> </head> <body> <pre>
   2 NQMGR(8)                                                 NQMGR(8)
   3
   4 <b>NAME</b>
   5        nqmgr - Postfix queue manager
   6
   7 <b>SYNOPSIS</b>
   8        <b>nqmgr</b> [generic Postfix daemon options]
   9
  10 <b>DESCRIPTION</b>
  11        The  <b>nqmgr</b>  daemon awaits the arrival of incoming mail and
  12        arranges for its delivery via Postfix delivery  processes.
  13        The actual mail routing strategy is delegated to the <a href="trivial-rewrite.8.html"><b>triv-</b></a>
  14        <a href="trivial-rewrite.8.html"><b>ial-rewrite</b>(8)</a> daemon.  This program  expects  to  be  run
  15        from the <a href="master.8.html"><b>master</b>(8)</a> process manager.
  16
  17        Mail  addressed  to  the  local  <b>double-bounce</b>  address is
  18        silently discarded.  This stops potential loops caused  by
  19        undeliverable bounce notifications.
  20
  21 <b>MAIL</b> <b>QUEUES</b>
  22        The <b>nqmgr</b> daemon maintains the following queues:
  23
  24        <b>incoming</b>
  25               Inbound mail from the network, or mail picked up by
  26               the local <b>pickup</b> agent from the <b>maildrop</b> directory.
  27
  28        <b>active</b> Messages  that  the  queue  manager  has opened for
  29               delivery. Only a  limited  number  of  messages  is
  30               allowed  to  enter  the  <b>active</b> queue (leaky bucket
  31               strategy, for a fixed delivery rate).
  32
  33        <b>deferred</b>
  34               Mail that could not be  delivered  upon  the  first
  35               attempt.  The  queue manager implements exponential
  36               backoff  by  doubling  the  time  between  delivery
  37               attempts.
  38
  39        <b>corrupt</b>
  40               Unreadable  or  damaged  queue files are moved here
  41               for inspection.
  42
  43        <b>hold</b>   Messages that are kept  "on  hold"  are  kept  here
  44               until someone sets them free.
  45
  46 <b>DELIVERY</b> <b>STATUS</b> <b>REPORTS</b>
  47        The <b>nqmgr</b> daemon keeps an eye on per-message delivery sta-
  48        tus reports in  the  following  directories.  Each  status
  49        report file has the same name as the corresponding message
  50        file:
  51
  52        <b>bounce</b> Per-recipient status information about why mail  is
  53               bounced.    These   files  are  maintained  by  the
  54               <a href="bounce.8.html"><b>bounce</b>(8)</a> daemon.
  55
  56        <b>defer</b>  Per-recipient status information about why mail  is
  57               delayed.    These   files  are  maintained  by  the
  58               <a href="defer.8.html"><b>defer</b>(8)</a> daemon.
  59
  60        The <b>nqmgr</b> daemon is responsible for asking  the  <a href="bounce.8.html"><b>bounce</b>(8)</a>
  61        or <a href="defer.8.html"><b>defer</b>(8)</a> daemons to send non-delivery reports.
  62
  63 <b>STRATEGIES</b>
  64        The  queue  manager implements a variety of strategies for
  65        either opening queue files (input) or for message delivery
  66        (output).
  67
  68        <b>leaky</b> <b>bucket</b>
  69               This  strategy limits the number of messages in the
  70               <b>active</b> queue and prevents the  queue  manager  from
  71               running out of memory under heavy load.
  72
  73        <b>fairness</b>
  74               When  the  <b>active</b> queue has room, the queue manager
  75               takes one message from the <b>incoming</b> queue  and  one
  76               from the <b>deferred</b> queue. This prevents a large mail
  77               backlog from blocking the delivery of new mail.
  78
  79        <b>slow</b> <b>start</b>
  80               This strategy eliminates "thundering herd" problems
  81               by slowly adjusting the number of parallel deliver-
  82               ies to the same destination.
  83
  84        <b>round</b> <b>robin</b>
  85               The queue manager sorts delivery requests by desti-
  86               nation.   Round-robin selection prevents one desti-
  87               nation from dominating deliveries to other destina-
  88               tions.
  89
  90        <b>exponential</b> <b>backoff</b>
  91               Mail  that  cannot  be  delivered  upon  the  first
  92               attempt is deferred.   The  time  interval  between
  93               delivery attempts is doubled after each attempt.
  94
  95        <b>destination</b> <b>status</b> <b>cache</b>
  96               The   queue  manager  avoids  unnecessary  delivery
  97               attempts by  maintaining  a  short-term,  in-memory
  98               list of unreachable destinations.
  99
 100        <b>preemptive</b> <b>message</b> <b>scheduling</b>
 101               The  queue manager attempts to minimize the average
 102               per-recipient delay while still preserving the cor-
 103               rect per-message delays, using a sophisticated pre-
 104               emptive message scheduling.
 105
 106 <b>TRIGGERS</b>
 107        On an idle system, the queue manager waits for the arrival
 108        of  trigger  events,  or it waits for a timer to go off. A
 109        trigger is a one-byte message.  Depending on  the  message
 110        received,  the queue manager performs one of the following
 111        actions (the message is followed by the symbolic  constant
 112        used internally by the software):
 113
 114        <b>D</b> <b>(QMGR</b><i>_</i><b>REQ</b><i>_</i><b>SCAN</b><i>_</i><b>DEFERRED)</b>
 115               Start  a  deferred queue scan.  If a deferred queue
 116               scan is already in  progress,  that  scan  will  be
 117               restarted as soon as it finishes.
 118
 119        <b>I</b> <b>(QMGR</b><i>_</i><b>REQ</b><i>_</i><b>SCAN</b><i>_</i><b>INCOMING)</b>
 120               Start  an incoming queue scan. If an incoming queue
 121               scan is already in  progress,  that  scan  will  be
 122               restarted as soon as it finishes.
 123
 124        <b>A</b> <b>(QMGR</b><i>_</i><b>REQ</b><i>_</i><b>SCAN</b><i>_</i><b>ALL)</b>
 125               Ignore deferred queue file time stamps. The request
 126               affects the next deferred queue scan.
 127
 128        <b>F</b> <b>(QMGR</b><i>_</i><b>REQ</b><i>_</i><b>FLUSH</b><i>_</i><b>DEAD)</b>
 129               Purge all information  about  dead  transports  and
 130               destinations.
 131
 132        <b>W</b> <b>(TRIGGER</b><i>_</i><b>REQ</b><i>_</i><b>WAKEUP)</b>
 133               Wakeup  call,  This is used by the master server to
 134               instantiate servers that should not  go  away  for-
 135               ever.  The  action  is  to  start an incoming queue
 136               scan.
 137
 138        The <b>nqmgr</b> daemon reads an entire buffer worth of triggers.
 139        Multiple  identical  trigger  requests  are collapsed into
 140        one, and trigger requests are sorted so that <b>A</b> and <b>F</b>  pre-
 141        cede  <b>D</b>  and  <b>I</b>.  Thus, in order to force a deferred queue
 142        run, one would request <b>A</b> <b>F</b> <b>D</b>; in order to notify the queue
 143        manager of the arrival of new mail one would request <b>I</b>.
 144
 145 <b>STANDARDS</b>
 146        None.  The <b>nqmgr</b> daemon does not interact with the outside
 147        world.
 148
 149 <b>SECURITY</b>
 150        The <b>nqmgr</b> daemon is not security sensitive. It reads  sin-
 151        gle-character  messages  from  untrusted  local users, and
 152        thus may be susceptible to denial of service attacks.  The
 153        <b>nqmgr</b>  daemon  does  not talk to the outside world, and it
 154        can be run at fixed low privilege in a  chrooted  environ-
 155        ment.
 156
 157 <b>DIAGNOSTICS</b>
 158        Problems and transactions are logged to the syslog daemon.
 159        Corrupted message files are saved to the <b>corrupt</b> queue for
 160        further inspection.
 161
 162        Depending  on the setting of the <b>notify</b><i>_</i><b>classes</b> parameter,
 163        the postmaster is notified of bounces and of  other  trou-
 164        ble.
 165
 166 <b>BUGS</b>
 167        A  single  queue  manager  process has to compete for disk
 168        access with multiple front-end processes such as <b>smtpd</b>.  A
 169        sudden  burst  of  inbound mail can negatively impact out-
 170        bound delivery rates.
 171
 172 <b>CONFIGURATION</b> <b>PARAMETERS</b>
 173        The following <b>main.cf</b> parameters are  especially  relevant
 174        to  this  program. See the Postfix <b>main.cf</b> file for syntax
 175        details and for default values.  Use  the  <b>postfix</b>  <b>reload</b>
 176        command after a configuration change.
 177
 178 <b>Miscellaneous</b>
 179        <b>allow</b><i>_</i><b>min</b><i>_</i><b>user</b>
 180               Do  not  bounce recipient addresses that begin with
 181               '-'.
 182
 183        <b>queue</b><i>_</i><b>directory</b>
 184               Top-level directory of the Postfix queue.
 185
 186 <b>Active</b> <b>queue</b> <b>controls</b>
 187        In the text below, <i>transport</i> is the first field in a  <b>mas-</b>
 188        <b>ter.cf</b> entry.
 189
 190        <b>qmgr</b><i>_</i><b>clog</b><i>_</i><b>warn</b><i>_</i><b>time</b>
 191               Minimal delay between warnings that a specific des-
 192               tination is clogging up the active queue. Specify 0
 193               to disable.
 194
 195        <b>qmgr</b><i>_</i><b>message</b><i>_</i><b>active</b><i>_</i><b>limit</b>
 196               Limit the number of messages in the active queue.
 197
 198        <b>qmgr</b><i>_</i><b>message</b><i>_</i><b>recipient</b><i>_</i><b>limit</b>
 199               Limit the number of in-memory recipients.
 200
 201               This  parameter  also limits the size of the short-
 202               term, in-memory destination cache.
 203
 204        <b>qmgr</b><i>_</i><b>message</b><i>_</i><b>recipient</b><i>_</i><b>minimum</b>
 205               Per message minimum of in-memory recipients.
 206
 207        <b>default</b><i>_</i><b>recipient</b><i>_</i><b>limit</b>
 208               Default limit on the number of in-memory recipients
 209               per transport.
 210
 211        <i>transport_</i><b>recipient</b><i>_</i><b>limit</b>
 212               Limit  on  the  number of in-memory recipients, for
 213               the named message <i>transport</i>.
 214
 215        <b>default</b><i>_</i><b>extra</b><i>_</i><b>recipient</b><i>_</i><b>limit</b>
 216               Default limit on the total number of per  transport
 217               in-memory  recipients  that the preempting messages
 218               can have.
 219
 220        <i>transport_</i><b>extra</b><i>_</i><b>recipient</b><i>_</i><b>limit</b>
 221               Limit on the number of in-memory  recipients  which
 222               all  preempting messages delivered by the transport
 223               <i>transport</i> can have.
 224
 225 <b>Timing</b> <b>controls</b>
 226        <b>minimal</b><i>_</i><b>backoff</b><i>_</i><b>time</b>
 227               Minimal time in seconds between  delivery  attempts
 228               of a deferred message.
 229
 230               This  parameter also limits the time an unreachable
 231               destination is kept in  the  short-term,  in-memory
 232               destination status cache.
 233
 234        <b>maximal</b><i>_</i><b>backoff</b><i>_</i><b>time</b>
 235               Maximal  time  in seconds between delivery attempts
 236               of a deferred message.
 237
 238        <b>maximal</b><i>_</i><b>queue</b><i>_</i><b>lifetime</b>
 239               Maximal time in days a message is queued before  it
 240               is sent back as undeliverable.
 241
 242        <b>queue</b><i>_</i><b>run</b><i>_</i><b>delay</b>
 243               Time in seconds between deferred queue scans. Queue
 244               scans do not overlap.
 245
 246        <b>transport</b><i>_</i><b>retry</b><i>_</i><b>time</b>
 247               Time in seconds between attempts to contact a  bro-
 248               ken delivery transport.
 249
 250 <b>Concurrency</b> <b>controls</b>
 251        <b>initial</b><i>_</i><b>destination</b><i>_</i><b>concurrency</b>
 252               Initial  per-destination concurrency level for par-
 253               allel delivery to the same destination.
 254
 255        <b>default</b><i>_</i><b>destination</b><i>_</i><b>concurrency</b><i>_</i><b>limit</b>
 256               Default limit on the number of parallel  deliveries
 257               to the same destination.
 258
 259        <i>transport_</i><b>destination</b><i>_</i><b>concurrency</b><i>_</i><b>limit</b>
 260               Limit  on  the number of parallel deliveries to the
 261               same destination, for delivery via the  named  mes-
 262               sage <i>transport</i>.
 263
 264 <b>Recipient</b> <b>controls</b>
 265        <b>default</b><i>_</i><b>destination</b><i>_</i><b>recipient</b><i>_</i><b>limit</b>
 266               Default  limit on the number of recipients per mes-
 267               sage transfer.
 268
 269        <i>transport_</i><b>destination</b><i>_</i><b>recipient</b><i>_</i><b>limit</b>
 270               Limit on  the  number  of  recipients  per  message
 271               transfer, for the named message <i>transport</i>.
 272
 273 <b>Message</b> <b>scheduling</b>
 274        <i>transport_</i><b>delivery</b><i>_</i><b>slot</b><i>_</i><b>cost</b> (valid range: 0,2,3...)
 275               This  parameter basically controls how often a mes-
 276               sage delivered by <i>transport</i>  can  be  preempted  by
 277               another message.  An internal per-message/transport
 278               counter is  incremented  by  one  for  each  <i>trans-</i>
 279               <i>port_</i><b>delivery</b><i>_</i><b>slot</b><i>_</i><b>cost</b>   deliveries   handled   by
 280               <i>transport</i>. This counter represents  the  number  of
 281               "available  delivery  slots"  for use by other mes-
 282               sages.  Current message can be preempted by another
 283               message  when  that  other message can be delivered
 284               using less <i>transport</i> agents than the value  of  the
 285               "available delivery slots" counter.
 286
 287               Value  equal  to  0 disables the message preemption
 288               for <i>transport</i>.
 289
 290        <i>transport_</i><b>minimum</b><i>_</i><b>delivery</b><i>_</i><b>slots</b>
 291               Message preemption is not attempted at all whenever
 292               a  message  that  can't  ever  accumulate  at least
 293               <i>transport_</i><b>minimum</b><i>_</i><b>delivery</b><i>_</i><b>slots</b> available delivery
 294               slots is being delivered by <i>transport</i>.
 295
 296        <i>transport_</i><b>delivery</b><i>_</i><b>slot</b><i>_</i><b>discount</b> (valid range: 0..100)
 297
 298        <i>transport_</i><b>delivery</b><i>_</i><b>slot</b><i>_</i><b>loan</b>
 299               These parameters speed up the moment when a message
 300               preemption can happen.  Instead  of  waiting  until
 301               the  full  amount  of  delivery  slots  required is
 302               available, the preemption can  happen  when  <i>trans-</i>
 303               <i>port_</i><b>delivery</b><i>_</i><b>slot</b><i>_</i><b>discount</b> percent of the required
 304               amount  plus   <i>transport_</i><b>delivery</b><i>_</i><b>slot</b><i>_</i><b>loan</b>   still
 305               remains  to  be  accumulated.  Note  that  the full
 306               amount will still have  to  be  accumulated  before
 307               another preemption can take place later.
 308
 309        <b>default</b><i>_</i><b>delivery</b><i>_</i><b>slot</b><i>_</i><b>cost</b>
 310
 311        <b>default</b><i>_</i><b>minimum</b><i>_</i><b>delivery</b><i>_</i><b>slots</b>
 312
 313        <b>default</b><i>_</i><b>delivery</b><i>_</i><b>slot</b><i>_</i><b>discount</b>
 314
 315        <b>default</b><i>_</i><b>delivery</b><i>_</i><b>slot</b><i>_</i><b>loan</b>
 316               Default  values  for the transport specific parame-
 317               ters described above.
 318
 319 <b>SEE</b> <b>ALSO</b>
 320        <a href="master.8.html">master(8)</a>, process manager
 321        syslogd(8) system logging
 322        <a href="trivial-rewrite.8.html">trivial-rewrite(8)</a>, address routing
 323
 324 <b>LICENSE</b>
 325        The Secure Mailer license must be  distributed  with  this
 326        software.
 327
 328 <b>AUTHOR(S)</b>
 329        Wietse Venema
 330        IBM T.J. Watson Research
 331        P.O. Box 704
 332        Yorktown Heights, NY 10598, USA
 333
 334        Scheduler enhancements:
 335        Patrik Rak
 336        Modra 6
 337        155 00, Prague, Czech Republic
 338
 339                                                          NQMGR(8)
 340 </pre> </body> </html>