qmail send.8

NAME

qmail-send - deliver mail messages from the queue with rate control

SYNOPSIS

qmail-send [ -s] | -d

DESCRIPTION

qmail-send handles messages placed into the outgoing queue by qmail-queue. qmail-send by default looks at /var/indimail/queue for messages. This path can be changed by defining the QUEUEDIR environment variable. If you are using qscheduler(8) to invoke qmail-send, then qscheduler will use QUEUE_COUNT, QUEUE_START to invoke multiple qmail-send processes, with each having its own queue defined by the QUEUEDIR environment variable. QUEUEDIR will typically be /var/indimail/queue/queue1, /var/indimail/queue/queue2 and so on. This manual will refer queue as the value of QUEUEDIR. For each delivery, qmail-send puts a delivery number in the logs. In a multi-queue environment, qmail-send will append the queue identifier to the delivery number. It uses the value of QIDENT environment variable set by qscheduler. This allows the matchup(1) program to process the logs in a multi-queue environment. The matchup(1) program is used by qmailanalog scripts.

qmail-send can load startup plugins from /usr/lib/indimail/plugins directory. This directory can be changed by defining the PLUGINDIR environment variable. By default, qmail-send will attempt to load the plugin qmail-send.so. This can be changed by defining START_PLUGIN environment variable. You can define multiple plugins separated by the space charater in the START_PLUGIN variable. qmail-send will use dlopen(3) function to load all the plugins and by default try to execute the symbol startup. The symbol to be loaded can be changed by defining the START_PLUGIN_SYMB environment variable. qmail-send will terminate if any of the loaded functions return non-zero status.

qmail-send sends a single byte 'S' on desciptor 7 to qmail-todo to indicate that it has started. qmail-send reads instructions from qmail-todo on descriptor 8. It gets the filename in todo directory, the message id and whether the message is local or remote. It then uses qmail-lspawn to deliver messages to local recipients and qmail-rspawn to deliver messages to remote recipients. If a message is temporarily undeliverable to one or more addresses, qmail-send leaves it in the queue and tries the addresses again later.

qmail-send prints a readable record of its activities to descriptor 0. It writes commands to qmail-lspawn, qmail-rspawn, and qmail-clean on descriptors 1, 3, and 5, and reads responses from descriptors 2, 4, and 6. qmail-send is responsible for avoiding deadlock.

qmail-send uses qmail-queue to queue bounces and aliases/forwards. This can be changed by using QMAILQUEUE environment variable. If a different queue program is desired for bounces, it can be set by using BOUNCEQUEUE environment variable.

When injecting a bounce for a previously forwarded email, whose sender was rewritten using SRS**, qmail-send** rewrites the recipient to the original sender using Sender Rewriting Scheme, if SRS** has been** configured. see qmail-srs(5) for information on how to do this.

qmail-send adds the X-Bounced-Address header when creating a bounce. It assigns the address that caused the bounce to this header. This is useful for programs that generate DKIM signature to use the domain in the X-Bounced-Address for the d= DKIM-Signature tag.

If qmail-send receives a TERM signal, it will exit cleanly, after waiting (possibly more than a minute) for current delivery attempts to finish.

If qmail-send receives an ALRM signal, it will reschedule every message in the queue for immediate delivery.

If the environment variable USE_FSYNC is set, then qmail-send writes all data to disk ("flushes") all modified in-core data of (i.e., modified buffer cache pages for) the new message to the disk device (or other permanent storage device) so that all changed information can be retrieved even if the system crashes or is rebooted. This includes writing through or flushing a disk cache if present. The call blocks until the device reports that the transfer has completed. This is done for the info and mess files. This can also be set by using conf-fsync control file.

If the environment variable USE_FDATASYNC is enabled, qmail-send uses fdatasync(2) instead of fsync(2). This can also be set by using conf-fdatasync control file.

If the environment variable USE_SYNCDIR is enabled, qmail-send forces BSD style directory syncing. This can also be set by using conf-syncdir control file.

if the value of the environment variables USE_FSYNC, USE_FDATASYNC, USE_SYNCDIR is zero, the corresponding variables is unset. This allows setting of these variables for qmail-local(8).

