QTOOL(8)

📦 version 8.15.2, in ubuntu jammy

💖 QTOOL — the qtool(8) glow-up 💖

okay bestie, so you know that section 8 of the System Manager's Manual? yeah. we're doing qtool. it's giving queue herding and honestly it ate.

✨ NAME ✨

qtool — manipulate sendmail queues 🎀

🌸 SYNOPSIS 🌸

qtool.pl [options] target_directory source [source ...]

qtool.pl [-Q][-d|-b] [options] source [source ...]

💅 DESCRIPTION 💅

So Qtool moves the queue files that sendmail uses, from one queue to another. it uses the same locking mechanism as sendmail, so you can lowkey run it while sendmail is running and nothing bad happens. 🫶

but babe. listen. it should not be used when queue groups have been configured to move queue files into directories they don't belong in, according to the queue group selections made in the sendmail.cf file. unless you are absolutely sure you're not interfering with the queue group selection mechanism, do not move queue files around. periodt.

With no options, qtool will move any queue files as specified by source into target_directory. and source can be literally any of these three things:

  • an individual queue control file
  • a queue file id
  • a queue directory

If the -d option is specified, qtool will delete the messages specified by source instead of moving them. 😭

If the -b option is specified, the selected messages get bounced by running sendmail with the -OTimeout.queuereturn=now option. 💀

✨ Options ✨

  • -b — Bounce all of the messages specified by source. the messages get bounced immediately. no attempt will be made to deliver the messages. no thoughts, head empty, straight to the bounce bin. 💀
  • -C configfile — Specify the sendmail config file. defaults to /etc/mail/sendmail.cf. 👑
  • -d — Delete all of the messages specified by source. 🗑️
  • -e perl_expression — Evaluate perl_expression for each queue file as specified by source. if perl_expression evaluates to true, then that queue file is moved. see below for more detail on perl_expression. 🧚
  • -Q — Operate on quarantined items (queue control file begins with hf instead of qf). quarantine era, we love a little isolation moment. 🙈
  • -s seconds — Move only the queue files specified by source that have a modification time older than seconds. ⏳

🦋 Perl Expressions 🦋

okay this is the fun part. you can use any valid perl expression. inside the expression you have access to a hash that contains many of the fields in the control file, plus some other data about that queued message. that hash is called %msg. 🌈

if a field has multiple values (e.g. 'Recipient'), it will be returned as an array, otherwise it will be returned as a scalar. slay.

Through %msg, you can access the following variables:

  • auth — AUTH= parameter.
  • body_type — Body type (8BITMIME, 7BIT, or undefined).
  • body_last_mod_time — The last time the body was modified since the epoch in seconds.
  • body_size — The size of the body file in bytes.
  • content-length — Content-Length: header value (Solaris sendmail only).
  • controlling_user — The controlling user.
  • control_last_mod_time — The last time the control file was modified since the epoch in seconds.
  • control_size — The size of the control file in bytes.
  • creation_time — The time when the control file was created.
  • data_file_name — The data file name (deprecated). ⚠️
  • deliver_by — Deliver by flag and deadline for DELIVERBY ESMTP extension.
  • envid — Original envelope id form ESMTP.
  • error_recipient — The error recipient (deprecated). ⚠️
  • final_recipient — Final recipient (for DSNs).
  • flags — Array of characters that can be the following values:
    • w — warning message has been sent
    • r — This is an error response or DSN
    • 8 — has 8 bit data in body
    • b — delete Bcc: headers
    • d — envelope has DSN RET= parameter
    • n — don't return body
  • headers — This is a Perl hash where the keys are rfc822 field names and the values are rfc822 field values. If a field has only one value it will be returned as a string. If a field has more than one value (e.g. 'Received') it will be returned as a list of strings.
  • inode_number — The inode number for the data (body) file.
  • next_delivery_time — Earliest time of next delivery attempt.
  • num_delivery_attempts — Number of delivery attempts that have been made.
  • macro — Defined macro.
  • message — Envelope status message.
  • original_recipient — Original recipient (ORCPT= parameter).
  • priority — Adjusted priority of message.
  • quarantine_reason — Quarantine reason for quarantined (held) envelopes.
  • recipient — Array of character flags followed by colon and recipient name. Flags:
    • N — Has NOTIFY= parameter.
    • S — Success DSN requested.
    • F — Failure DSN requested.
    • D — Delay DSN requested.
    • P — Primary address (not the result of alias/forward expansion).
  • sender — Sender
  • version — Version of control file.

🔥 EXAMPLES 🔥

okay here's the vibe check, bestie. look at these:

qtool.pl q2 q1

Moves all of the queue files in queue q1 to queue q2.

qtool.pl q2 q1/d6CLQh100847

Moves the message with id d6CLQh100847 in queue q1 to queue q2.

qtool.pl q2 q1/qfd6CLQh100847

Moves the message with id d6CLQh100847 in queue q1 to queue q2.

qtool.pl -e '$msg{num_delivery_attempts} == 3' /q2 /q1

Moves all of the queue files that have had three attempted deliveries from queue q1 to queue q2. iconique.

💀 BUGS 💀

In sendmail 8.12, it is possible for a message's queue and data files (df) to be stored in different queues. 😭 in this situation, you must give qtool the pathname of the queue file, not of the data file (df).

To be safe, never feed qtool the pathname of a data file (df). fr fr. do not do it.

👑 SEE ALSO 👑

sendmail(8)

🌸 HISTORY 🌸

The qtool command appeared in sendmail 8.10. ✨

aaaand that's the whole page, bestie. 🫶 this little masterpiece is dated $Date: 2013-11-22 20:51:18 $ and it lives in the System Manager's Manual as QTOOL(8) — mwah, iconic, no notes. 💅💖

📦 where this page comes from