Learning qmail s Management Commands

 < Free Open Study > 



Learning qmail's Management Commands

In addition to the user utilities described in Chapter 4, "Using qmail," qmail includes commands for the mail administrator or that implement part of the system's core functionality.

qmail-clean

Usage: qmail-clean

Description: qmail-clean reads cleanup commands from descriptor 0 (zero), does the clean up, and reports the results to descriptor 1 (one).

qmail-clean is started by qmail-start (see the "qmail-start" section) and receives commands from qmail-send.

Caveats: You should never run qmail-clean manually. If qmail is running, qmail-clean is running and doing its job. If you want to forcibly empty the queue, see the "Managing the Queue" section later in this chapter.

qmail-getpw

Usage: qmail-getpw local

Description: qmail-getpw is called by qmail-lspawn to determine which user is responsible for mail sent to the local address local. It returns six pieces of information:

  • Username—the name of local user that controls local

  • UID—the user ID associated with the user

  • GID—the group ID associated with the user

  • Home directory—the user's home directory

  • Dash—contains a dash (hyphen) if local contains an extension, for example, ken-dojo

  • Extension—contains the extension (everything after the dash) if local contains one

An ASCII NUL character terminates each field in the output.

qmail-getpw uses the operating system's getpwnam function to look up the user in /etc/passwd, the Unix user database. qmail-getpw requires several criteria of accounts listed in /etc/passwd before considering them to be valid mail accounts:

  • The UID must not be zero.

  • The home directory must exist and be visible to qmail-getpw.

  • The user must own their home directory.

  • The username must not contain uppercase letters.

  • The username must be thirty-one characters or less.

If no valid, matching user is found, qmail-getpw assigns the address to alias, the qmail pseudo-user responsible for system aliases. When it does this, the "dash" field is set to - and the extension is set to local. For example, if local is isshinryu and there's no entry in /etc/passwd for isshinryu, qmail-getpw's output looks as if local was originally alias-isshinryu.

Caveats: qmail-getpw relies on the getpwnam function, which is somewhat unreliable because it doesn't distinguish between temporary lookup failures and nonexistent users. The qmail-users mechanism, described in Chapter 3, can be used to override qmail-getpw.

Examples: On a system with a local user named cleteth that meets the previous requirements:

 $ /var/qmail/bin/qmail-getpw cleteth | od -c 0000000   c   l    e   t   e   t    h  \0   5   0   3  \0   5    0    3   \0 0000020   /   h    o   m   e   /    c   l   e   t   e   t   h   \0   \0   \0 0000040 $ 

In this example, the output of qmail-getpw is passed through od to make the NUL field terminators visible. In this case, the username returned is cleteth, the UID is 503, the GID is 503, the home directory is /home/cleteth, and "dash" and the extension are null.

On the same system, adding an extension to the local address yields:

 $ /var/qmail/bin/qmail-getpw cleteth-dojo | od -c 0000000   c   l    e   t   e   t    h  \0   5   0   3   \0   5    0   3   \0 0000020   /   h    o   m   e   /    c   l   e   t   e    t   h   \0   -   \0 0000040   d   o    j   o  \0 0000045 $ 

The results are similar to the previous example, except that "dash" is set to - and the extension is dojo.

Finally, on the same system, which doesn't contain a valid isshinryu account:

 $ /var/qmail/bin/qmail-getpw isshinryu | tr '\0' '\n' alias 49492 31314 /var/qmail/alias - isshinryu $ 

This time, tr is used to turn the NULs into newlines. The username is alias, the UID is 49492, the GID is 31314 (nofiles), the home directory is /var/qmail/alias, "dash" is -, and the extension is isshinryu—which is exactly the same result that qmail-getpw alias-isshinryu would give.

qmail-local

Usage: qmail-local [-nN] user homedir local dash ext domain sender defaultdelivery

Description: qmail-local reads a mail message on standard input and delivers it to user. qmail-local is usually run by qmail-lspawn. The -n option causes qmail-local to print a description of the delivery instructions instead of actually delivering the message. The -N option, which is the default, causes the message to be delivered.

The command-line arguments are

  • user: the username of the user to whom the message is being delivered.

  • homedir: the absolute path of the directory in which qmail-local will look for .qmail files—usually user's home directory.

  • local: the "local" part (the part before the "@") of the envelope recipient address.

  • dash: the "dash" part of the .qmaildashext file receiving messages for local. Usually either - if local has an extension or empty if it doesn't.

  • ext: the "ext" part of the .qmaildashext file receiving messages for local. Usually either contains the extension if local has one or empty if it doesn't.

  • domain: the "domain" part (the part after the @) of the envelope recipient address.

  • sender: the envelope sender, or envelope return path.

  • defaultdelivery: the default delivery instructions supplied to qmail-start for deliveries to addresses without specific instructions in a .qmail file.