qmail-send can be configured to use a queue with a different split subdirectory value than compile time value of 151. This can be done by setting the CONFSPLIT envrionment variable. Additionally, it can process a queue created with todo, intd with subdirectory split instead of without any split. This can be done by setting the BIGTODO environment variable.

OPTIONS

-s
This implies qmail-send will use static queue mode. In this mode qmail-send doesn't create shared memory segments for maintaining the local/remote concurrency values See multi-queue(7) for a complete overview.

-d
This implements dynamic queue mode where qmail-send is responsible for creating shared a shared memory segment for writing the current local and remote concurrency value.

CONTROL FILES

WARNING: qmail-send reads its control files only when it starts. If you change the control files, you must stop and restart qmail-send. Exception: If qmail-send receives a HUP signal, it will reread concurrencylocal, concurrencyl.queue, concurrencyremote, concurrencyr.queue, locals, virtualdomains, holdlocal, holdremote, envnoathost, conf-syncdir, and conf-fsync.

During startup, qmail-send uses the environment variable LOGLOCK and locks the file CONTROLDIR/defaultdelivery before writing a line to the log file (or stdout). If multiple qmail-send processes are running, all writing to one multilog, lines may get jumbled up in extreme situations. This can be avoided by setting LOGLOCK environment variable. If qmail-send receives a INT signal, it will toggle log lock synchronization. If log locking is set, it will get turned off and vice versa.

qmail-send by default looks at /etc/indimail/control for all control files. This path can be changed by defining the CONTROLDIR environment variable.

bouncefrom
Bounce username. Default: MAILER-DAEMON.

bouncehost
Bounce host. Default: me, if that is supplied; otherwise the literal name bouncehost, which is probably not what you want. If a message is permanently undeliverable, qmail-send sends a single-bounce notice back to the message's envelope sender. The notice is From: bouncefrom@bouncehost, although its envelope sender is empty.

bouncemaxbyte
Limit the size of bounces. Default: 50000 bytes.

bouncesubject
Configures the bounce message subject

bouncemessage
Text for bounce message. Remember that this may break QSBMF

doublebouncehost
Double-bounce host. Default: me, if that is supplied; otherwise the literal name doublebouncehost, which is probably not what you want.

doublebounceto
User to receive double-bounces. Default: postmaster. If a single-bounce notice is permanently undeliverable, qmail-send sends a double-bounce notice to doublebounceto*@*doublebouncehost. (If that bounces, qmail-send gives up.) As a special case, if the first line of doublebounceto contains a '@' or is blank (contains a single linefeed), qmail-send will not queue the double-bounce at all.

doublebouncesubject
Configures the double bounce message subject

doublebouncemessage
Text for double bounce message. Remember that this may break QSBMF

concurrencylocal
Maximum number of simultaneous local delivery attempts. Default: 10. If 0, local deliveries will be put on hold. concurrencylocal is limited at compile time to 500.

concurrencyl.queue
Maximum number of simultaneous local delivery attempts for the queue queue. A queue can be defined by setting QUEUEDIR environment variable, referring to the path of the queue. Here queue refers to the basename of the queue path. Default: 10. If 0, local deliveries will be put on hold. concurrencyl.queue is limited at compile time to 500.

concurrencyremote
Maximum number of simultaneous remote delivery attempts. Default: 20. If 0, remote deliveries will be put on hold. concurrencyremote is limited at compile time to 500.

concurrencyr.queue
Maximum number of simultaneous remote delivery attempts for the queue queue. A queue can be defined by setting QUEUEDIR environment variable, referring to the path of the queue. Here queue refers to the basename of the queue path. Default: 20. If 0, remote deliveries will be put on hold. concurrencyr.queue is limited at compile time to 500.

envnoathost
Presumed domain name for addresses without @ signs. Default: me, if that is supplied; otherwise the literal name envnoathost, which is probably not what you want. If qmail-send sees an envelope recipient address without an @ sign, it appends @envnoathost.

locals
List of domain names that the current host receives mail for, one per line. Default: me, if that is supplied; otherwise qmail-send refuses to run. An address user@domain is considered local if domain is listed in locals.

percenthack
List of domain names where the percent hack is applied. If domain is listed in percenthack, any address of the form user%fqdn@domain is rewritten as user@fqdn. user may contain %, so the percent hack may be applied repeatedly. qmail-send handles percenthack before locals.

