Table of Contents for
sendmail, 4th Edition

Version ebook / Retour

Cover image for bash Cookbook, 2nd Edition sendmail, 4th Edition by Gregory Neil Shapiro Published by O'Reilly Media, Inc., 2007
  1. sendmail, 4th Edition
  2. Cover
  3. sendmail, 4th Edition
  4. Dedication
  5. Preface
  6. 1. Some Basics
  7. I. Administration
  8. 2. Download, Build, and Install
  9. 3. Tune sendmail with Compile-Time Macros
  10. 4. Maintain Security with sendmail
  11. 5. Authentication and Encryption
  12. 6. The sendmail Command Line
  13. 7. How to Handle Spam
  14. 8. Test Rule Sets with -bt
  15. 9. DNS and sendmail
  16. 10. Build and Use Companion Programs
  17. 11. Manage the Queue
  18. 12. Maintain Aliases
  19. 13. Mailing Lists and ~/.forward
  20. 14. Signals, Transactions, and Syslog
  21. 15. Debug sendmail with -d
  22. II. Configuration Reference
  23. 16. Configuration File Overview
  24. 17. Configure sendmail.cf with m4
  25. 18. The R (Rules) Configuration Command
  26. 19. The S (Rule Sets) Configuration Command
  27. 20. The M (Mail Delivery Agent) Configuration Command
  28. 21. The D (Define a Macro) Configuration Command
  29. 22. The C and F (Class Macro) Configuration Commands
  30. 23. The K (Database-Map) Configuration Command
  31. 24. The O (Options) Configuration Command
  32. 25. The H (Headers) Configuration Command
  33. 26. The X (Milters) Configuration Command
  34. III. Appendixes
  35. A. The mc Configuration Macros and Directives
  36. B. What’s New Since Edition 3
  37. C. The checkcompat( ) Function
  38. Bibliography
  39. Index
  40. About the Authors
  41. Colophon
  42. Copyright

Appendix C. The checkcompat( ) Function

Inside sendmail is the often-overlooked checkcompat( ) routine. It has existed since V3, and is intended to allow the site administrator to accept, reject, and log mail delivery attempts. As sendmail continues to evolve, the need for this checkcompat( ) routine diminishes. It is no longer, for example, needed to screen for spam rejection because much of that can now be done in rule sets and the access database. On modern machines that support POSIX threads, the Milter API allows external programs to perform all the tasks that formerly could be handled only by the checkcompat( ) routine.

But the checkcompat( ) routine still has a number of uses. Here are a few:

  • Capture the message body for each outbound message and send it via TCP/IP to a central archive host. Be sure to detect multiple recipients to avoid duplicate archived messages.[455]

  • Check the Received: headers on messages sent from one of your MX servers to see who sent it. This allows you to reject spam messages that try to do an end run around your access database. Sort the Received: headers by date and examine the second most recent.

  • Monitor a port for incoming commands, or a database of times. You might use this to defer delivery for particular recipients during selected windows of time.

  • Check for a particular header that indicates a copy of the message should be archived. You might use this to add a recipient (if not already present) that results in archival of the message (such as archiver@archive.host).

Note that because the checkcompat( ) routine is called for every delivery attempt a cascade of errors can propagate if you are not careful with your design. Logging a warning based on the sender, for example, can result in multiple warnings when there are multiple recipients.

Finally, note that V8.8 and above sendmail also offer a check_compat rule set (see The check_compat Rule Set on page 259) that can perform some of the checkcompat( ) routine’s functionality at the rule set level. This is one way to avoid having to program in the C language.

How checkcompat( ) Works

When sendmail prepares to deliver mail, it first checks the size of the mail message and rejects (bounces) it if it is larger than the limit imposed by the M= delivery agent equate (M= on page 746). V8.8 and above sendmail then call the check_compat rule set (The check_compat Rule Set on page 259). After that, all versions of sendmail call the checkcompat( ) routine.

The checkcompat( ) routine lies in a unique position within the sendmail code. It is the one place where both the sender and the already aliased recipient addresses are available at the same time. Because it is invoked immediately before actual delivery, all the information needed for delivery is available to you for checking.

If checkcompat( ) returns EX_OK, as defined in <sysexits.h>, the mail message is considered OK and delivered. Otherwise, the message is bounced. If you wish the message to be requeued instead of bounced, you can return EX_TEMPFAIL.

Again note that the checkcompat( ) routine is called once for each already aliased recipient.

Arguments Passed to checkcompat( )

The checkcompat( ) is found in the C-language source file sendmail/conf.c. Inside that file you will find it declared like this:

checkcompat(to, e)
        register ADDRESS *to;
        register ENVELOPE *e;

Here, to is a pointer to a structure of typedef ADDRESS which contains information about the recipient. And e is a pointer to a structure of typedef ENVELOPE which contains information about the current envelope. (Actually, both are linked lists of structures.)

