There are many tools available for debugging problems with sendmail. For the most part, standard types of configurations shouldn't provide any problems. However, for complex configurations requiring the rewriting of address parsing rules, problems may arise and debugging may be necessary.
First of all, the standard mail utility, mail (or Mail, or mailx) can be invoked with the -v flag to turn on verbose delivery. Verbose delivery shows the steps that sendmail takes in delivering the mail message. For example, the following is a transcript from an unsuccessful mail connection:
firstname.lastname@example.org... Connecting to herbie.ucs.indiana.edu. via smtp... 220 herbie.ucs.indiana.edu ESMTP Sendmail 8.7.5/8.6.12 ready at Thu, 18 Jul 1996 09:16:24 -0500 (EST) >>> EHLO outland.uwsg.indiana.edu 250-herbie.ucs.indiana.edu Hello outland.uwsg.indiana.edu [18.104.22.168], pleased to meet you 250-EXPN 250-8BITMIME 250-SIZE 250-DSN 250-VERB 250-ONEX 250 HELP >>> MAIL From:<email@example.com> SIZE=28 250 <firstname.lastname@example.org>... Sender ok >>> RCPT To:<email@example.com> 550 <firstname.lastname@example.org>... User unknown email@example.com... User unknown >>> RSET 250 Reset state /home/brier/dead.letter... Saved message in /home/brier/dead.letter /home/brier/dead.letter... Closing connection to herbie.ucs.indiana.edu. >>> QUIT 221 herbie.ucs.indiana.edu closing connection
This transcript provides a lot of information about what happened with this mail message. The first line shows that the message was intended for the address firstname.lastname@example.org, but that the SMTP connection was made to the machine herbie.ucs.indiana.edu. A little investigation with nslookup shows that uwsg.indiana.edu is a mail exchange record in the Domain Name System (DNS) for the machine herbie.ucs.indiana.edu, so all mail sent to uwsg.indiana.edu is actually delivered to herbie.ucs.indiana.edu.
Most of the remaining lines show the SMTP conversation between the two hosts. Much of this conversation is standard, but at line 15 there is an error: 550 <email@example.com>... User unknown. Here is our problem. There is no user fard on herbie.ucs.indiana.edu, and so the mail was not delivered.
One useful command line option of sendmail is -bv. This option puts sendmail into verify mode; it verifies addresses only, it does not deliver them. This is a good method for validating users or mailing lists.
For example, the following invocation:
$ /usr/lib/sendmail -bv brier brier... deliverable: mailer local, user brier
shows us that the address brier is a valid address and will be delivered locally. The next invocation:
$ /usr/lib/sendmail -bv ombuds ombuds... deliverable: mailer smtp, host indiana.edu, user firstname.lastname@example.org
shows that the address ombuds is also a valid address, but instead of being delivered locally, it will be delivered to email@example.com.
sendmail has a test mode which only performs and displays address rewriting, it does not actually deliver any mail. This test mode is an excellent resource for researching what sendmail does to an address during it's rewriting stage, and where mail sent to that address ends up being transported. Test mode can also be used to test changes made to a configuration file, especially changes to the address rewriting rules.
Test mode is invoked with the -bt option to sendmail. Since it is used often with experimental .cf files, it is often invoked in conjunction with the -C option which allows specification of an alternate .cf file. For example:
/usr/lib/sendmail -bt -Ciu-standalone.cf
would invoke sendmail in test mode, using the configuration file iu-standalone.cf in the current working directory, rather than the default /etc/sendmail.cf.
Using sendmail in test mode requires some knowledge about how sendmail rewrites addresses to allow them to be delivered. Briefly, the .cf file contains a number of rules for rewriting addresses. These rules are gathered up into rulesets which perform some task. So, a ruleset is a collection of rules responsible for a specific purpose in the address rewriting process, for example, canonifying names. These sendmail rulesets are numbered (0-99 in V8). The details of rewriting rules are a bit outside the scope of this course. For more information, check out the optional reference, Open Computing "Hands-On" Tutorial: January 1994, Explosion in a Punctuation Factory by Bryan Costales, or Bryan's book, sendmail, also called "the bat book".
In test mode, sendmail requires the user to specify an address to rewrite, and which rulesets through which that address should be sent. Without knowing a whole lot about rulesets and a mail message's flow through them, it is a little hard to know which rulesets to use. For general purposes, rulesets 3 and 0 give good information. Both of these rulesets are run on every message that goes through sendmail (ruleset 3 is the very first one, and ruleset 0 is the very last). For example, here is a sample transcript of a sendmail in test mode:
$ /usr/lib/sendmail -bt ADDRESS TEST MODE (ruleset 3 NOT automatically invoked) Enter <ruleset> <address> > 3,0 uwsg@uwsg rewrite: ruleset 3 input: uwsg @ uwsg rewrite: ruleset 96 input: uwsg < @ uwsg > rewrite: ruleset 96 returns: uwsg < @ herbie . ucs . indiana . edu . > rewrite: ruleset 3 returns: uwsg < @ herbie . ucs . indiana . edu . > rewrite: ruleset 0 input: uwsg < @ herbie . ucs . indiana . edu . > rewrite: ruleset 98 input: uwsg < @ herbie . ucs . indiana . edu . > rewrite: ruleset 98 returns: uwsg < @ herbie . ucs . indiana . edu . > rewrite: ruleset 95 input: < > uwsg < @ herbie . ucs . indiana . edu . > rewrite: ruleset 95 returns: uwsg < @ herbie . ucs . indiana . edu . > rewrite: ruleset 0 returns: $# smtp $@ herbie . ucs . indiana . edu . $: uwsg < @ herbie . ucs . indiana . edu . >
Ruleset 3 canonifies the address, invoking ruleset 96 to do part of it's work. First it puts angle brackets around the host part of the address (this notation is for sendmail's internal use, they are stripped off before sending), then it calls ruleset 96 to look up the hostname and convert it, if needed, to a fully qualified domain name. Note that ruleset 96 also returns the true name of the host. In this case, internally, uwsg became uwsg.indiana.edu, which was discovered to be an MX record and became the true hostname, herbie.ucs.indiana.edu.
Ruleset 0 is in charge of doing final parsing of addresses. In this example, ruleset 0 calls ruleset 98 (which is empty by default, so does nothing), then calls ruleset 95, which resolves addresses to the triple that sendmail expects as a final result. This triple consists of the mailer to use (in this case smtp as denoted by $#), the address to which the message should be transported (in this case herbie.ucs.indiana.edu as denoted by $@, and the address to put on the message (in this case uwsg < @ herbie . ucs . indiana . edu . > as denoted by $:).
|/canon host||Canonify host name.|
|/mx host||Look up MX records.|
|/map mapname key||Do Map lookup.|
|/parse address||Parse address.|
|/try mailer address||Externalize address.|
|/tryflags [HE][SR]||Tweak try.|
|.Dx value||Define macro.|
|.Cc value||Extend class.|
|-ddebugflags||Set debug flags.|
To summarize, with this sendmail configuration, a mail sent to uwsg@uwsg will have it's address rewritten to firstname.lastname@example.org and will be delivered to herbie.ucs.indiana.edu by the smtp mailer.
Beginning with version 8.7, sendmail supports a set of
extensions to test mode for making certain debugging operations
easier. These options are summarized in Table 1 (also available as plain text).
|-d21.2||Shows rewriting of addresses.|
|-d21.12||Shows more detailed rewriting of addresses.|
|-d60||Shows map lookups.|
|-d11||Shows mailer invocations|
|-d8.7||Shows DNS chat.|
|-d27.4||Shows alias, forward, and include traffic.|
|-d28.4||Shows user database traffic.|
|-d12||Shows remote name editing.|
|-d0.1||Shows compile flags and system identity.|
|-d0.4||Shows proving for local names.|
|-d0.10||Shows OS-dependent compile flags.|
sendmail has a -d flag for debugging options. For essential information on sendmail's command line debugging options, see Sendmail Installation and Operation Guide - Debugging.
The information reported by these debugging options is often very
low-level and may not always be helpful without the source at hand.
However, Table 2 (a plain text version is
available) shows a list of some of the more useful debugging flags.
The debugging options are most often used in tandem with the
-v option which turns on verbose delivery for sendmail
(the same as it does for mail).
Terms used: SMTP, mail exchange, DNS, sendmail, sendmail.cf.