queuelifetime
Number of seconds a message can stay in the queue. Default: 604800 (one week). After this time expires, qmail-send will try the message once more, but it will treat any temporary delivery failures as permanent failures.

bouncelifetime
Number of seconds a bounce message can stay in the queue. Default: 604800 (one week). After this time expires, qmail-send will try the message once more, but it will treat any temporary delivery failures as permanent failures.

bounce.envrules
Specific environment variables can be set for bounce recipients. The format of this file is of the form pat:envar1=val,envar2=val,...] where pat is a regular expression which matches a bounce recipient. envar1, envar2 are list of environment variables to be set. If var is omitted, the environment variable is unset.

The name of the control file can be overriden by the environment variable BOUNCERULES

Example: answerme@save*:CONTROLDIR=control2,QMAILQUEUE=

sets CONTROLDIR to control2 for the sender answerme@saveme.com and unsets QMAILQUEUE environment variable. If there are multiple lines for a pattern, all lines are applied. However if an environment variable is being set in multiple lines, the last rule takes precedence. The environment variable QREGEX can be set to use regular expressions for matching pat instead of the internal wildmat function.

Example: answerme@save*:DATABYTES=2000000,MAXRECIPIENT=2,QMAILQUEUE= answerme@save*:DATABYTES=4000000

DATABYTES gets set to 4 MB in for any email matching answerme@save*

virtualdomains
List of virtual users or domains, one per line. A virtual user has the form user*@domain:prepend, without any extra spaces. When qmail-send sees the recipient address user@domain, it converts it to prepend-user@*domain and treats it as local.

A virtual domain has the form domain*:*prepend. It applies to any recipient address at domain. For example, if

     nowhere.mil:joe-foo

is in virtualdomains, and a message arrives for info@nowhere.mil, qmail-send will rewrite the recipient address as joe-foo-info@nowhere.mil and deliver the message locally.

virtualdomains may contain wildcards:

     .fax:uucp-fax
     :alias-catchall
     .nowhere.mil:joe-foo-host

virtualdomains may also contain exceptions: an empty prepend means that domain is not a virtual domain.

qmail-send handles virtualdomains after locals: if a domain is listed in locals, virtualdomains does not apply.

holdlocal
A boolean parameter indicating whether mail for local hosts should be queued without delivery. Zero indicates delivery as normal; any other value causes local mail to be held. Default: zero

holdremote
A boolean parameter indicating whether mail for remote hosts should be queued without delivery. Zero indicates delivery as normal; any other value causes remote mail to be held. This is provided to permit use of qmail in a dial-up environment when the remote delivery path may not always be available, as an alternative to the use of serialmail. Default: zero

conf-fsync
A boolean parameter to turn on fsync of file descriptors when writing to a file during delivery

conf-syncdir
A boolean parameter to turn on BSD style sync semantics for flushing directories.

Delivery Rate Control

qmail-send turns on delivery rate control if the environment variable RATELIMIT_DIR is set and a rate control definition file exists in the directory RATELIMIT_DIR with the same name as the recipient domain. For details check drate(1). This directory should be writeable for the user qmails. Delivery rate control can be turned off by setting the environment variable RATELIMIT_DIR to an empty string.

The following control files described below apply to delivery rate control. Remember that a local rate definition file for a domain takes precedence over any matching line in ratecontrol file. Any matching definition for a domain in ratecontrol file takes precedence over definition in .global file.

RATELIMIT_DIR/ratecontrol
You can set rate control expression for recipient domains. The format of this file is of the form pat:mathematical_expression where pat is a regular expression which matches the domain part the recipient. When a match occurs, qmail-send will automatically create a local rate definition file and the rate control will apply to the individual domain that got matched.

RATELIMIT_DIR/.global
For recpient domains that do not have a local rate control definition and do not match any line in RATELIMIT_DIR/ratecontrol, this file serves as the rate control definition for all such domains. This definition does not apply individually to the recipient domains but to sum total of all such remaining domains that do not have a local definition.

External BOUNCE Processor

qmail-send will execute an external program defined by the environment variable BOUNCEPROCESSOR (if set) when delivery to a recipient fails. The external program will be called with the following arguments

