Package: postqf
PostQFCopyright © 2022 Ralph SeichterPostQF is a user-friendlyPostfixqueue data filter which operates on data produced bypostqueue -j. See the manual page's subsection titled "JSON object format"
for details. PostQF offers convenient features for analysis and and cleanup of Postfix mail queues.I have used the all-purpose JSON manipulation utility "jq" before, but found it inconvenient for everyday Postfix
administration tasks. "jq" offers great flexibility and handles all sorts of JSON input, but it comes at the cost of
complexity. PostQF is an alternative specifically tailored for easier access to Postfix queues.To facilitate the use of Unix-likepipelines, PostQF usually reads
fromstdinand writes tostdout. Using command line arguments, you can override this behaviour and define one or
more input files and/or an output file. Depending on the context, a horizontal dash-represents eitherstdinorstdout. See the command line usage description below.Example usageFind all messages in thedeferredqueue where the delay reason contains the stringconnection timed out.postqueue-j|postqf-qdeferred-d'connection timed out'Find all messages in theactiveorholdqueues which have at least one recipient in theexample.comorexample.orgdomains, and write the matching JSON records into the file/tmp/output.postqueue-j|postqf-q'active|hold'-r'@example\.(com|org)$'-o/tmp/outputFind all messages all queues for which the sender address isalice@gmail.comorbob@gmail.com, and pipe the queue
IDs topostsuperin order to place the matching messages on hold.postqueue-j|postqf-s'^(alice|bob)@gmail\.com$'-i|postsuper-h-Print the number of messages which arrived during the last 30 minutes.postqueue-j|postqf-a30m|wc-lThe next example assumes a directory/tmp/datawith several files, each containing JSON output produced at some
previous time. The command pipes all queue IDs which have ever been in theholdqueue into the fileidlist, relying
on BASH wildcard expansion to generate a list of input files.postqf-i-qhold/tmp/data/*.json>idlistCount unique recipient address domains for deferred messages and print a sorted list:postqueue-j|postqf-qdeferred--rdomFiltersQueue entries can be easily filtered byArrival timeDelay reasonQueue nameRecipient addressSender addressand combinations thereof, usingregular expressions. Anchoring is optional,
meaning that plain text is treated as a substring pattern.Time based filtersArrival time filters do not use regular expressions, but support the following formats instead:ISO 8601time strings.Unix time(the number of seconds since January 1, 1970). This is the
representation of arrival time returned in JSON-format Postfix queue data.Time difference, expressed as one or more digits followed by a single "unit" characters, m, h,ord. These units
designate seconds, minutes, hours and days. The resulting timestamp will be in the past, as in "now minus the
difference".Please keep in mind that formats 1 and 2 are used for fixed timestamps, while format 3 represents time differences
against the time of running PostQF. When format 3 is used with static input data (say, JSON data you saved to disk
sevaral days ago) the results may vary as time progresses. When in doubt, use absolute time formats.The command line option-a Xmeans "message arrived after timeX", and-b Ymeans "message arrived before
timeY". The filter string can have any of the supported formats, and you can mix them freely. Here are some
examples of valid command line arguments:-a 2022-01-23T08:30 -b 2022-01-23T17:45January 23, 2022 between 08:30 and 17:45.-a 1642923000 -b 1642956300The same time interval, specified in Unix time.-a 90mLess than 90 minutes ago.-b 36hMore than 36 hours ago.Custom outputIn addition to filtering JSON input and producing JSON output in the process, PostQF can also generate a number of
simple reports to answer some of the most frequently asked questions about message queue content. The following data can
be shown in reports:Delay reasonRecipient addressRecipient domainSender addressSender domainAnother type of custom output is a list of raw message IDs associated with the filter criteria. ID lists can be piped to
utilities likepostsuper. Please note that only one type of report or custom
output can be generated at a time, and that the necessary command line options are therefore mutually exclusive.Command line usagepostqf [-h] [-d REGEX] [-q REGEX] [-r REGEX] [-s REGEX] [-a TS] [-b TS] [-o OUTFILE]
       [--id | --rcpt | --rdom | --reason | --sdom | --sender] [FILE [FILE ...]]

Positional arguments:
  FILE        Input file. Use a dash "-" for standard input.

Optional arguments:
  -h, --help  show this help message and exit
  -o OUTFILE  Output file. Use a dash "-" for standard output.

Regular expression filters:
  -d REGEX    Delay reason filter.
  -q REGEX    Queue name filter.
  -r REGEX    Recipient address filter.
  -s REGEX    Sender address filter.

Arrival time filters:
  -a TS       Message arrived after TS.
  -b TS       Message arrived before TS.

Custom output (mutually exclusive):
  --id, -i    ID output only.
  --rcpt      Recipient address report.
  --rdom      Recipient domain report.
  --reason    Delay reason report.
  --sdom      Sender domain report.
  --sender    Sender address report.InstallationThe only installation requirement is Python 3.7 or newer. PostQF is distributed viaPyPI.organd is typically installed using eitherpiporpip3, depending on your
Python distribution.I also provide an installer script as an alternative. It will download the latest PostQF release into the current
directory, and generate an executable launcher. A small disadvantage of this method is that it will not check if you
have a supported Python version installed.# Typical: Installation using 'pip'.pipinstallpostqfThepipinstallation process also adds apostqflauncher executable. The exact location depends on your Python
distribution, and you might need to modify your PATH environment variable for easy access.# Alternative: Official installation script.mkdir~/postqfcd~/postqf# Download and run the install script. If successful, it will print a message# similar to "You can now launch PostQF using /home/alice/postqf/postqf".curl-fLhttps://github.com/rseichter/postqf/raw/master/scripts/install|bashContactThe project is hosted on GitHub in therseichter/postqfrepository. If you have
suggestions or run into any problems, please check thediscussionssection first. There is also anissuetracker available, and thebuild configurationfile contains a contact email address.