'\" t
.\" $Header: /home/mea/src/CVSROOT/zmailer/man/mailq.1.in,v 1.18 2003/08/28 23:51:29 mea Exp $
.ds ]W "ZMailer 2.99"
.nr X
.TH MAILQ 1zm "2003-Aug-28"
.SH NAME
mailq \- zmailer mail queue printer
.SH SYNOPSIS
.IP \fBmailq\fR 6em
.\" 46c:dE:h:iK:Mp:Qr:sStu:U:vV
[\fB\-4\fR|\fB\-6\fR]
[\fB\-d\fR]
[\fB\-i\fR]
[\fB\-M\fR]
[\fB\-p\fR\ \fIport_or_socket_path\fR]
[\fB\-s\fR[\fBs\fR]]
[\fB\-t\fR]
[\fB\-u\fR\ \fIuser\fR]
[\fB\-U\fR\ \fIusername\fR/\fIpassword\fR]
[\fB\-v\fR[\fBv\fR]]
[\fB\-S\fR]
[\fB\-Q\fR[\fBQ\fR[\fBQ\fR[\fBQ\fR]]]]
[\fB\-Z\fR\ \fIzenvfile\fR]]]
[[\fB\-c\ \fIchannel\fR]\ \fB\-h\ \fIhost\fR]
[\fIhost\fR]
.PP
\fIFIXME: Not all options are documented!\fR
.SH DESCRIPTION
The 
.IR mailq (1zm)
queries a running
.IR scheduler (8zm)
process on a specified host for its current internal model of
the mail transport queues and presents this information to the user.
By default, the
.IR scheduler (8zm)
process queried is the one relevant to the local host, i.e. either a
local process or a
.IR scheduler (8zm)
on a mail server host.
If the optional
.I host
argument is specified, the
.IR scheduler (8zm)
running on that host will be queried instead.
.PP
If the
.IR scheduler (8zm)
has used
.B \-Q
option to shrink the amount of output, the
.IR mailq (1zm)
.B must
also use
.B \-Q
option to report about the queue status at the server in ``queue-summary''
format.
.PP
The information printed for each queued message is labelled by its
message file id, which is the name of the original message file in the
\fIPOSTOFFICE\fB/queue\fR directory and of the message control file in
the \fIPOSTOFFICE\fB/transport\fR directory.
The information may be different for different \fIchannel\fR/\fIhost\fR
combinations in destination addresses in a single message, so the status
information is grouped in clusters labelled by the channel and host for
addresses in the group.
.PP
The text associated with a particular deferred destination in a message
originates in a transport agent.
The
.I scheduler
annotates the transport agent messages with retry information when an
address has been scheduled for later delivery attempts, or with text
stating why a retry that should have happened was delayed.
A lack of annotations indicates a delivery attempt is in progress.
.SH OPTIONS
The normal action is to print the transport queue.
.IP "\-c \fIchannel\fR \-h \fIhost\fR"
.RS
in MAILQv2 mode (see
.IR scheduler (8zm))
query details about only those messages destined at given channel and host.
.PP
The default for \fIchannel\fR is "\fIsmtp\fR".
.RE
.IP \-d
This prints the information received from the scheduler as is.
This will override the verbose option.
This is
.I debugging
mode.
.IP \-i
.RS
prints a verbose transport queue output (see the \-v flag) for your own
messages only.
.RE
.IP \-M
.RS
Attached to an MTA instance wide shared memory segment, and
dumpts its content (various counters and gauges).
.PP
.I "This works only local in the system, unlike MAILQ-v2 queries!"
.PP
Listed variables are described at:
.IR mailq-m (5zm).
.RE
.IP \-p\ \fIport\fR
.RS
specifies an alternate TCP/IP port to connect to a
.IR scheduler (8zm)
at.
.RE
.IP \-Q
.RS
Shows full thread-wise status of
.IR scheduler 's
internal state.
.RE
.IP \-QQ
.RS
Produces abbreviated summary of 
.IR scheduler 's
internal state.
.RE
.IP \-QQQ
.RS
Shows only
.IR scheduler 's
summary statistics lines.
.RE
.IP \-QQQQ
.RS
Shows same dump as "mailq -M" produces, but can do it over the network.
.PP
Listed variables are described at:
.IR mailq-m (5zm).
.RE
.IP \-s
.RS
asks for a status of the
.IR router (8zm),
.IR scheduler (8zm),
and transport queues.
.PP
The first two are determined by scanning the appropriate directories
and counting files, whereas the status of the transport queue is
retrieved from the running
.IR scheduler (8zm)
process.
.PP
Doubling this option will cause
.IR mailq (1zm)
to exit after printing this summary.
.RE
.IP \-S
shows summary of files queued to the channel/destination.
Listed info tells the number of files, and if available, also
total- and mean-size of those files.
.IP \-t
disables any previous verbose flags to produce the normal
.I terse
output.
.IP \-u\ \fIuser\fR
.RS
selects messages sent by the specified user id.
.PP
This option is usually only useful to the Postmaster on the system.
.RE
.IP \-U\ \fIusername\fR/\fIpassword\fR
.RS
Defines username/password pair for MAILQ-V2 mode connection, in case
the default "nobody"/"nobody" is not proper.
.PP
Do note: The "/" separates fields!
.RE
.IP \-v[v]
.RS
will produce verbose transport queue output in that message id's,
and sender and recipient addresses, will be listed in addition to the normal
status line.
.PP
Doubling this option asks for extra verbose output, presently
this adds the message size in bytes after the message id.
This option is only useful if
.I mailq
can read the message control files in the postoffice.
Most users can only see the data for their own messages.
.RE
.IP "\-Z\ \fIzenvfile\fR"
:RS
passes on explicite non-compiled-in-default located ZCONFIG environment file.
.RE
.PP
.SH mailq -Q output codes
Examples of ``mailq -Q'' output:
.PP
.nf
\fCsmtp/*.com/0
.RS 3em
\fCsmtp/aol.com/0  \fRR=1 A=147 P={19598} HA={571}s FA={571}s OF=1 S={STUFF} UF=0 QA=1d18h
\fCsmtp/some.com/0 \fRR=1 A=58 W=1860s QA=11h11m28s
.RS 3em
\fCThreads: 11 Msgs: 36 Procs: 23 Idle: 12 Plim:90 Flim: 150 Tlim: 1
.RE
.RE
\fCKids: 414 Idle: 324 Msgs: 754 Thrds: 129 Rcpnts: 943 Uptime: 1d31m22s
\fCMsgs in 5384 out 4630 stored 754 Rcpnts in 441890 out 440917 stored 971\fR
.fi
.PP
The codes mean following:
.IP \fBR=\fR
Number of
.B messages
on this  ``channel/host''  thread; this does
.B not
count individual target users separately!
(e.g. if there are a dozen recipients at some message, but they are
at same host, they are counted as one.)
.IP \fBA=\fR
Count of
.IR A ttempts
to do delivery at this thread.
.IP \fBP=\fR
.IR P rocess
number(s) of the transport agent actively handling this thread.
\fIThere can be multiple processes, and they are listed comma-separated
inside the curly brackets.\fR  Similarly for the rest of the things below.
.IP \fBW=\fR
Delay time until next time the transport-agent may try to send this
thread.
.RI ( W ait)
.IP \fBHA=\fR
.RI ``# H unger A ge(s)''
-- time since the scheduler saw last ``#hungry'' message from
the transport agent.
.IP \fBFA=\fR
``\fIF\fReed \fIA\fRge(s)''
-- time since the scheduler did last time feed something to
the transport agent(s).
.IP \fBOF=\fR
.RI `` O ver F eed
count'' -- how many unacknowledged tasks are still in the transport agent(s)
for this thread.  The ``OverFeed'' was created to handle sluggish scheduler
in hard pressed system to get jobs scheduled around, when the transport
agents were in practice running dry as they did their jobs fast, but the
scheduler didn't get around to feed them...
Thus the way for the scheduler to ``overfeed'' as many of the jobs in
active thread to the transport agent as possible, and then just wait
them to complete, and be acknowledged.
With this a lot more gets done even with a sluggish scheduler.
.IP \fBS=\fR
.RI Feed- S tate
of TA-process(es) doing actual job.  The scheme goes like following:
.RS
.IP LARVA
(This is very fast transient state.)
TA processes are created at this state, and they stay there only until
the first ``#hungry'' message is heard, then
.I one
job if fed there, and state is changed to ``STUFFing.''
(One job so that if it fails, TA process kicks to other thread.)
.IP STUFFing
This is normal lifetime state of a TA process.
When process' 
.I UF=
count goes to zero, more jobs are fed to it.
A process moves away from this state by either:
.RS
.IP "Getting a \fR#retryat \fImessage"
Next state is FINISHing.
.IP "Running out of jobs to feed"
Next state is FINISHing -- this requires that no messages were
available for feeding at the time.  If even single one is fed,
state stays in STUFFing.
.RE
.IP FINISHing
This waits for the
.I OF=
count to go to zero, and then it tries to pick a new thread for
the process to work on (if available), or if none can be found,
moves the process to IDLE state.
If a new thread is found for processing, process moves there,
and goes to STUFFing state.
.IP IDLE
(This is very fast transient state.)
The TA process is being idled, next state for the process will
be in thread-group idle-pool.
.RE
.IP \fBUF=\fR
How many messages out of all present in the queue have not yet been
fed to the current TA process set ?
("\fIU\fRn\fIF\fRed count")
.IP \fBQA=\fR
Age of oldest message in the queue at this thread.
("\fIQ\fRueue\fIA\fRge")
.PP
.SH FILES
.PP
.TS
l l.
\fI/opt/mail/zmailer.conf\fR	(ZCONFIG)
\fI/var/spool/postoffice/transport\fR	(POSTOFFICE/transport)
\fI/var/spool/postoffice/queue\fR	(POSTOFFICE/queue)
.TE
.PP
.SH SEE ALSO
The \fBMAILQ-V2\fR protocol is described at the
.IR scheduler (8zm)
manual page.
.PP
.IR mailq-m (5zm),
.IR zmailer (1zm),
.IR router (8zm),
.IR scheduler (8zm),
.IR "ZMailer::mailq" (3pm),
.IR zmailer.conf (5zm).
.PP
.SH AUTHOR
This program authored and copyright by:
.RS 3em
Rayan Zachariassen <no address>
.RE
Partial rewrite for ZMailer 2.99/3.0 by:
.RS 3em
Matti Aarnio <mea@nic.funet.fi>
.RE