Understanding the qmailctl Script

---

The qmailctl script provides a simple, consistent interface for controlling and monitoring a qmail installation. The qmailctl script is created and installed during the qmail installation process described in Chapter 2, "Installing qmail." In general, it won't work on qmail installations done using other instructions or methods such as Red Hat Package Manager bundles (RPMs) or Berkeley Software Distribution (BSD) ports—although it can easily be adapted to other installations based on daemontools/ucspi-tcp.

Although many qmail administrators find the script convenient, its use is completely optional.

Using the qmailctl Script

The qmailctl script was designed to serve two purposes: It's compatible with the System V init.d startup/shutdown scripts used to start and stop services according to system run level, and it's an interactive interface for manually controlling and monitoring qmail on both System Vand BSD-style systems.

System V init.d Script

As a System V init.d startup/shutdown script, qmailctl is symbolically linked into one or more rcN.d directories, where N specifies a run level from 0 (zero) to 6 (six). The name of the link starts with K if qmail is to be stopped (killed) when entering that run level or S if qmail is to be started. Following the K or S is a twodigit number that indicates the order in which the various scripts in rcN.d are to be run, from lowest to highest. Following the two-digit number is the name of the service, qmail. For example, a qmail installation might have the following symbolic links to qmailctl:

 /etc/rc0.d/K30qmail /etc/rc1.d/K30qmail /etc/rc2.d/S80qmail /etc/rc3.d/S80qmail /etc/rc4.d/S80qmail /etc/rc5.d/S80qmail /etc/rc6.d/K30qmail 

When the init.d mechanism runs these scripts, it passes them a start argument if the link starts with S or a stop argument if it starts with K.

Note 

The location of the directory that contains the rcN.d directories varies across operating systems. Consult your system documentation for information about where it stores them.

Interactive Interface

As an interactive control and monitoring interface, qmailctl is run with an optional argument specifying the function to be performed. For example, when run with no arguments, it prints a concise usage statement:

 # qmailctl Usage: /usr/local/sbin/qmailctl {start|stop|restart|doqueue|flush|reload|stat| pause|cont|cdb|queue|help} # 

To execute the help function, which prints a quick description of each function, you do this:

 # qmailctl help    stop -- stops mail service (smtp connections refused, nothing goes out)   start -- starts mail service (smtp connection accepted, mail can go out)   pause -- temporarily stops mail service (connections accepted, nothing leaves)    cont -- continues paused mail service    stat -- displays status of mail service     cdb -- rebuild the tcpserver cdb file for smtp restart -- stops and restarts smtp, sends qmail-send a TERM & restarts it doqueue -- sends qmail-send ALRM, scheduling queued messages for delivery  reload -- sends qmail-send HUP, rereading locals and virtualdomains   queue -- shows status of queue    alrm -- same as doqueue   flush -- same as doqueue     hup -- same as reload # 

These functions are described in the following sections.

Note 

Most of the functions performed by qmailctl require root privilege. Running qmailctl as a normal user won't work, but it won't do any harm either.

start

This tells the supervise processes associated with the qmail-send and qmail-smtpd services to start them. Once started, qmail-send will process the queue, and messages will be delivered locally and remotely. Once started, qmail-smtpd will accept connections on the Simple Mail Transfer Protocol (SMTP) port and messages will be accepted or rejected.

This is an example:

 # qmailctl start Starting qmail # 

stop

This tells the supervise processes associated with the qmail-send and qmail- smtpd services to stop them. While qmail-send is stopped, no messages will be delivered locally or remotely, and messages queued by qmail-inject will remain unprocessed. While qmail-smtpd is stopped, connections to the SMTP port will be refused.

This is an example:

 # qmailctl stop Stopping qmail. . .   qmail-smtpd   qmail-send # 

restart

This temporarily takes the qmail-smtpd down while it restarts the qmail-send service. Restarting qmail-send causes it to reread all of its control files. This is necessary when changing any qmail-send control files except /var/qmail/control/locals and /var/qmail/control/virtualdomains.

This is an example:

 # qmailctl restart Restarting qmail: * Stopping qmail-smtpd. * Sending qmail-send SIGTERM and restarting. * Restarting qmail-smtpd. # 