original_message_file bounce_file bounce_report bounce_sender original_recipient bounce_recipient

The external program runs with uid of qmails. If the bounce script exits 1, the bounce is discarded. You should be very careful in writing your own bounce processor. If the bounce processor program returns non-zero exit status (other than an exit value of 1), qmail-send will continue to retry the script. Also just like bounces, bounce processor is not crash-proof. In case your bounce processor genuinely returns non-zero exit status and you shut qmail-send, you will not be able to again get back to retry the bounce that the processor was handling.

Retry Schedule

Each message has its own retry schedule. The longer a message remains undeliverable, the less frequently qmail tries to send it. The retry schedule is not configurable. The following table shows the retry schedule for a message that's undeliverable to a recipient until it bounces. Local messages a similar, but more frequent, schedule than remote messages.

Local Retry Schedule is governed by 100 * (x * x), where x is the try number

qmail-send delivery retry times, for chanskip=10 (local)
Try ======= after ======= == delay until next =
seconds dd hh mm ss seconds dd hh mm ss
...................... ....................... ......................
#00 0 [00 00:00:00] 100 [00 00:01:40]
#01 100 [00 00:01:40] 300 [00 00:05:00]
#02 400 [00 00:06:40] 500 [00 00:08:20]
#03 900 [00 00:15:00] 700 [00 00:11:40]
#04 1600 [00 00:26:40] 900 [00 00:15:00]
#05 2500 [00 00:41:40] 1100 [00 00:18:20]
#06 3600 [00 01:00:00] 1300 [00 00:21:40]
#07 4900 [00 01:21:40] 1500 [00 00:25:00]
#08 6400 [00 01:46:40] 1700 [00 00:28:20]
#09 8100 [00 02:15:00] 1900 [00 00:31:40]
#10 10000 [00 02:46:40] 2100 [00 00:35:00]
#11 12100 [00 03:21:40] 2300 [00 00:38:20]
#12 14400 [00 04:00:00] 2500 [00 00:41:40]
#13 16900 [00 04:41:40] 2700 [00 00:45:00]
#14 19600 [00 05:26:40] 2900 [00 00:48:20]
#15 22500 [00 06:15:00] 3100 [00 00:51:40]
#16 25600 [00 07:06:40] 3300 [00 00:55:00]
#17 28900 [00 08:01:40] 3500 [00 00:58:20]
#18 32400 [00 09:00:00] 3700 [00 01:01:40]
#19 36100 [00 10:01:40] 3900 [00 01:05:00]
#20 40000 [00 11:06:40] 4100 [00 01:08:20]
#21 44100 [00 12:15:00] 4300 [00 01:11:40]
#22 48400 [00 13:26:40] 4500 [00 01:15:00]
#23 52900 [00 14:41:40] 4700 [00 01:18:20]
#24 57600 [00 16:00:00] 4900 [00 01:21:40]
#25 62500 [00 17:21:40] 5100 [00 01:25:00]
#26 67600 [00 18:46:40] 5300 [00 01:28:20]
#27 72900 [00 20:15:00] 5500 [00 01:31:40]
#28 78400 [00 21:46:40] 5700 [00 01:35:00]
#29 84100 [00 23:21:40] 5900 [00 01:38:20]
#30 90000 [01 01:00:00] 6100 [00 01:41:40]
#31 96100 [01 02:41:40] 6300 [00 01:45:00]
#32 102400 [01 04:26:40] 6500 [00 01:48:20]
#33 108900 [01 06:15:00] 6700 [00 01:51:40]
#34 115600 [01 08:06:40] 6900 [00 01:55:00]
#35 122500 [01 10:01:40] 7100 [00 01:58:20]
#36 129600 [01 12:00:00] 7300 [00 02:01:40]
#37 136900 [01 14:01:40] 7500 [00 02:05:00]
#38 144400 [01 16:06:40] 7700 [00 02:08:20]
#39 152100 [01 18:15:00] 7900 [00 02:11:40]
#40 160000 [01 20:26:40] 8100 [00 02:15:00]
#41 168100 [01 22:41:40] 8300 [00 02:18:20]
#42 176400 [02 01:00:00] 8500 [00 02:21:40]
#43 184900 [02 03:21:40] 8700 [00 02:25:00]
#44 193600 [02 05:46:40] 8900 [00 02:28:20]
#45 202500 [02 08:15:00] 9100 [00 02:31:40]
#46 211600 [02 10:46:40] 9300 [00 02:35:00]
#47 220900 [02 13:21:40] 9500 [00 02:38:20]
#48 230400 [02 16:00:00] 9700 [00 02:41:40]
#49 240100 [02 18:41:40] 9900 [00 02:45:00]
#50 250000 [02 21:26:40] 10100 [00 02:48:20]
#51 260100 [03 00:15:00] 10300 [00 02:51:40]
#52 270400 [03 03:06:40] 10500 [00 02:55:00]
#53 280900 [03 06:01:40] 10700 [00 02:58:20]
#54 291600 [03 09:00:00] 10900 [00 03:01:40]
#55 302500 [03 12:01:40] 11100 [00 03:05:00]
#56 313600 [03 15:06:40] 11300 [00 03:08:20]
#57 324900 [03 18:15:00] 11500 [00 03:11:40]
#58 336400 [03 21:26:40] 11700 [00 03:15:00]
#59 348100 [04 00:41:40] 11900 [00 03:18:20]
#60 360000 [04 04:00:00] 12100 [00 03:21:40]
#61 372100 [04 07:21:40] 12300 [00 03:25:00]
#62 384400 [04 10:46:40] 12500 [00 03:28:20]
#63 396900 [04 14:15:00] 12700 [00 03:31:40]
#64 409600 [04 17:46:40] 12900 [00 03:35:00]
#65 422500 [04 21:21:40] 13100 [00 03:38:20]
#66 435600 [05 01:00:00] 13300 [00 03:41:40]
#67 448900 [05 04:41:40] 13500 [00 03:45:00]
#68 462400 [05 08:26:40] 13700 [00 03:48:20]
#69 476100 [05 12:15:00] 13900 [00 03:51:40]
#70 490000 [05 16:06:40] 14100 [00 03:55:00]
#71 504100 [05 20:01:40] 14300 [00 03:58:20]
#72 518400 [06 00:00:00] 14500 [00 04:01:40]
#73 532900 [06 04:01:40] 14700 [00 04:05:00]
#74 547600 [06 08:06:40] 14900 [00 04:08:20]

