The qf
file holds all the information
that is needed to perform delivery of a queued mail
message. The information contained in that file, and its appearance,
changes from release to release of sendmail.
Here, we document the qf
file that is used with V8.8 sendmail.
Note that as of V8.7 a V
version line has been introduced
to enable future versions to correctly process older version's queue files.
This section must be taken with a proverbial grain of salt. The internals
of the qf
file are essentially an internal interface
to sendmail and, as such, are subject to change without
notice. The information offered here is intended only to help
debug sendmail problems. It is not intended (and
we strongly discourage its use) as a
guide for writing files directly to the queue.
The qf
file is line-oriented, containing one item of information per
line. Each line begins with a single uppercase character (the code
letter), which
specifies the contents of the line. Each code letter is followed,
with no intervening space, by the information appropriate to
the letter. The complete list of code letters is shown in
Table 23.2.
Code | Meaning | Version | How Many | |
---|---|---|---|---|
B | Section 23.9.1 | Body type | V8.6 and above | At most one |
C | Section 23.9.2 | Controlling user | V5.62 and above | At most one per R line |
D | Section 23.9.3, D line | Data filename | Obsolete as of V8.7 | Exactly one |
E | Section 23.9.4, E line | Errors to | V8.6 and earlier | Many |
F | Section 23.9.5, F line | Flag bits | V8.1 and above | Many |
H | Section 23.9.6, H line | Header definition | All versions | Many |
I | Section 23.9.8, K line | df file's inode number | V8.7 and above | Exactly one |
K | Section 23.9.8 | Time last processed | V8.7 and above | Exactly one |
M | Section 23.9.9 | Message (why queued) | All versions | At most one |
N | Section 23.9.10, N line | Number times tried | V8.7 and above | At most one |
P | Section 23.9.11 | Priority (current) | All versions | At most one |
Q | Section 23.9.12, Q line | Original recipient | V8.7 and above | At most one per R line |
R | Section 23.9.13 | Recipient address | All versions | Many |
S | Section 23.9.14 | Sender address | All versions | Exactly one |
T | Section 23.9.15 | Time created | All versions | Exactly one |
V | Section 23.9.16, V line | Version | V8.7 and above | Exactly one |
Z | Section 23.9.17, Z line | DSN envelope ID | V8.7 and above | At most one |
$ | Section 23.9.18, $ line | Restore macro value | V8.6 and above | At most one each |
. | Section 23.9.19, . line | End of qf file | V8.7 and above | At most one |
Some code letters may appear only once in a qf
file;
others may appear many times. Any line that begins
with a tab or space character is joined to the line above it.
Empty lines are ignored. The order in which these lines appear in the
qf
file is important for the mailq command to work properly.
We discuss the individual lines in the qf
file by code letters. Each letter is
presented in alphabetical order rather than the order in which they should appear
in the qf
file.
Message body type
(V8.6 and above)The message body type is described under the
-B
command-line switch (see Section 36.7.1). TheB
line in theqf
file stores whatever the body type was set to, either from the command line or by the SMTP MAIL command. The two usual body types are8BITMIME
or7BIT
.The form of the
B
line isBtype
There must be no space between the
B
and thetype
. If thetype
is missing, the body type becomes the character value zero. If the entireB
line is missing, the default is7BIT
. Iftype
is longer than MAXNAME as defined in conf.h (see Section 18.8.19, MAX...) when compiling sendmail, it is truncated to MAXNAME-1 characters when theqf
file is read.Note that the
type
must be either7bit
or8bitmime
. Anything else will not be detected when theqf
file is read and may eventually cause the ESMTP dialogue to fail:501 <sender>... Unknown BODY type badtypeThis error will be reproduced at every MX site for the recipient until a site that does not speak ESMTP is found or until the MX list is exhausted.
Set controlling user
(V5.62 and above)To ensure secure handling of delivery, recipient addresses that are either a file or a program require that sendmail perform delivery as the owner of the file or program rather than as root. A file address is one that begins with a
/
character. A program address is one that begins with a|
character. Both characters are detected after quotation marks have been stripped from the address.To prevent potential security violations, sendmail must take special precautions when addresses in the
qf
file result from reading a ~/.forward or:include:
file. When such an address is to be placed into theqf
file (whether as a recipient's address in anR
line or as an error recipient's address in anE
line), sendmail first places aC
line (for Controlling user) into the file and then the recipient's address. TheC
line specifies the owner of the ~/.forward or:include:
file:Cgeorge RPF:/u/users/george/mail/archive Cben RPF:|/u/users/ben/bin/mailfilterHere, when sendmail later delivers to the recipients in this
qf
file, it first converts its user identity to that of the user george, then resets itself back to being root again. The same process repeats with the next recipient, except that sendmail changes from root to ben and back again. If there is noC
line preceding aR
line, the previousC
line's value is carried down:Cgeorge RPF:/u/users/george/mail/archive RPF:|/u/users/ben/bin/mailfilter controlling user is georgeThe form of the
C
line in theqf
file isCuser
Prior to V8 Cuser:eaddr
V8.1 through V8.7.5 Cuser:uid:gid:eaddr
V8.7.6 and V8.8The
C
must begin the line and be immediately followed byuser
, with no intervening space. If nouser
follows theC
, any prior controlling user is cleared and the identity that is used reverts to that specified by theDefaultUser
(u
) option (see Section 34.8.15, DefaultUser (g)(u)). If present, theuser
is the login name of the owner of the ~/.forward or:include:
file that yielded the address in the next followingR
orE
line. Ifuser
is the name of a user who is unknown to the system, prior to V8.7.6 and prior to V8.8 the effect was the same as if it were missing. Beginning with V8.8 and V8.7.6, an unknownuser
causes the identity to become that of theuid
andgid
. Beginning with V8 sendmail, an optionaleaddr
may be last. If present, theeaddr
gives the address to use for error messages.There may be only one
C
line immediately preceding eachR
andE
line. TwoC
lines in a row have the effect of the second superseding the first.
Data filename
(Obsolete as of V8.7)Beginning with V8.7 sendmail looks for its data file (the file containing the message body) under the same name as its
qf
file, but with theq
changed into ad
. Prior to V8.7, theD
line in theqf
file contained the name of the file that contained the message body. If theD
line was missing, there was no message body. The form of theqf
fileD
line wasDfile
The
D
must begin the line. Thefile
must immediately follow with no intervening space. All text, from the first character following theD
to the end of the line, is taken as the name of the file. There is no default forfile
; either it must be present, or the entireD
line must be absent.The sendmail program opens the
df
file
for reading. If that open fails, sendmail syslog(3)'s the following error message at LOG_CRIT and continues to process theqf
file:readqf: cannot open dfAA12345Be aware that sendmail attempts to remove the
file
after it has been delivered to all recipients. If sendmail is unable to remove thefile
, and if theLogLevel
(L
) option (see Section 34.8.33, LogLevel (L)) is greater than 97, sendmail syslog(3)'s the following warning at LOG_DEBUG:file: unlink-fail #The file is the name of the file that could not be removed. The # is the error number, as defined in /usr/include/errno.h.
The
df
file is opened only when processing the queue file, not when printing it.
Send errors to
(V8.6 and earlier)Notification of errors often requires special handling by sendmail. When mail to a mailing list fails, for example, sendmail looks for the owner of that list. If it finds one, the owner, not the sender, receives notification of the error. To differentiate error notification addresses from ordinary sender and recipient addresses, pre-V8.7 sendmail stored error addresses separately in the
qf
file, one perE
line. Beginning with V8.7, thisE
line is no longer used. Instead, sendmail uses theS
line.The form of the
E
line in theqf
file looks like this:Eaddr
V8.6 and earlierThe
E
must begin the line. One or more addresses may be entered on that same line. Whitespace and commas may surround the individual addresses. Note, however, that sendmail places only a single address on eachE
line. There may be multipleE
lines. Each is processed in turn.Each line is fully processed as it is read. That is, the line is scanned for multiple addresses. Each address that is found is alias-expanded. Each resulting new address is processed by rule sets 3 and 0 to resolve a delivery agent for each.
If an alias expands to a program or a file (text that begins with a
/
or|
character), that text is sent out in the delivered message'sErrors-To:
line in that form. This can cause confusion when the message is later processed and bounced at the receiving site.
Saved flag bits
(V8.1 and above)Under V8 sendmail the
Timeout.queuewarn
option (see Section 34.8.70) can specify an interval to wait before notifying the sender that a message could not immediately be delivered. To keep track of whether such a notification has been sent, sendmail stores the state of its EF_WARNING envelope flag in theqf
file. If that flag is set, notification has already been sent.Error mail messages sent by sendmail may occasionally be queued, rather than immediately delivered. The
Timeout.queuewarn
option notification should not be sent for such mail. If such mail remains in the queue too long, it should be canceled rather than bounced. V8 sendmail saves the state of the EF_RESPONSE envelope flag in theqf
file. If that flag is set, the message is an error notification.Beginning with V8.8, sendmail also records the state of the EF_HAS8BIT flag (the message body contains 8-bit data) and the EF_DELETE_BCC flag (delete empty
Bcc:
headers; see Section 35.10.4, Bcc:).All envelope flags are listed in Table 37.3 of Section 37.5.12, -d2.1. The
F
line is used to save envelope flags for later restoration. Its form looks like this:Fflags
Here, the
flags
are any combination ofw
, which restores (sets) the EF_WARNING flag;r
, which restores the EF_RESPONSE flag;8
, which restores the EF_HAS8BIT flag; andb
, which restores the EF_DELETE_BCC flag. Only those letters are recognized. Other letters are silently ignored. Note that these flags may be done away with in later versions of sendmail and new flags may be added without notice.For security protection, V8 sendmail rejects and logs the following flag sequence:
From a space hereSee Section 23.3.5, "Funny Flag Bits in qf File" for more information about this.
Header line
(All versions of sendmail)The lines of text that form the message header are saved to the
qf
file, one perH
line. Any header lines added by sendmail are also saved toH
lines in theqf
file.The form of the
H
line is:Hdefinition
The
H
must begin the line, and thedefinition
must immediately follow with no intervening space. Thedefinition
is exactly the same as, and obeys the same rules as, theH
commands in the configuration file (see Section 35.1, "The H Configuration Command").When sendmail writes header lines to the
qf
file, it pre-expands macros (replaces expressions such as$x
with their values) and preresolves conditionals ($?
,$!
, and$.
).The order in which
H
lines appear in theqf
file is exactly the same as the order in which they appear in the delivered message.
Inode and device information for the df file
(V8.7 and above)When a machine crashes under UNIX, files in a directory may become detached from that directory. When this happens, those orphaned files are saved in a directory called lost+found. Because file names are saved only in directories, orphaned files are nameless. Consequently, UNIX stores them in lost+found using their inode numbers as their names.
To illustrate, consider finding these four files in lost+found after a crash:
#1528 #1200 #3124 #3125Two of these are
qf
files, and two aredf
files. Beginning with V8.7 sendmail theqf
files contain a record of the inode numbers for their correspondingdf
files. That information is stored in theI
line:Imajor/minor/ino
Here, the
major
andminor
are the major and minor device numbers for the disk device that thedf
file was stored on. Theino
is the inode number for thedf
file. In our above lost+found example the following command could be run to pair up the orphaned files:%grep "^I.*/.*/" *
#1200:I123/45/3124 #1325:I123/45/1528This shows that the
qf
file #1200 has thedf
file #3124 and that theqf
file #1325 has thedf
file #1528.The sendmail program does not check the inode number in the
I
line against the actual inode number of thedf
file. Instead, theI
line is generated afresh each time theqf
file is processed.
The time last processed from the queue
(V8.7 and above)The
MinQueueAge
option (see Section 34.8.41) sets the length of time a queued message must remain queued before delivery can again be tried. Each time sendmail processes aqf
file, it subtracts the time stored in theK
line from the current time and compares the result to theMinQueueAge
. If sufficient time has not passed, the rest of processing is skipped. (Note that this test is performed only if theqf
file has been processed at least once; see theN
line in Section 23.9.10).The time stored in the
K
line looks like this:K703531020This number represents the date and time in seconds. Every time the
qf
file is processed (delivery is attempted), theK
line is updated with the current time.
The reason message was queued
(All versions of sendmail)When a mail message is placed into the queue because of an error during the delivery attempt, the nature of that error is stored in the
M
line of theqf
file. The error is usually prefixed withDeferred
:Deferred: reasonDelivery can be deferred until a later queue run because of a temporary lack of services. For example, the reason may be "remote host is down."
The form of the
qf
fileM
line is:Mmsg
The
M
must begin the line. It is immediately followed by themsg
with no intervening space. The text ofmsg
is everything up to the end of the line. Themsg
created by sendmail may include the wordDeferred:
, followed by a reason. TheM
line should appear before theS
line.If the
msg
is missing, sendmail simply prints a blank line rather than a reason when showing the queue with mailq or the-bp
command-line switch. If theM
line is entirely missing, sendmail prints nothing.The maximum number of characters in
msg
is defined by MAXLINE in conf.h (see Section 18.8.19). There should be only oneM
line in aqf
file. If there are multipleM
lines, only the last is used. If multiple recipients produced error messages, only the last one is stored in anM
line.
Number of times tried
(V8.7 and above)Each time delivery is attempted for a message, the number stored in its
qf
file'sN
line is incremented by one. This number always begins at zero.When delivering many messages to a single host, sendmail remembers failures. If one message fails to make it all the way through an SMTP dialogue, all the following messages to that same host will be deferred (not attempted during the current queue run). For those deferred messages the number of tries is correctly incremented as though the delivery was actually attempted.
The value in this
N
line is used to determine whether the delay of theMinQueueAge
option (see Section 34.8.41) should be triggered. This value, when zero, can also be used to enable a special first-time connection timeout (see Section 34.8.70.9, "Timeout.iconnect").
Priority when processed from queue
(All versions of sendmail)Not all messages need to be treated equally. Messages that have failed often, for example, tend to continue to fail. When sendmail processes the messages in its queue, it sorts them by priority that was and attempts to deliver those most likely to succeed first.
When a mail message is first placed into the queue, it is given an initial priority calculated when it was first created (see Section 34.8.53), which is stored in the
P
line:P640561This number in the
qf
file is really a cost. The lower it is, the more preferentially the message is treated by sendmail. Each time theqf
file is read, the number in theP
line is incremented. The size of that increment is set by the value of theRetryFactor
(Z
) option (see Section 34.8.56, RetryFactor (Z)). If that option is negative, the logic of "what fails will continue to fail" is inverted.The form of the
qf
fileP
line isPpri
The
P
must begin the line. Thepri
is a text representation of an integer value. Thepri
must immediately follow theP
with no intervening space. The text inpri
is converted to an integer using the C library routine atol(3). That routine allowspri
to be represented in text as a signed decimal number, an octal number, or a hexadecimal number.If
pri
is absent, the priority value used is that of the configuration fileRetryFactor
(Z
) option. If the entireP
line is absent, the priority value begins as zero.There should be only one
P
line in anyqf
file. MultipleP
lines cause all but the last to be ignored.
The DSN ORCPT address
(V8.7 and above)When a mail message arrives that includes an ORCPT parameter for the ESMTP RCPT command (see RFC1891), sendmail needs to save that parameter's information separately from the RCPT recipient address:
RCPT TO:<gw@wash.dc.gov> ORCPT=rfc822;gw@wash.dc.gov recipient address parameter's informationNot all sites understand ESMTP. If sendmail forwards the message to such a site, it needs to omit the ORCPT parameter. Consequently, sendmail must not store that parameter with the RCPT address.
The
Q
line is used to separately store the ORCPT parameter information:Qtype
;addr
The
type
;
addr
is defined by RFC1891. The sendmail program checks the validity ofaddr
when that information is received but otherwise merely storestype
;
addr
as is in theQ
line.There must be only a single
Q
line for each recipientR
line, and each suchQ
line must precede its correspondingR
line.
Recipient's address
(All versions of sendmail)The
qf
file lists all the recipients for a mail message. There may be one recipient or many. When sendmail creates theqf
file, it lists each recipient address on an individualR
line. The form of theR
line in theqf
file looks like this:Rflags:addr
The
R
must begin the line. Only a single address may appear on eachR
line. There may be multipleR
lines. Each is processed in turn.If the colon is present and if the version of the
qf
file is greater than 0, the characters between theR
and the colon are interpreted as flags that further define the nature of the address:P
(primary) Addresses can undergo many transformations prior to delivery. When expanding aliases, for example, the address george might be transformed into two addresses via a ~/.forward file: george@here and george@there. In this instance, george is the primary address, and the aliases are secondary addresses. If aliasing yields only a single transformation, the single new address is considered primary. Addresses that are received via a RCPT SMTP command are always considered primary, as are all other recipient addressees prior to aliasing.N
(notify) Recipient addresses can lead to various kinds of notification based on the nature of the DSN NOTIFY extension to the RCPT SMTP command. That notification can be either NEVER or some combination of SUCCESS, FAILURE, or DELAY. Internally, sendmail uses the absence of the latter three to imply NEVER. ThisN
flag simply says that the DSN NOTIFY extension appeared in the message. If theN
is absent, but anS
,F
, orD
is present, DSN information will not be propagated. Note that NOTIFY can also be specified by using the-N
command line switch (see Section 36.7.28, -N).
S
,F
,D
(success, failure, delay) The DSN NOTIFY extension to the RCPT SMTP command will specify either NEVER or some combination of SUCCESS, FAILURE, or DELAY. When any of these is specified, its first letter is used as a flag for the recipient address. SUCCESS means to notify the sender that final delivery succeeded. FAILURE is used to notify the sender that some step toward delivery failed fatally. DELAY lets the sender know that the message has been delayed but delivery will continue to be attempted.
Each
R
line is fully processed as it is read. That is, the line is scanned for multiple addresses. Each address that is found is alias-expanded. Each resulting new address is processed by rule sets 3 and 0 to resolve a delivery agent for each.
Sender's address
(All versions of sendmail)Each mail message must have a sender. The sendmail program can determine the sender in four ways:
If the sender is specified in the envelope of an SMTP connection, that sender's address is used.
If the
-f
command-line argument is used to run sendmail, the sender's address is the address following the-f
.If the sender is not specified in the envelope, the address that is used is that of the user who ran the sendmail program. If that user is unknown, the sender is made to be postmaster.
When processing the queue, the sender's address is specified in the
S
line of theqf
file.The form of the
S
line in theqf
file looks like this:Saddr
The
S
must begin the line. Exactly one address must follow on that same line. Whitespace may surround that address. There may be only oneS
line in theqf
file.If the
addr
is missing, sendmail sets the sender to be the user who ran sendmail. If that user is not known in the passwd file (or database), sendmail syslog(3)'s the following message and sets the sender to be postmaster:Who are you?The resulting address is then processed to extract the user's full name into
$x
(see Section 31.10.42, $x). Finally, the sender's address is rewritten by rule sets 3, 1, and then 4.Under all versions of sendmail the address in the
S
line will include any RFC822 comment text that appeared with the original message. Under V8.7, if theF=c
flag (see Section 30.8.14, F=c) is set for the sender's delivery agent, all comment text is stripped from the address.If sendmail is compiled with USERDB defined (see Section 18.8.54, USERDB), the sender address can optionally be rewritten by the User Database before it is placed into the
S
line. Such rewriting is allowed only if the delivery agent for the sender includes theF=i
flag (see Section 30.8.24, F=i).
Creation time
(All versions of sendmail)To limit the amount of time a message can remain in the queue before being bounced, sendmail must know when that message was first placed in the queue. That time of first placement is stored in the
T
line in theqf
file. For example, the following number represents the date and time in seconds:T703531020Each time sendmail fails to deliver a message from the queue, it checks to see whether too much time has passed. It adds the
T
line value to the value specified in theTimeout.queuereturn
(T
) option (see Section 34.8.70). If that sum is less than the current time, the message is bounced instead of being left in the queue.Messages are occasionally left in the queue for longer than the normal timeout period. This might happen, for example, if a remote machine is down but you know that it will eventually be brought back up. There are two ways to lengthen the amount of time a message may remain in the queue.
The preferred way is to create a temporary separate queue directory and move the necessary queued file to that temporary holding place. When the remote site comes back up, you can later process the files in that other queue by running sendmail with an artificially long
Timeout.queuereturn
value (see Section 23.7).A second way to extend the life of messages in the queue is to edit the
qf
file and change the value stored in theT
line. Just add 86400 to that value for each day you want to extend. Care is required to avoid editing a file that is currently being processed by sendmail. [8][8] The nvi(1) editor uses the same file locking as sendmail and so can safely be used to edit
qf
files.There is currently no plan to give sendmail the ability to rejuvenate queued messages (make old messages appear young).
The form of the
T
line in theqf
file is:Tsecs
The
T
begins the line, and thesecs
must immediately follow with no intervening space. The numeric text that formssecs
is converted to an integer using the C library routine atol(3). That routine allowssecs
to be represented in text as a signed decimal number, an octal number, or a hexadecimal number.If
secs
is absent or the entireT
line is absent, the time value is zero. A zero value causes the mail message to time out immediately.There should be only one
T
line in anyqf
file. MultipleT
lines cause all but the last to be ignored.
Version of the qf file
(V8.7 and above)s sendmail evolves, it will continue to add new abilities to the
qf
file. To protect old versions of sendmail from wrongly misinterpreting new configuration files, theV
line has been introduced. Prior to V8.7 sendmail there was noV
line. For versions prior to 8.7.6 the version for theV
line is 1:V1 V8.7.5 and earlierFor V8.7.6 and above, including V8.8, the version is 2 (where version 2 changes the layout of the
C
line in theqf
file):V2 V8.7.6 and above and V8.8If the version is greater than that currently supported, sendmail will log this error and exit:
Version number in qf (bad
) greater than max (max
)A version 1
qf
file allowsflags
to follow theR
line.
DSN ENVID envelope identifier
(V8.7 and above)The MAIL ESMTP command may optionally be followed by an RFC1891 ENVID envelope identifier:
MAIL From: <address
> ENVID=envelopeID
ENVID is used to propagate a consistent envelope identifier (distinct from the
Message-ID:
header see Section 35.10.19, Message-ID:) that is permanently associated with a message.The
Z
line holds that ENVID envelope identifier information:ZenvelopeID
The ENVID information needs to be held separately from the
S
sender line because sendmail has no way to determine in advance whether a recipient host speaks ESMTP.There must be only a single
Z
line in anyqf
file. The${envid}
macro (see Section 31.10.12, ${envid}) also stores the ENVID value.
Restore macro value
(V8.6 and above)The sendmail program uses the
$r
macro (see Section 31.10.31, $r) to store the protocol used when sendmail first received a mail message. If the message was received by using SMTP, that protocol issmtp
. Otherwise, it is NULL.The sendmail program uses the
$s
macro (see Section 31.10.33, $s) to store the full canonical name of the sender's machine.The sendmail program uses the
$_
macro (see Section 31.10.1, $-) to store RFC1413 identd(8) information and IP source routing information.When sendmail creates a
qf
file, it saves the values of the$r
,$s
, and$_
macros in lines that begin with$
.The form of the
$
line in theqf
file looks like this:$Xvalue
The
$
must begin the line, and the macro's single-character name (theX
) must immediately follow with no intervening space. TheX
is followed (again with no intervening space) by the value of the macro.If
value
is missing, the value given to the macro is NULL. If theX
andvalue
are missing, the macro\0
is given a value of NULL. If both are present, the macro that is specified (X
) is given the value specified (value
).There may be multiple
$
lines. The need to quickly process aqf
file requires that only single-character macro names be used.
Mark EOF in qf file
(V8.7 and above)One form of attack against sendmail involves appending information to an existing
qf
file. To prevent such attacks, V8.7 introduced the dot line. In aqf
file, any line that begins with a single dot:.followed by anythingis considered to mark the end of the file's useful information. Upon encountering that dot, sendmail continues to read the
qf
file. If any line follows the dot line, sendmail logs the following message and changes theqf
file into aQf
file (see Section 23.3.3, "Extra Data at End of qf File"):SECURITY ALERT: extra data in qf: bogus line here