2.2 Obtain the Source

The latest release of sendmail is available via:

http://www.sendmail.org/current-release.html

When you download the source you must select one file from many that are listed. In addition to selecting the version you want, you must choose between two forms of compressed tar(1) distributions. Those that end in .Z are compressed with Unix compress(1); those that end in .gz are compressed with GNU gzip(1). The latter is the preferred form because the file is smaller and therefore quicker to transfer.

In addition to the two forms of distribution, each release has a PGP signature file associated with it.^[2] This is a signature of the uncompressed file, so you need to uncompress the tar(1) file before verifying it.

^[2] Further information about how to use PGP can be found in PGP: Pretty Good Privacy, by Simson Garfinkel, O'Reilly & Associates, http://www.oreilly.com/catalog/pgp/.

To verify V8.5 or earlier distributions, get Eric Allman's public key by sending email to pgp-public-keys@keys.pgp.net with the following subject line:

Subject: MGET Allman

Eric Allman's public key will be mailed back to you a few minutes later. Save that returned email to a file—for example, /tmp/eric.asc—and add that key to your public "keyring" with the command:

% pgp -ka /tmp/eric.asc                for pgp version 2.x 
% pgpk -a /tmp/eric.asc                for pgp version 5.x 

For V8.6 and above, you download a special signing key from www.sendmail.org, instead of Eric's key. The fingerprint for the signing key is:

CA AE F2 94 3B 1D 41 3C  94 7B 72 5F AE 0B 6A 11    1997
F9 32 40 A1 3B 3A B6 DE  B2 98 6A 70 AF 54 9D 26    1998
25 73 4C 8E 94 B1 E8 EA  EA 9B A4 D6 00 51 C3 71    1999
81 8C 58 EA 7A 9D 7C 1B  09 78 AC 5E EB 99 08 5D    2000
59 AF DC 3E A2 7D 29 56  89 FA 25 70 90 0D 7E C1    2001
7B 02 F4 AA FC C0 22 DA  47 3E 2A 9A 9B 35 22 45    2002

The fingerprint for Eric's key is:

C0 28 E6 7B 13 5B 29 02 6F 7E 43 3A 48 4F 45 29      V8.5 and earlier

Once you have the appropriate key, execute the following command for the uncompressed source file:

pgp signature-file             for pgp version 2.x 
pgpv signature-file here       for pgp version 5.x 

If the uncompressed tar file is good, pgp(1) will report that the signature is valid.

A few things can go wrong here, causing the verification to fail:

• Signature and tar(1) files must match each other's versions. Transfer them again, this time with matching versions.

• When transferring the files with ftp(1), you must be sure to use binary mode. Transfer them again, this time with the correct mode.

• A presumed mirror FTP site might not be as official as you expect. If a secondary distribution fails to verify, get the official distributions from the official site shown earlier.

• The official distribution might appear bad. If it fails to verify, first check that your copy of PGP was correctly installed, then make sure your network connection is clean and that it has not been compromised. If all else fails (including getting the distribution anew as explained earlier), describe your problem to the folks at sendmail@sendmail.org.

If your copy of the sendmail distribution fails to verify, don't use it!

2.2.1 What's Where in the Source

V8.12 sendmail unpacks by creating a directory, then unpacking into that directory. The directory name is the same as the compressed filename but with a dash instead of the first dot:

% gzcat sendmail.8.12.7.tar.gz | tar xvf -
x sendmail-8.12.7/FAQ, 321 bytes, 1 tape blocks
x sendmail-8.12.7/INSTALL, 1396 bytes, 3 tape blocks
x sendmail-8.12.7/KNOWNBUGS, 8770 bytes, 18 tape blocks
... and so on

Inside the newly created directory you will find the full sendmail distribution:

% cd sendmail-8.12.7
% ls
Build           README          include         makemap
FAQ             RELEASE_NOTES   libmilter       praliases
INSTALL         cf              libsm           rmail
KNOWNBUGS       contrib         libsmdb         sendmail
LICENSE         devtools        libsmutil       smrsh
Makefile        doc             mail.local      test
PGPKEYS         editmap         mailstats       vacation

The README and RELEASE_NOTES files provide the most up-to-date information about changes, new features, and bug fixes. Read the documents in the doc directory. Also note that the README files in all the subdirectories contain important comments as well.

The files and directories in the source directory are listed in Table 2-1, and are described in detail in the sections that follow.

2.2.1.1 The top-level Build script

The top-level Build script can be used to do a global build across all programs. For example, you can do this to build all the programs:

% ./Build

All the commands you can use with the master Build (Section 5.1) are available to this Build.

2.2.1.2 The contrib directory

The contrib directory contains user-contributed and unsupported code. Among its contents are perl(1) scripts, shell scripts, C-language source code, and patches. The README file in this directory explains some of the policy surrounding the programs. For more complete information you will need to dig through the source files yourself.

If you have software that you would like to see included in this directory, email a description of that program to sendmail@sendmail.org.

2.2.1.3 The devtools directory

The devtools directory contains all the scripts and m4(1) source used to build sendmail and its libraries and companion programs. The README file there briefly describes the m4 macros used to configure your build process. We describe the current macros in Section 2.4. You should consult this file whenever a new release is issued because it will always have the most up-to-date information.

The devtools/Site directory is the default location for your m4 build configuration files. The README in that directory describes the strategy used to locate a build configuration file. Note that the -f command-line switch (-f) for the Build command can override use of that directory. Also note that the -Q command-line switch (-Q) for the Build command modifies the way an m4 file is found.

2.2.1.4 The doc directory