Remote Retry Schedule is governed by 400 * (x * x), where x is the try number

qmail-send delivery retry times, for chanskip=20 (remote)
Try ======= after ======= == delay until next =
seconds dd hh mm ss seconds dd hh mm ss
#00 0 [00 00:00:00] 400 [00 00:06:40]
#01 400 [00 00:06:40] 1200 [00 00:20:00]
#02 1600 [00 00:26:40] 2000 [00 00:33:20]
#03 3600 [00 01:00:00] 2800 [00 00:46:40]
#04 6400 [00 01:46:40] 3600 [00 01:00:00]
#05 10000 [00 02:46:40] 4400 [00 01:13:20]
#06 14400 [00 04:00:00] 5200 [00 01:26:40]
#07 19600 [00 05:26:40] 6000 [00 01:40:00]
#08 25600 [00 07:06:40] 6800 [00 01:53:20]
#09 32400 [00 09:00:00] 7600 [00 02:06:40]
#10 40000 [00 11:06:40] 8400 [00 02:20:00]
#11 48400 [00 13:26:40] 9200 [00 02:33:20]
#12 57600 [00 16:00:00] 10000 [00 02:46:40]
#13 67600 [00 18:46:40] 10800 [00 03:00:00]
#14 78400 [00 21:46:40] 11600 [00 03:13:20]
#15 90000 [01 01:00:00] 12400 [00 03:26:40]
#16 102400 [01 04:26:40] 13200 [00 03:40:00]
#17 115600 [01 08:06:40] 14000 [00 03:53:20]
#18 129600 [01 12:00:00] 14800 [00 04:06:40]
#19 144400 [01 16:06:40] 15600 [00 04:20:00]
#20 160000 [01 20:26:40] 16400 [00 04:33:20]
#21 176400 [02 01:00:00] 17200 [00 04:46:40]
#22 193600 [02 05:46:40] 18000 [00 05:00:00]
#23 211600 [02 10:46:40] 18800 [00 05:13:20]
#24 230400 [02 16:00:00] 19600 [00 05:26:40]
#25 250000 [02 21:26:40] 20400 [00 05:40:00]
#26 270400 [03 03:06:40] 21200 [00 05:53:20]
#27 291600 [03 09:00:00] 22000 [00 06:06:40]
#28 313600 [03 15:06:40] 22800 [00 06:20:00]
#29 336400 [03 21:26:40] 23600 [00 06:33:20]
#30 360000 [04 04:00:00] 24400 [00 06:46:40]
#31 384400 [04 10:46:40] 25200 [00 07:00:00]
#32 409600 [04 17:46:40] 26000 [00 07:13:20]
#33 435600 [05 01:00:00] 26800 [00 07:26:40]
#34 462400 [05 08:26:40] 27600 [00 07:40:00]
#35 490000 [05 16:06:40] 28400 [00 07:53:20]
#36 518400 [06 00:00:00] 29200 [00 08:06:40]
#37 547600 [06 08:06:40] 30000 [00 08:20:00]
#38 577600 [06 16:26:40] 30800 [00 08:33:20]
#39 608400 [07 01:00:00] 31600 [00 08:46:40]
#40 640000 [07 09:46:40] 32400 [00 09:00:00]
#41 672400 [07 18:46:40] 33200 [00 09:13:20]
#42 705600 [08 04:00:00] 34000 [00 09:26:40]
#43 739600 [08 13:26:40] 34800 [00 09:40:00]
#44 774400 [08 23:06:40] 35600 [00 09:53:20]
#45 810000 [09 09:00:00] 36400 [00 10:06:40]
#46 846400 [09 19:06:40] 37200 [00 10:20:00]
#47 883600 [10 05:26:40] 38000 [00 10:33:20]
#48 921600 [10 16:00:00] 38800 [00 10:46:40]
#49 960400 [11 02:46:40] 39600 [00 11:00:00]
#50 1000000 [11 13:46:40] 40400 [00 11:13:20]
#51 1040400 [12 01:00:00] 41200 [00 11:26:40]
#52 1081600 [12 12:26:40] 42000 [00 11:40:00]
#53 1123600 [13 00:06:40] 42800 [00 11:53:20]
#54 1166400 [13 12:00:00] 43600 [00 12:06:40]
#55 1210000 [14 00:06:40] 44400 [00 12:20:00]
#56 1254400 [14 12:26:40] 45200 [00 12:33:20]
#57 1299600 [15 01:00:00] 46000 [00 12:46:40]
#58 1345600 [15 13:46:40] 46800 [00 13:00:00]
#59 1392400 [16 02:46:40] 47600 [00 13:13:20]
#60 1440000 [16 16:00:00] 48400 [00 13:26:40]
#61 1488400 [17 05:26:40] 49200 [00 13:40:00]
#62 1537600 [17 19:06:40] 50000 [00 13:53:20]
#63 1587600 [18 09:00:00] 50800 [00 14:06:40]
#64 1638400 [18 23:06:40] 51600 [00 14:20:00]
#65 1690000 [19 13:26:40] 52400 [00 14:33:20]
#66 1742400 [20 04:00:00] 53200 [00 14:46:40]
#67 1795600 [20 18:46:40] 54000 [00 15:00:00]
#68 1849600 [21 09:46:40] 54800 [00 15:13:20]
#69 1904400 [22 01:00:00] 55600 [00 15:26:40]
#70 1960000 [22 16:26:40] 56400 [00 15:40:00]
#71 2016400 [23 08:06:40] 57200 [00 15:53:20]
#72 2073600 [24 00:00:00] 58000 [00 16:06:40]
#73 2131600 [24 16:06:40] 58800 [00 16:20:00]
#74 2190400 [25 08:26:40] 59600 [00 16:33:20]

SEE ALSO

nice(1) addresses(5), envelopes(5), qmail-control(5), qmail-srs(5), qmail-log(5), qmail-queue(8), qmail-multi(8), drate(1), qmail-start(8), qscheduler(8), multi-queue(7), qmail-todo(8), qmail-clean(8), qmail-lspawn(8), qmail-dkim(8), dk-filter(8), qmail-rspawn(8), fsync(2) fdatasync(2)