doqueue, alrm, flush

This sends qmail-send an ALRM signal, causing it to schedule all queued mail for an immediate delivery attempt.

This is an example:

 # qmailctl flush Sending ALRM signal to qmail-send. # 

Note that this will not reschedule messages queued to hosts that have been recently unreachable. The qmail-tcpok command (see the "Learning qmail's Management Commands" section later in this chapter) can be used to make qmail forget which hosts are unreachable.

reload, hup

This sends qmail-send a HUP signal, causing it to reread /var/qmail/control/locals and /var/qmail/control/virtualdomains.

This is an example:

 # qmailctl reload Sending HUP signal to qmail-send. # 

stat

This runs svstat on the qmail-send and qmail-smtpd services and their logging subservices. It runs the qmail-qstat command to print a summary of the current state of the queue.

This is an example:

 # qmailctl stat /service/qmail-send: up (pid 8310) 699 seconds /service/qmail-send/log: up (pid 862) 91020 seconds /service/qmail-smtpd: up (pid 8318) 699 seconds /service/qmail-smtpd/log: up (pid 861) 91020 seconds messages in queue: 0 messages in queue but not yet preprocessed: 0 # 

pause

This sends the qmail-send and qmail-smtpd services a STOP signal, causing them to immediately stop functioning. The cont function can be used to reactivate them. While qmail-send is paused, no messages will be delivered locally or remotely. While qmail-smtpd is paused, connections to the SMTP port will be accepted but no dialogue will take place.

This is an example:

 # qmailctl pause Pausing qmail-send Pausing qmail-smtpd # qmailctl stat /service/qmail-send: up (pid 8310) 770 seconds, paused /service/qmail-send/log: up (pid 862) 91091 seconds /service/qmail-smtpd: up (pid 8318) 770 seconds, paused /service/qmail-smtpd/log: up (pid 861) 91091 seconds messages in queue: 0 messages in queue but not yet preprocessed: 0 # 

cont

This sends the qmail-send and qmail-smtpd services a CONT signal, causing them to immediately resume functioning if they previously paused by the pause function.

This is an example:

 # qmailctl cont Continuing qmail-send Continuing qmail-smtpd # qmailctl stat /service/qmail-send: up (pid 8310) 852 seconds /service/qmail-send/log: up (pid 862) 91173 seconds /service/qmail-smtpd: up (pid 8318) 852 seconds /service/qmail-smtpd/log: up (pid 861) 91173 seconds messages in queue: 0 messages in queue but not yet preprocessed: 0 # 

cdb

This rebuilds the binary SMTP access control database, /etc/tcp.smtp.cdb, from the text database, /etc/tcp.smtp, using the tcprules command from ucspi-tcp.

This is an example:

 # qmailctl cdb Reloaded /etc/tcp.smtp. # 

queue

This runs the qmail-qstat command to print a summary of the state of the queue and the qmail-qread command to print the status of each message in the queue.

This is an example:

 # qmailctl queue messages in queue: 1 messages in queue but not yet preprocessed: 0 21 Jul 2001 19:55:31 GMT  #93883  1532  <[e-mail]>          remote  [e-mail] # 

help

This displays a summary of the functions provided by the qmailctl script. (See the previous example.)

Logging

The qmailctl script keeps a log that shows when it was run, from which terminal it was run, and which function was executed. The log contains output from key commands that might be useful for troubleshooting.

This is an example:

 Sun Jun 17 07:46:59 EDT 2001 /dev/console start Sun Jun 17 13:09:30 EDT 2001 /dev/pts/0 cdb Sun Jun 17 13:10:36 EDT 2001 /dev/pts/0 cdb Sun Jun 17 13:15:43 EDT 2001 /dev/pts/0 cdb Thu Jun 21 10:24:37 EDT 2001 /dev/pts/0 hup Thu Jun 21 14:49:31 EDT 2001 /dev/console stop 

This log shows that qmailctl start was run on the console on June 17 when the system was booted. Then qmailctl cdb and qmailctl hup were run from a pseudo teletype (TTY), probably by the mail administrator. Finally, qmailctl stop was run on June 21 when the system was shut down.

---