The members of the ADDRESS *to structure are shown in Table C-1. Note that these members are correct for V8.14 sendmail only. Also note that the table shows only those members that can be useful in a checkcompat( ) routine (see sendmail.h for the other members of *to).

Table C-1. ADDRESS *to members

Type

Member

Description

struct address *

q_alias

The alias that yielded this address

char *

q_finalrcpt

This is a Final-Recipient: DSN header

unsigned long

q_flags

Address flags

char *

q_fullname

The (GECOS) full name of q_ruser, if known

gid_t

q_gid

The gid of the q_ruser, if known

char *

q_home

The home directory (path), if F=w delivery-agent flag is set

char *

q_host

The host part ($@) from rule set 0

struct mailer *

q_mailer

The delivery agent ($#) from rule set 0

char *

q_message

Message regarding address (not always an error)

struct address *

q_next

Link to the next ADDRESS in the chain

char *

q_orcpt

The ORCPT parameter from RCPT TO: line was set

char *

q_owner

The owner of q_alias

char *

q_paddr

The address in a form suitable for printing

int

q_qdir

Queue directory inside group

int

q_qgrp

Index into queue groups

char *

q_ruser

The login name for this user, if known

time_t

q_statdate

The date of the status change

short

q_state

The state of the address

char *

q_statmta

Which MTA generated q_rstatus

uid_t

q_uid

The uid of the q_ruser, if known

char *

q_user

The user part ($:) from rule set 0

The members of the ENVELOPE *e structure are shown in Table C-2. Note that these members are correct for V8.14 sendmail only. Also note that the table shows only those members that can be useful in a checkcompat( ) routine (see sendmail.h for other members of *e).

Table C-2. ENVELOPE *e members

Type

Member

Description

char *

e_auth_param

The parameters set by AUTH=

char *

e_bodytype

The type of message body

short

e_class

The message class (priority, junk, etc.)

time_t

e_ctime

The time this message was accepted

long

e_deliver_by

The DELIVERYBY BY= interval

int

e_dlvr_flag

The DELIVERYBY BY= flags

SM_FILE_T *

e_dfp

The datafile

int

e_dfqgrp

The datafile’s queue group index

int

e_dfqdir

The datafile’s queue directory index

time_t

e_dtime

The time of the last delivery attempt

char *

e_envid

Envelope ID from MAIL FROM:

short

e_errormode

The error return mode

ADDRESS *

e_errorqueue

The queue for error responses

unsigned long

e_flags

Envelope flags

ADDRESS

e_from

The sender address structure

char **

e_fromdomain

The domain part of the sender

HDR *

e_header

Linked list of headers

short

e_hopcount

The hop count for the message

char *

e_id

The ID for this entry

char *

e_message

The error message

char *

e_msgid

The message ID (for logging)

long

e_msgpriority

The adjusted priority of this message

long

e_msgsize

The size of the message in bytes

int

e_nrcpts

The number of recipients

int

e_ntries

The number of delivery attempts

int

e_qgrp

The queue group (index into queues)

int

e_qdir

The index into queue directories

char *

e_sender

Sender address with comments stripped

ADDRESS *

e_sendqueue

Linked list of recipients

char *

e_statmsg

The status message (changes per delivery)

char *

e_status

The DSN status for this message

short

e_timeoutclass

The message timeout class

The checkcompat( ) routine is a powerful internal hook inside sendmail. It is so internal and powerful, in fact, that if you are truly clever you can even use checkcompat( ) to modify rewrite rules at runtime (scary, but possible).

Global Variables

V8.14 sendmail uses more than 100 variables. They are all listed in sendmail.h and conf.c with “lite” comments. Global variables store information such as sendmail’s option values, file descriptor values, macro values, class lists, and database access information. Any can be modified inside checkcompat, but before attempting to do so, study the sendmail C source code to anticipate any unexpected side effects.

In general, you can use almost any of the global variables when designing your own checkcompat( ) routine. The five most interesting are:

RealHostAddr

The IP address of the sending host. This is a union of several sockaddr_ types depending on your selection of protocol types. This can be zero for locally submitted mail.

RealHostName

A string containing the definitive canonical name of the sending host. If it can’t be resolved to a name, it will contain the host’s IP number in text form, surrounded by square brackets.

LogLevel

This variable determines the amount of logging that sendmail does, and is set using the LogLevel option (LogLevel on page 1040). You can use this LogLevel variable to decide how much, if anything, you wish to log about what you are doing inside the checkcompat( ) function.

CurrentLA

An integer representation of the current load average. You might want to use checkcompat( ) to defer mail between selected senders and recipients when the load is very high.

Verbose

An integer that, when nonzero, means that you allow checkcompat( ) to show (print to the standard output) what it is doing.


[455] * Of course, if the archive host supports POSIX threads, these tasks would be better handled by a Milter running on that host.