Before delivering the message, qmail-local constructs a Delivered-To header field containing local@domain. If the message already contains a Delivered-To field with the same contents, the message is assumed to be looping and a bounce message is generated.

A Return-Path header field is constructed from sender.

If dash is empty, qmail-local treats a missing .qmaildashext file the same way it treats an empty dot-qmail file: it uses the instructions in defaultdelivery.

Caveats: The standard input for qmail-local must be a "seekable" file—not a pipe, socket, or fifo—so qmail-local can read it more than once.

qmail-local requires access to homedir and any relevant .qmail files in order to run with the -n option. Only root can run qmail-local without the -n option because qmail-local sets its UID to user.

Example: A user uses the -n option to test the deliverability of a message to a local address:

 # /var/qmail/bin/qmail-local -n cleteth /home/cleteth cleteth "" "" \ > example.com root@example.com ./Maildir/ maildir ./Maildir/ did 1+0+0 # 

The output verifies that mail to local user cleteth would be delivered to the maildir mailbox /home/cleteth/Maildir.

A similar test to an extension address, where no matching dot-qmail file exists, gives an error:

 # /var/qmail/bin/qmail-local -n cleteth /home/cleteth cleteth-dojo - \ > dojo example.com root@example.com ./Maildir/ Sorry, no mailbox here by that name. (#5.1.1) # 

qmail-lspawn

Usage: qmail-lspawn defaultdelivery

Description: qmail-lspawn reads delivery instructions from descriptor 0 (zero), invokes qmail-local to perform the deliveries, and reports the status of the deliveries to descriptor 1 (one). The defaultdelivery argument is passed to qmail-local.

Before invoking qmail-local, qmail-lspawn determines the local user that controls the address by first checking the qmail-users mechanism (/var/qmail/users/cdb, see Chapter 3) then, if that fails, by calling qmail-getpw.

After determining the controlling user, qmail-lspawn runs qmail-local with that user's UID and primary GID. Supplemental groups to which the user belongs are not included or set up.

qmail-lspawn is started by qmail-start (see the "qmail-start" section) and receives commands from qmail-send.

Caveats: You should never run qmail-lspawn manually. If qmail is running, qmail-lspawn is running and doing its job.

qmail-newmrh

Usage: qmail-newmrh

Description: qmail-newmrh reads /var/qmail/control/morercpthosts (see Chapter 3) and creates a new /var/qmail/control/morercpthosts.cdb.

qmail-newmrh updates morercpthosts "atomically"—the new one is built in a temporary file and moved into place when it's complete—so qmail-smtpd never has to wait for qmail-newmrh to finish, regardless of the size of morercpthosts.

Caveats: qmail-newmrh does not implement locking to prevent multiple simultaneous attempts to update morercpthosts.cdb.

Example: On a system hosting a large number of virtual domains, the mail administrator has implemented morercpthosts. To add a new virtual domain, stout.example.com to morercpthosts.cdb, she does the following:

 # echo stout.example.com >> /var/qmail/control/morercpthosts # /var/qmail/bin/qmail-newmrh # 

qmail-newu

Usage: qmail-newu

Description: qmail-newu reads /var/qmail/users/assign (see Chapter 3) and creates a new /var/qmail/control/users/cdb.

qmail-newu updates cdb "atomically"—the new one is built in a temporary file and moved into place when it's complete—so qmail-lspawn never has to wait for qmail-newu to finish, regardless of the size of assign.

Caveats: qmail-newu does not implement locking to prevent multiple simultaneous attempts to update cdb.

Example: On a system using the qmail-users mechanism, the mail administrator has updated users/assign. To create a new users/cdb, she does the following:

 # /var/qmail/bin/qmail-newu # 

qmail-pop3d

Usage: qmail-pop3d maildir

