SIGUSR1

SIGUSR1

---

Tell sendmail to dump its states

sendmail signal

Beginning with V8.6.5, sendmail responds to a SIGUSR1 signal. This signal causes sendmail to syslog at LOG_DEBUG the several items that define its state. ^[1] That syslog output begins with a line that looks like this:

^[1] This same information is syslog 'd if the daemon loses track of $j in $=w and if $j becomes or is not fully qualified.

 --- dumping state on   reason   : $j =   val   --- 

where reason can be any one of the following:

user signal

The information has been logged because sendmail received a SIGUSR1 signal. In this instance the daemon logs the information and continues to run.

daemon lost $j

The information has been logged because a running daemon discovered that the value in $j (the canonical name of this host, $j) disappeared from the class $=w (the list of all names by which the local host is known, $=w). This test is made and this information is logged only if sendmail was compiled with XDEBUG defined (XDEBUG). In this instance the daemon logs the information and aborts.

daemon $j lost dot

The information has been logged because a running daemon discovered that the value in $j (the canonical name of this host, $j) was no longer canonical (no longer contained a dot inside it). This test is made and this information is logged only if sendmail was compiled with XDEBUG defined (XDEBUG). In this instance the daemon logs the information and aborts.

Whichever the reason, the information that is logged for each looks pretty much the same; for example:

 --- dumping state on   reason   : $j =   val   --- CurChildren =   num   NextMacroId =   nextid   (Max   maxid   )   --- open file descriptors: ---     output of dumpfd() here  --- connection cache: ---     output of mci_dump() here  --- ruleset debug_dumpstate returns stat  ret, pv: -      output of rule set debug_dumpstate here  --- end of state dump --- 

We have described the first line already. If, for some reason, $j is missing from $=w , that line will be followed by:

 *** $j not in $=w *** 

The second line simply shows the number of children the daemon has forked and currently has out doing other work in parallel with itself. The third line shows the next available value that can be assigned to a multicharacter sendmail macro ( nextid ), and the maximum of such numbers available ( maxid ). That line is followed by three sections of information. The first two sections are always output; the third is output only if rule set debug_dumpstate (See this section) exists.

- open file descriptors: -

Each open file descriptor is displayed along with its current properties. These lines of output can be numerous . In general form, they look like this:

   num   : fl=   flags   mode=   mode     type     stats   

Here, the num is the number of the open file descriptor. The other information in this line is described in detail in our discussion of the -d2.9 debugging switch (see -d2.9).

- connection cache: -

When sending mail, outgoing connections are maintained for efficiency, and information about those connections is cached. Before connecting to a remote host, for example, sendmail checks its cache to see whether that host is down. If it is, it skips connecting to that host.

This output is highly detailed and very complicated. See the -d11.1 debugging switch (-d11.1) for a full description.

- ruleset debug_dumpstate returns stat ..., pv: -

If the debug_dumpstate rule set ^[2] is defined in your configuration file, it will be called here, and the previous line of output will be printed. The stat is the numeric representation of the code returned by sendmail 's internal rewrite () routine. That code will be either EX_OK (0) if there were no parsing errors, EX_CONFIG (78) if there were, or EX_DATAERR (65) if there was a fatal error (such as too much recursion, or if a replacement was out of bounds). Text describing the error is also logged and will appear in this output.

^[2] In V8.7 sendmail this is rule set 89. Beginning with V8.8 sendmail , rule sets 80 through 89 are reserved for use by vendors , such as Sun Microsystems.

Rule set debug_dumpstate is called with an empty workspace. After the debug_dumpstate rule set is done, each token in the resulting new workspace is printed, one per line. This gives you a hook into the internals of sendmail , enabling you to display information that might otherwise be invisible. For example, consider the desire to display identd information, the current sender's address, and the current queue identifier:

 Sdebug_dumpstate R$*     $@ $&_ $&s $&i 

Here, the $* in the LHS matches the zero tokens passed to the debug_dumpstate rule set. The $@ prefix in the RHS suppresses recursion. Each of the three sendmail macros that follows is stated with a $& prefix (Section 21.5.3) that prevents each from being prematurely expanded when the configuration file is first read.

Another example might involve the need to look up the current recipient's host with DNS:

 Sdebug_dumpstate R$*     $@ $[ $&h $] 

The $[ and $] operators (Section 18.7.6) cause the hostname appearing between them to be looked up with DNS and replaced with its full canonical name. Again, the macro h is prefixed with $& to prevent premature expansion.

In general, the debug_dumpstate rule set should be excluded from your configuration file. When a problem does appear, you can define it, restart the daemon, and then wait for the problem to reoccur. When it does, kill sendmail with a SIGUSR1 and examine the syslog result.

Do not be tempted to use the debug_dumpstate rule set for routine logging of specialty information. Forcing rules to be processed with a signal is fraught with danger. The current active rule set can, for example, be clobbered in possibly unrecoverable ways. Use this debug_dumpstate rule set technique only to solve specific problems, then erase it when the problem is solved .