The doc directory contains only one subdirectory, op. The doc/op directory contains the sendmail "INSTALLATION AND OPERATION GUIDE." That guide is supplied in troff(1) source (op.me), and as a ready-to-print PostScript document (op.ps).

This is the main document distributed with sendmail that describes that program. It is succinct, and always a good place to start for a quick but detailed overview.

2.2.1.5 The include directory

The include directory contains four subdirectories. The include/libsmdb directory contains files that support the use of the libsmdb library of common database routines. The include/sendmail directory contains files useful for sendmail and for programs that share the sendmail definitions and declarations (for example, the mailstats program). The include/libmilter directory contains files that support use of the libmilter library of routines. The include/sm directory contains files that support use of the libsm library of routines.

2.2.1.6 The INSTALL file

The INSTALL file contains a brief list of steps for compiling and installing sendmail.

2.2.1.7 The KNOWNBUGS file

The KNOWNBUGS file contains a (not always up-to-date) list of the most difficult bugs to fix in the sendmail program. Presence of this file ought not suggest that sendmail is distributed with bugs. Rather, it should assure you that reported bugs are admitted to and dealt with.

If you encounter behavior with sendmail that appears to be a bug in sendmail and not in another program, document that bug carefully so that it can be repeated, and send your description of it to sendmail-bugs@sendmail.org.

If you encounter a security problem with sendmail, use the fingerprint and public key stored in the PGPKEYS file to encrypt a message and send that message to sendmail-security@sendmail.org. Always try to avoid sending security-related email in clear text.

2.2.1.8 The libmilter directory

The sendmail folks have defined a mail filter API called milter. Using this API, third-party programmers (you, for example) can design programs to access mail messages as they are being processed by sendmail. Such real-time access allows email message content to be filtered and possibly rejected based on content—a potentially powerful anti-spam tool.

The README file in this directory describes the steps needed to design, compile, and run such a filter. But beware. The use of this API and creation of a filter program require the use of POSIX threads. If your OS lacks POSIX thread support, you will not be able to use this API.

For systems that support POSIX threads, we illustrate the creation and use of a mail filter program in Section 7.6.

2.2.1.9 The libsm directory

To support many of the new features in sendmail, and to pave the way for more sophisticated versions in the future, the designers of sendmail decided to create a replacement for many of the routines in the standard C library. A quick glance at that directory will reveal replacements, for example, of fput(3) and ungetc(3).

A library of these routines is built and used by sendmail automatically when you build that program. You need do nothing special here.

In the rare event that you need to port sendmail to an entirely new operating system, you will need to study the file README in that directory, and examine (and perhaps tweak) some of the various C source files there.

2.2.1.10 The libsmdb directory

The libsmdb directory contains source for a library that supports opening, reading, writing, searching, and closing database files. The types of database files supported are Berkeley db (versions 1, 2, and 3), btree and hash, and ndbm. This library is used by makemap, praliases, editmap, and vacation.

2.2.1.11 The libsmutil directory

The libsmutil directory contains source for a library of routines that are useful to sendmail and its companion programs. Among the routines are support for debugging with -d (Section 16.1), the checking of safe files and directories (-d44.4), and other useful tasks.

2.2.1.12 The LICENSE file

The LICENSE file contains the legal jargon surrounding how, when, and why you can use the source and the programs produced by that source. It also includes instructions on how to get updated license information.

2.2.1.13 The Makefile file

The top-level Makefile file can be used to globally compile all the programs in the distribution. It uses two environment variables: CONFIG and FLAGS. These can either be put into make's environment as part of its command line, or put into your shell's environment. The first technique is used when you wish to condition one of these variables just once or so. The second is useful when a variable setting is needed over and over during a prolonged development session.

The first technique looks like this:

% make CONFIG="-Q Server" FLAGS="-c"

Here, the CONFIG variable is used to set the location for your m4 build file, and the FLAGS variable is used to pass any other command-line switches you need to the Build program.

The second technique begins by conditioning your shell's environment variables:

setenv CONFIG "-Q Server"                   the C shell and derivatives
CONFIG="-Q Server" ; export CONFIG          the Bourne shell and derivatives
setenv FLAGS "-c"                           the C shell and derivatives
FLAGS="-c" ; export FLAGS                   the Bourne shell and derivatives

You will see the result of declaring these two environment variables when you run the make(1) program, this time without having to specify those two variables in the command line:

% make all

See Section 5.1 for an overview of how Build works, and what the -c and -Q switches do.

2.2.1.14 The PGPKEYS file

The PGPKEYS file contains the keys used to validate the authenticity of the sendmail distribution. To use them, however, you first need to unpack the distribution, then run pgp on the uncompress tar file. This might give you the impression of safety, but be aware that a fake distribution can contain fake keys in a fake PGPKEYS file, and the fake PGPKEYS file will verify the fake distribution.

See Section 2.2 for a description of the better way to validate your sendmail distribution.

2.2.1.15 The README file

The README file's name should encourage you to do just what it says. Read that file whenever you download a fresh distribution. It contains lots of useful and up-to-date information.

2.2.1.16 The RELEASE_NOTES file

The RELEASE_NOTES file contains a comprehensive and cumulative history of the sendmail program. It is organized by release date, with the most recent first, and earlier releases following in order, by age. Each section shows changes to the code, changes to the configuration files, and changes that affect compiling. This file is a must-read because it details in one place all the changes that are included in the current and prior releases.

2.2.1.17 The test directory

The test directory contains C-language programs that help the development team at sendmail.com solve problems concerning the porting of sendmail to other architectures. They are of interest only if you intend to port sendmail to a currently unsupported platform. Each .c file is somewhat self-documenting.