Description: qmail-pop3d accepts Post Office Protocol, version 3 (POP3, see http://www.ietf.org/rfc/rfc1939.txt) commands on standard input, accesses maildir as necessary, and sends the POP3 response to standard output.

qmail-pop3d supports the optional POP3 commands UIDL, TOP, and LAST.

qmail-pop3d is normally run by qmail-popup. Instructions for installing qmail-pop3d are provided in Chapter 10, "Serving Mailboxes."

Caveats: Idle sessions are terminated after 20 minutes.

A blank line is appended to every message returned by qmail-pop3d as a workaround for bugs in some POP3 clients.

Example: To verify that qmail-pop3d is functioning, or to experiment with the POP3 protocol, qmail-pop3d can be run interactively:

 $ /var/qmail/bin/qmail-pop3d $HOME/Maildir/ +OK list +OK 1 2667 2 2399 3 17690 . quit +OK $ 

In this example, the user used qmail-pop3d to access his main mailbox. The list command shows there are three messages in the mailbox and displays the size of each.

qmail-popup

Usage: qmail-popup hostname subprogram [args]

Description: qmail-popup reads authentication information from standard input using the POP3 protocol, then invokes subprogram, passing the authentication information on descriptor 3. qmail-popup waits for subprogram to finish and prints an error message if subprogram exits with a non-zero status.

qmail-popup supports both USER/PASS and APOP authentication.

Subprogram is normally Dan Bernstein's checkpassword or one of the variants available from http://www.qmail.org/.

See Chapter 10, "Serving Mailboxes," for installation instructions.

Caveats: Idle sessions are terminated after 20 minutes.

POP3 should only be used on secure networks. USER/PASS authentication passes reusable passwords over the network unencrypted. Even APOP sessions, in which the password is not passed over the network, are susceptible to being "hijacked" by an attacker.

Example: To verify that authentication using checkpassword is working correctly, qmail-popup can be run interactively:

 # /var/qmail/bin/qmail-popup example.com /bin/checkpassword /bin/echo valid pw +OK <17668.990972413@example.com> user elaina +OK pass wrongpass -ERR authorization failed # /var/qmail/bin/qmail-popup example.com /bin/checkpassword /bin/echo valid pw +OK <17671.990972454@example.com> user elaina +OK pass rightpass valid pw # 

qmail-pw2u

Usage: qmail-pw2u [-/ohHuUC] [-cchar]

Description: qmail-pw2u reads /etc/passwd entries (see man 5 passwd) on standard input and generates a qmail-users assign file on standard output. By default, qmail-pw2u uses the same rules as qmail-getpw to determine valid mail users.

For each valid user, qmail-pw2u generates two assign entries:

 =user:user:UID:GID:/home/user::: +user-:user:UID:GID:/home/user:-:: 

A catchall wildcard entry is also generated so system aliases will still work:

 +:alias:UID:GID:/var/qmail/alias:-:: 

A final line consisting of a single dot (.) is also included, as qmail-newu requires.

Table 5-1 describes qmail-pw2u's options.

Table 5-1: qmail-pw2u Options

OPTION

MEANING

/

Use homedir/.qmail-/ext instead of homedir/.qmail-ext

o (default)

Skip user if homedir does not exist, is not owned by user, or is not visible to qmail-pw2u

h

Stop if homedir does not exist. Skip user if user does not own homedir

H

Do not check the existence or ownership of homedir

u

Allow uppercase letters in user

U (default)

Skip user if there are any uppercase letters in user

C

Disable the user-extension mechanism

cchar

Use char as the user-extension delimiter in place of -

Control Files: qmail-pw2u uses the following optional files to add to or remove from the output generated:

     include 

A list of users to be included from the file generated. If include exists and user is not listed in include, user is ignored.

     exclude 

A list of users to be excluded from the file generated. If exclude exists and user is listed in exclude, user is ignored.

Tip 

You probably don't want to use both include and exclude. Decide whether you want new users to be allowed or denied mail accounts by default and choose accordingly.

     mailnames 

A list of alternative names for users. Each line has the form

 user:mailname1:mailname2:... 

The addresses mailname1, mailname1-ext, mailname2, and so on will be delivered to user.

Caution 

The addresses user and user-ext will not be delivered to user unless user is listed as one of the mailnames.

For example, with the mailnames entry:

 scott:scott.miller:asmiller:smiller 

Mail to scott.miller, asmiller, and smiller will be delivered to user scott, but mail to scott will not.

Lines in mailnames are silently ignored if user doesn't exist.

     subusers 

A list of "subusers"—extra addresses handled by a user. Each line has the form

 sub:user:pre: 

The address sub will be handled by homedir/.qmail-pre, where homedir is user's home directory, and the address sub-ext will be handled by homedir/.qmail-pre-ext.

For example, with the following entry in subusers, user bill receives mail for cleteth via $HOME/.qmail-cleteth and mail for cleteth-dojo via $HOME/qmail-cleteth-dojo or $HOME/.qmail-cleteth-default:

 cleteth:bill:cleteth:     append 

A list of miscellaneous assignments in assign format (see Chapter 3, "Configuring qmail: The Basics") printed at the end of qmail-pw2u's output.

Caveats: If you're using qmail-users, after changing any usernames, UIDs, GIDs, or home directories in /etc/passwd, you must rerun qmail-pw2u and qmail-newu if you want qmail-lspawn to see the changes.

Example: To generate an assign equivalent to the default qmail-getpw behavior and build cdb from the new assign file, do this:

 # /var/qmail/bin/qmail-pw2u < /etc/passwd > /var/qmail/users/assign # /var/qmail/bin/qmail-newu # 

If you did that and noticed that some of the users in assign are not valid mail users, you could add them to exclude, regenerate assign, and rebuild cdb:

 # echo pcguest >> /var/qmail/users/exclude # echo xfs >> /var/qmail/users/exclude # /var/qmail/bin/qmail-pw2u < /etc/passwd > /var/qmail/users/assign # /var/qmail/bin/qmail-newu # 

qmail-qmqpc

Usage: qmail-qmqpc

Description: qmail-qmqpc is a drop-in replacement for qmail-queue (see the "qmail-queue" section) that queues a message to a remote Quick Mail Queueing Protocol (QMQP) server (http://cr.yp.to/proto/qmqp.html).

In "mini-qmail" installations, qmail-queue is replaced with a symbolic link to qmail-qmqpc.

Control Files: qmail-qmqpc uses one configuration file, /var/qmail/control/qmqpservers, which is a list of Internet Protocol (IP) addresses of QMQP servers to which it will try, in order, to queue the message.

Caveats: If qmail-qmqpc is unable to successfully queue the message to one of the servers listed in qmqpservers, it will return an exit code indicating whether the failure is temporary or permanent, but the message will not be queued on the local system. The process injecting the message is responsible for reporting the failure.

qmail-qmqpd

Usage: qmail-qmqpd

Description: qmail-qmqpd receives messages via the QMQP and invokes qmail-queue to place them into the queue (http://cr.yp.to/proto/qmqp.html).

qmail-qmqpd is normally run under tcpserver from the ucspi-tcp package. Installation and configuration of QMQP clients and servers is covered in Chapter 7, "Configuring qmail: Advanced Options."

Caveats: QMQP is designed for use on private networks. qmail-qmqpd should be configured to accept connections only from authorized hosts because it will relay messages for any host that can connect.

qmail-qmtpd

Usage: qmail-qmtpd

Description: qmail-qmtpd receives messages via the QMTP and invokes qmail-queue to place them into the queue (http://cr.yp.to/proto/qmtp.txt).

qmail-qmtpd supports the rcpthosts, morercpthosts, and databytes control files (see Chapter 3), and the RELAYCLIENT and DATABYTES environment variables.

qmail-qmtpd is normally run under tcpserver from the ucspi-tcp package. Installation and configuration of QMTP clients and servers is covered in Chapter 7, "Configuring qmail: Advanced Options."

Caveats: None

qmail-qread

Usage: qmail-qread

Description: qmail-qread reports on the status of messages in the queue. For each message in the queue, qmail-qread prints:

  • The date and time at which the message entered the queue

  • The queue ID

  • The size of the message in bytes

  • The sender

  • The recipients, including those to whom the message has already been delivered

Caveats: qmail-qread requires read access to the queue so it must be run either as root or as qmails and with group ID qmail.

Example: To view the contents of the queue, the mail administrator runs qmail-qread:

 # /var/qmail/bin/qmail-qread 26 May 2001 22:44:06 GMT   #93881   1112   <rachel@example.org>          remote  jessica@example.com   done  remote  samantha@example.net   done  remote  erica@example.org          remote  james@example.com # 

qmail-qread reports that there is one message in the queue, from rachel@example.org to four recipients, two of which have already been delivered.

qmail-qstat

Usage: qmail-qstat

Description: qmail-qstat prints a summary of the contents of the queue. It shows both the total number of messages in the queue and the number of messages in the queue that haven't been preprocessed by qmail-send.

Caveats: qmail-qstat requires read access to the queue so it must be run either as root or as qmails and with group ID qmail.

Example: To view a summary of the queue, the mail administrator runs qmail-qstat:

 # /var/qmail/bin/qmail-qstat messages in queue: 2 messages in queue but not yet preprocessed: 0 # 

qmail-qstat reports that there are two messages in the queue, both of which have been preprocessed.

qmail-remote

Usage: qmail-remote host sender recip [recip . . .]

Description: qmail-remote reads a message from standard input and delivers it via SMTP to host with the envelope sender set to sender and recipients set to recip.

qmail-remote reports results to standard output for the message and for the individual recipients. Recipient reports are one letter and are printed in the order of the recip arguments. Following the recipient reports is the message report. Each report is a single character.

Table 5-2 lists the report codes used by qmail-remote.

Table 5-2: qmail-remote Report Codes

CODE

TYPE

MEANING

r

Recipient

Host accepted recipient.

h

Recipient

Host permanently rejected recipient.

s

Recipient

Host temporarily rejected recipient.

K

Message

Host accepts responsibility for delivering message to all accepted recipients.

Z

Message

Temporary failure

D

Message

Permanent failure

Following the recipient and message reports, qmail-remote prints a human-readable description of what happened.

Host may be specified as a fully qualified domain name, for example, mail.example.com, or as an IP address enclosed in square brackets, for example, [192.168.1.5].

Control Files: qmail-remote uses four configuration files, usually in /var/qmail/control: helohost, smtproutes, timeoutconnect, and timeoutremote. These files are covered in Chapter 3, "Configuring qmail: The Basics."

Caveats: qmail-remote does not enforce SMTP restrictions on line length or non-ASCII characters.

qmail-remote does not queue messages that temporarily fail. In normal use, qmail-remote is called indirectly by qmail-send after the message has been queued. If you call qmail-remote directly, you're responsible for queuing it, if it's necessary.

Example: To send a message, a user creates a file called msg containing the message and invokes qmail-remote to send it:

 $ cat msg From: bill@example.com To: ken@example.net, elaina@example.net Subject: No class tonight Cancelled due to the weather. $ /var/qmail/bin/qmail-remote mail.example.net bill@example.com ken@example.net elaina@example.net < msg rrK192.168.1.4 accepted message. Remote host said: 250 ok 991052072 qp 20788 $ 

The recipient report codes were both r and the message report code was K, so the message was successfully delivered to mail.example.com. The human-readable description confirms this and includes the remote system's response, which includes information potentially useful in tracking delivery problems.

qmail-rspawn

Usage: qmail-rspawn

Description: qmail-rspawn reads remote delivery commands from descriptor 0 (zero), invokes qmail-remote to perform the deliveries, and reports the results to descriptor 1 (one).

qmail-rspawn is started by qmail-start (see the "qmail-start" section) and receives commands from qmail-send.

Caveats: You should never run qmail-rspawn manually. If qmail is running, qmail-rspawn is running and doing its job.

qmail-send

Usage: qmail-send

Description: qmail-send receives messages placed in the queue by qmail-queue and uses qmail-lspawn and qmail-rspawn to deliver them.

qmail-send is started by qmail-start (see the "qmail-start" section), which sets up the communication channels listed in Table 5-3.

Table 5-3: qmail-send Channels

DESCRIPTOR

IN/OUT

PURPOSE

0

Output

Activity log

1

Output

qmail-lspawn commands

2

Input

qmail-lspawn responses

3

Output

qmail-rspawn commands

4

Input

qmail-rspawn responses

5

Output

qmail-clean commands

6

Input

qmail-clean responses

Signals: Upon receiving a terminate (TERM) signal, qmail-send exits cleanly after waiting for active deliveries to complete.

Note 

If there are active connections to slow remote hosts, qmail-send may take minutes or hours to exit.You can manually kill the qmail-remote processes to speed the shutdown, but that could result in some duplicated messages.

An alarm (ALRM) signal causes qmail-send to schedule all messages in the queue for an immediate delivery attempt.

A hang up (HUP) signal causes qmail-send to reread the locals and virtualdomains control files.

The qmailctl script (see the "Understanding the qmailctl Script" section earlier in this chapter) facilitates sending these signals.

Control Files: qmail-send uses the following control files, usually in /var/qmail/control: bouncefrom, bouncehost, concurrencylocal, concurrencyremote, doublebouncehost, doublebounceto, envnoathost, locals, percenthack, queuelifetime, and virtualdomains.

See Chapter 3, "Configuring qmail: The Basics," for more information about these files.

Caveats: You should never run qmail-send manually. If qmail is running, qmail-send is running and doing its job.

With the exception of locals and virtualdomains, qmail-send only reads its control files at startup. Changing the other files requires restarting qmail-send before the changes will take effect.

qmail-showctl

Usage: qmail-showctl

Description: qmail-showctl displays the state of qmail's configuration through control files. For each known control file, qmail-showctl prints the current setting or default setting, if the control file doesn't exist. Nonstandard and misspelled control files are also listed.

The output of qmail-showctl is useful for debugging configuration problems—especially when seeking help from people without direct access to the control files, such as members of the qmail mailing list (see Chapter 1, "Introducing qmail," for more information).

Caveats: qmail-showctl requires read access to the control files and read and execute access on the control directory (usually /var/qmail/control).

Example: A mail administrator is debugging a qmail configuration problem. He starts by examining the output of qmail-showctl:

  1 # /var/qmail/bin/qmail-showctl  2 qmail home directory: /var/qmail.  3 user-ext delimiter: -.  4 paternalism (in decimal): 2.  5 silent concurrency limit: 120.  6 subdirectory split: 23.  7 user ids: 501, 502, 503, 0, 504, 505, 506, 507.  8 group ids: 501, 502.  9 10 badmailfrom: (Default.) Any MAIL FROM is allowed. 11 bouncefrom: (Default.) Bounce user name is MAILER-DAEMON. 12 bouncehost: (Default.) Bounce host name is dolphin.example.com. 13 concurrencylocal: (Default.) Local concurrency is 10. 14 concurrencyremote: (Default.) Remote concurrency is 20. 15 databytes: (Default.) SMTP DATA limit is 0 bytes. 16 defaultdomain: Default domain name is example.com. 17 defaulthost: (Default.) Default host name is dolphin.example.com. 18 doublebouncehost: (Default.) 2B recipient host: dolphin.example.com. 19 doublebounceto: (Default.) 2B recipient user: postmaster. 20 envnoathost: (Default.) Presumed domain name is dolphin.example.com. 21 helohost: (Default.) SMTP client HELO host name is dolphin.example.com. 22 idhost: (Default.) Message-ID host name is dolphin.example.com. 23 localiphost: (Default.) Local IP address becomes dolphin.example.com. 24 25 locals: 26 Messages for localhost are delivered locally. 27 Messages for dolphin.example.com are delivered locally. 28 29 me: My name is dolphin.example.com. 30 percenthack: (Default.) The percent hack is not allowed. 31 plusdomain: Plus domain name is example.com. 32 qmqpservers: (Default.) No QMQP servers. 33 queuelifetime: (Default.) Message lifetime in the queue is 604800 seconds. 34 35 rcpthosts: 36 SMTP clients may send messages to recipients at localhost. 37 SMTP clients may send messages to recipients at dolphin.example.com. 38 39 morercpthosts: (Default.) No effect. 40 morercpthosts.cdb: (Default.) No effect. 41 smtpgreeting: (Default.) SMTP greeting: 220 dolphin.example.com. 42 43 smtproutes: (Default.) No artificial SMTP routes. 44 timeoutconnect: (Default.) SMTP client connection timeout is 60 seconds. 45 timeoutremote: (Default.) SMTP client data timeout is 1200 seconds. 46 timeoutsmtpd: (Default.) SMTP server data timeout is 1200 seconds. 47 virtualdomains: (Default.) No virtual domains. 48 defaultdelivery: I have no idea what this file does. 49 concurrencyincoming: I have no idea what this file does. 50 # 

Lines 2 through 8 show the value of compile-time configuration settings. See Chapter 2 for more information about these settings.

Line 2 shows the value of conf-qmail, the qmail home directory.

Line 3 shows the value of conf-break, the character that separates usernames from extensions in extension addresses, for example, the - in maryjane-quilting.

Line 4 shows the value of conf-patrn, the set of stat() bits that are disallowed on user's home directories and dot-qmail files. In this case it's the default, 2, which indicates the world-writable bit, meaning that qmail will refuse to deliver mail to a user with a world-writable home directory or .qmail file.

Line 5 shows the value of conf-spawn, the built-in limit to the values of the run-time configuration settings concurrencylocal and concurrencyremote. If the mail administrator sets one of the concurrency settings above the conf-spawn limit, qmail will silently lower it to the value of conf-spawn.

Line 6 shows the value of conf-split, the number of subdirectories into which certain queue directories are divided, in order to reduce the number of files per directory for improved performance on very busy servers.

Line 7 shows the values in conf-users, the users used to run the various pieces of qmail. conf-users lists the usernames, but qmail-showctl shows their UIDs.

Line 8 shows the values in conf-groups, the groups used by the various pieces of qmail. conf-groups lists the group names, but qmail-showctl shows their GIDs.

The remaining output shows the value of the run-time configuration settings. See Chapter 3 for more information about these settings. For each setting, qmail-showctl prints the name of the setting, the value (or (Default) if there's no control file specifying a value), and a short description of the purpose of the setting. See the qmail-control man page for a pointer to the program that uses each control file.

At the end of the list, qmail-showctl lists unrecognized control files. In this case, it shows the nonstandard control files, defaultdelivery and concurrencyincoming, from the installation scripts in Chapter 2. It would also list any misspelled control files, like virtualdomain, so it's a good idea to check this after setting a new control.

qmail-smtpd

Usage: qmail-smtpd

Description: qmail-smtpd receives messages via the SMTP (see "Simple Mail Transfer Protocol" in Appendix C) and invokes qmail-queue to place them into the queue.

To break alias loops, qmail-smtpd rejects any message with more than 100 Received or Delivered-To header fields.

qmail-smtpd supports Extended SMTP (ESMTP), including the 8BITMIME and PIPELINING options (http://www.ietf.org/rfc/rfc1869.txt).

qmail-smtpd is normally run under tcpserver from the ucspi-tcp package

Control Files: qmail-smtpd uses the following control files, usually in /var/qmail/control: badmailfrom, databytes, localiphost, morercpthosts, rcpthosts, smtpgreeting, and timeoutsmtpd.

Caveats: qmail-smtpd accepts messages containing long lines and non-ASCII characters, even though such messages violate the SMTP protocol.

SMTP uses two-byte line breaks consisting of carriage return and line feed (CR-LF). qmail-smtpd converts CR-LF line breaks into the Unix-standard newline (LF only). If qmail-smtpd encounters a linefeed not prefixed with a carriage return in the body of a message (the SMTP DATA command), it immediately returns a temporary error to the SMTP client and closes the connection. qmail-smtpd refuses messages with bare newlines because they would be corrupted if forwarded via SMTP: The bare linefeed would be indistinguishable from a newline and would be converted to CR-LF on sending.

Example: To verify that qmail-smtpd is working properly, the mail administrator runs it interactively:

 # /var/qmail/bin/qmail-smtpd 220 dolphin.example.com ESMTP help 214 qmail home page: http://pobox.com/~djb/qmail.html quit 221 dolphin.example.com # 

Tip 

To talk to the local system via SMTP, it's better to telnet to the SMTP on the local host than to run qmail-smtpd interactively because telnet automatically converts LF line breaks to CR-LF. For example, try the command telnet 0 25.

qmail-start

Usage: qmail-start [defaultdelivery [logger args]]

Description: qmail-start starts the qmail daemons: qmail-send, qmail-lspawn, qmail-rspawn, and qmail-clean. It runs each daemon under the appropriate user ID and group ID, and sets up the communication channels between qmail-send and the other daemons.

qmail-start redirects qmail-send's output to its own standard output or, if logger is specified, it's run with the supplied args and receives qmail-send's output.

If defaultdelivery is provided, it's passed to qmail-lspawn.

Caveats: qmail-start passes its environment: variables, resource limits, controlling terminals, and so on to qmail-local. For this reason, it's usually run with a minimal environment using the env command.

Example: The /var/qmail/boot directory contains a set of example startup scripts using qmail-start. The /var/qmail/rc script from Chapter 2 is fairly typical:

 #!/bin/sh # Using stdout for logging # Using control/defaultdelivery from qmail-local to deliver messages by default exec env - PATH="/var/qmail/bin:$PATH" \ qmail-start "&grave;cat /var/qmail/control/defaultdelivery&grave;" 

The first line identifies the file as script to be run by /bin/sh. The exec command tells the shell to replace itself with the following command, which is an env command that sets up a minimal environment, adding /var/qmail/bin to PATH, before running qmail-start with the defaultdelivery argument set to the contents of /var/qmail/control/defaultdelivery. Because no logger is specified, qmail-send's output will go to standard output.

qmail-tcpok

Usage: qmail-tcpok

Description: qmail-tcpok clears qmail-remote's list of remote hosts to which recent connections have timed out.

qmail-remote will not attempt delivery to a host marked as timing out for at least an hour, but it will eventually retry all pending deliveries, so qmail-tcpok does not normally need to be run. qmail-tcpok is most useful in situations where many messages are being relayed to a system that the mail administrator knows is no longer unresponsive.

See also "qmail-tcpto" below.

Caveats: To update the list of timing-out hosts, qmail-tcpok must be run as root or as user qmailr with group qmail.

Example: The mail administrator of Example, Inc., sees that Example's main relay, mail.example.com is accumulating messages destined for exchange.example.com, which was down temporarily but is now back up. Rather than waiting up to an hour for qmail-remote to notice, he runs qmail-tcpok on mail.example.com to make it "forget" which remote hosts are timing out:

 # /var/qmail/bin/qmail-tcpok # 

qmail-tcpto

Usage: qmail-tcpto

Description: qmail-tcpto prints the list of remote SMTP servers to which connections have timed out within the past hour.

After an SMTP connection attempt times out, qmail-remote records the IP address of the remote host in /var/qmail/queue/lock/tcpto. If the same address fails again, after at least two minutes with no intervening successful connections, qmail-remote assumes that further attempts will fail for at least another hour.

Caveats: To read the list of timing-out hosts, qmail-tcpto must be run as root or as user qmailr with group qmail.

Example: To display the current time-out table, run qmail-tcpto:

 # /var/qmail/bin/qmail-tcpto 192.168.4.42 timed out 2564 seconds ago; # recent timeouts: 2 192.168.64.164 timed out 1269 seconds ago; # recent timeouts: 2 192.168.2.5 timed out 2624 seconds ago; # recent timeouts: 10 192.168.28.10 timed out 4126 seconds ago; # recent timeouts: 10 # 

splogger

Usage: splogger [tag [facility]]

Description : splogger reads messages on its standard input and sends them to syslogd, the system logging daemon. The tag, which defaults to splogger, is prepended to each line, as is a numeric timestamp. If the message begins with alert:, it's logged at priority LOG_ALERT. If it begins with warning:, it's logged at priority LOG_WARNING. All other messages are logged at priority LOG_INFO.

Tip 

If specified, facility is the numeric Syslog facility. The default is 2, which is usually LOG_MAIL.

See the syslog.conf, syslogd, and syslog man pages

for more information about Syslog.

Caveats: splogger converts unprintable characters to question marks (?).

Blank lines are not logged.

Messages are folded—split into multiple messages—after 800 characters due to line-length limitations in Syslog. splogger puts a plus sign (+) after the time-stamp to indicate that the message was folded.

The use of Syslog is discouraged due to reliability, efficiency, and security concerns. (See Chapter 2, "Installing qmail," for details.)

Example: To test splogger, the mail manager on a host named sparge runs it interactively:

 # echo this is a splogger test | /var/qmail/bin/splogger # tail /var/log/maillog Jun 2 07:37:00 sparge splogger: 991481820.149780 this is a splogger test # 

tcp-env

Usage: tcp-env [-rR] [-ttimeout] program [args]

Description: tcp-env runs program with the supplied arguments, if any, after setting a number of environment variables describing a Transmission Control Protocol (TCP) connection.

Environment Variables: The tcp-environ man page describes the environment that tcp-env (from qmail) and tcpserver and tcpclient (from daemontools) support. They are described in Table 5-4.

Table 5-4: tcp-env Environment Variables

VARIABLE

DESCRIPTION

PROTO

Protocol, always TCP

TCPLOCALHOST

Domain name of the local host in lowercase, if available

TCPLOCALIP

IP address of the local host, for example: 192.168.1.3

TCPLOCALPORT

Local TCP port associated with the connection

TCPREMOTEHOST

Domain name of the remote host in lowercase, if available

TCPREMOTEINFO

Connection-specific string, for example: remote username, if supplied

TCPREMOTEIP

IP address of the remote host

TCPREMOTEPORT

Remote TCP port associated with the connection

Caveats: tcp-env is usually run with its input being a TCP connection. It's usually invoked by inetd, which is configured by /etc/inetd.conf. However, if the PROTO environment variable is set to TCP when tcp-env is invoked, it assumes that the other environment variables are set properly.

The use of inetd is discouraged due to reliability and security concerns. (See Chapter 2, "Installing qmail," for details.)

Example: To run qmail-smtpd via inetd, one would add something like the following to /etc/inetd.conf (but all on one line):

 smtp stream tcp nowait qmaild /var/qmail/bin/tcp-env tcp-env /var/qmail/bin/qmail-smtpd 

Tip 

See the inetd.conf man page for details about the syntax of entries in inetd.conf.



 < Free Open Study > 



The Qmail Handbook
The qmail Handbook
ISBN: 1893115402
EAN: 2147483647
Year: 2001
Pages: 186
Authors: Dave Sill

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net