MAILQ(1zm)                                                          MAILQ(1zm)



NAME
       mailq - zmailer mail queue printer

SYNOPSIS
       mailq [-4|-6]  [-d]  [-i]  [-M]  [-p port_or_socket_path]  [-s[s]] [-t]
             [-u user]  [-U username/password]  [-v[v]]   [-S]   [-Q[Q[Q[Q]]]]
             [-Z zenvfile]]] [[-c channel] -h host] [host]

       FIXME: Not all options are documented!

DESCRIPTION
       The  mailq(1zm) queries a running 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 scheduler(8zm)
       process queried is the one relevant to the local host,  i.e.  either  a
       local  process  or  a  scheduler(8zm)  on  a  mail server host.  If the
       optional host argument is specified, the scheduler(8zm) running on that
       host will be queried instead.

       If  the  scheduler(8zm) has used -Q option to shrink the amount of out-
       put, the mailq(1zm) must also use -Q option to report about  the  queue
       status at the server in ``queue-summary'' format.

       The information printed for each queued message is labelled by its mes-
       sage file id, which is the name of the original  message  file  in  the
       POSTOFFICE/queue  directory  and  of  the  message  control file in the
       POSTOFFICE/transport directory.  The information may be  different  for
       different  channel/host combinations in destination addresses in a sin-
       gle message, so the status information is grouped in clusters  labelled
       by the channel and host for addresses in the group.

       The text associated with a particular deferred destination in a message
       originates in a transport agent.  The scheduler annotates the transport
       agent  messages  with retry information when an address has been sched-
       uled 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.

OPTIONS
       The normal action is to print the transport queue.

       -c channel -h host
              in MAILQv2 mode (see scheduler(8zm)) query  details  about  only
              those messages destined at given channel and host.

              The default for channel is "smtp".

       -d     This  prints  the information received from the scheduler as is.
              This will override the verbose option.  This is debugging  mode.

       -i
              prints  a  verbose  transport queue output (see the -v flag) for
              your own messages only.

       -M
              Attached to an MTA instance  wide  shared  memory  segment,  and
              dumpts its content (various counters and gauges).

              This works only local in the system, unlike MAILQ-v2 queries!

              Listed variables are described at: mailq-m(5zm).

       -p port
              specifies  an  alternate  TCP/IP  port  to  connect  to a sched-
              uler(8zm) at.

       -Q
              Shows full thread-wise status of scheduler's internal state.

       -QQ
              Produces abbreviated summary of scheduler's internal state.

       -QQQ
              Shows only scheduler's summary statistics lines.

       -QQQQ
              Shows same dump as "mailq -M" produces, but can do it  over  the
              network.

              Listed variables are described at: mailq-m(5zm).

       -s
              asks for a status of the router(8zm), scheduler(8zm), and trans-
              port queues.

              The first two are determined by scanning the appropriate  direc-
              tories  and  counting files, whereas the status of the transport
              queue is retrieved from the running scheduler(8zm) process.

              Doubling this option will cause mailq(1zm) to exit after  print-
              ing this summary.

       -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.

       -t     disables  any previous verbose flags to produce the normal terse
              output.

       -u user
              selects messages sent by the specified user id.

              This option is usually only useful to the Postmaster on the sys-
              tem.

       -U username/password
              Defines  username/password pair for MAILQ-V2 mode connection, in
              case the default "nobody"/"nobody" is not proper.

              Do note: The "/" separates fields!

       -v[v]
              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.

              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 mailq  can  read  the  message  control
              files  in  the postoffice.  Most users can only see the data for
              their own messages.

       -Z zenvfile
              :RS passes on explicite non-compiled-in-default located  ZCONFIG
              environment file.


mailq -Q output codes
       Examples of ``mailq -Q'' output:

       smtp/*.com/0
          smtp/aol.com/0  R=1 A=147 P={19598} HA={571}s FA={571}s OF=1 S={STUFF} UF=0 QA=1d18h
          smtp/some.com/0 R=1 A=58 W=1860s QA=11h11m28s
             Threads: 11 Msgs: 36 Procs: 23 Idle: 12 Plim:90 Flim: 150 Tlim: 1
       Kids: 414 Idle: 324 Msgs: 754 Thrds: 129 Rcpnts: 943 Uptime: 1d31m22s
       Msgs in 5384 out 4630 stored 754 Rcpnts in 441890 out 440917 stored 971

       The codes mean following:

       R=     Number  of messages on this  ``channel/host''  thread; this does
              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.)

       A=     Count of Attempts to do delivery at this thread.

       P=     Process number(s) of the transport agent actively handling  this
              thread.   There  can  be multiple processes, and they are listed
              comma-separated inside the curly brackets.   Similarly  for  the
              rest of the things below.

       W=     Delay  time  until next time the transport-agent may try to send
              this thread.  (Wait)

       HA=    ``#HungerAge(s)'' -- time since the scheduler saw  last  ``#hun-
              gry'' message from the transport agent.

       FA=    ``Feed  Age(s)''  -- time since the scheduler did last time feed
              something to the transport agent(s).

       OF=    ``OverFeed 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 sched-
              uler  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.

       S=     Feed-State  of TA-process(es) doing actual job.  The scheme goes
              like following:

              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 one job  if  fed
                     there, and state is changed to ``STUFFing.''  (One job so
                     that if it fails, TA process kicks to other thread.)

              STUFFing
                     This is normal lifetime state of a TA process.  When pro-
                     cess' UF= count goes to zero, more jobs are fed to it.  A
                     process moves away from this state by either:

                     Getting a #retryat message
                             Next state is FINISHing.

                     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  STUFF-
                             ing.

              FINISHing
                     This  waits  for the 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.

              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.

       UF=    How  many  messages out of all present in the queue have not yet
              been fed to the current TA process set ?  ("UnFed count")

       QA=    Age of oldest message in the queue at this thread.  ("QueueAge")


FILES
       /opt/mail/zmailer.conf            (ZCONFIG)
       /var/spool/postoffice/transport   (POSTOFFICE/transport)
       /var/spool/postoffice/queue       (POSTOFFICE/queue)


SEE ALSO
       The MAILQ-V2 protocol is described at the scheduler(8zm) manual page.

       mailq-m(5zm),      zmailer(1zm),      router(8zm),      scheduler(8zm),
       ZMailer::mailq(3pm), zmailer.conf(5zm).


AUTHOR
       This program authored and copyright by:
          Rayan Zachariassen <no address>
       Partial rewrite for ZMailer 2.99/3.0 by:
          Matti Aarnio <mea@nic.funet.fi>



                                  2003-Aug-28                       MAILQ(1zm)