xref: /csrg-svn/usr.sbin/sendmail/src/READ_ME (revision 65000)

# Copyright (c) 1983 Eric P. Allman
# Copyright (c) 1988 The Regents of the University of California.
# All rights reserved.
#
# %sccs.include.redist.sh%
#
#	@(#)READ_ME	8.33 (Berkeley) 12/01/93
#

This directory contains the source files for sendmail.

For detailed instructions, please read the document ../doc/op.me:

	eqn ../doc/op.me | pic | ditroff -me

The Makefile is for the new (4.4BSD) Berkeley make, available from
ftp.uu.net in the directory /systems/unix/bsd-sources/usr.bin/make.
(Paul Southworth <pauls@umich.edu> published a description of porting
this make in comp.unix.bsd.)  This Makefile has assumptions about the
4.4 file system layout built in.

There is also a Makefile.dist which is much less clever, but works on
the old traditional make.  You can use this using:

	make -f Makefile.dist

There are a bunch of other Makefiles for other systems -- these are
the ones that I use, they have "Berkeley quirks" in them, and I don't
guarantee that they will work unmodified in your environment.  However,
they are all designed for the old make and can be used to help you get
started.  They have names like "Makefile.HPUX".  Many of them include
-I/usr/sww/include/db and -L/usr/sww/lib -- this is Berkeley's
location for the new database libraries, described below.  You don't
have to remove these definitions if you don't have these directories.

There is also a shell script (makesendmail) that tries to be clever
about using object subdirectories.  It's pretty straightforward, and
may help if you share a source tree among different architectures.

**************************************************************************
**  IMPORTANT:  DO NOT USE OPTIMIZATION (``-O'') IF YOU ARE RUNNING	**
**  GCC 2.4.x or 2.5.x.  THERE IS A BUG IN THE GCC OPTIMIZER THAT	**
**  CAUSES SENDMAIL COMPILES TO FAIL MISERABLY.				**
**************************************************************************

Jim Wilson of Cygnus believes he has found the problem -- it will
probably be fixed in GCC 2.5.6 -- but until this is verified, be
very suspicious of gcc -O.

**************************************************************************
**  IMPORTANT:  Read the appropriate paragraphs in the section on	**
**  ``Operating System and Compile Quirks''.				**
**************************************************************************


+----------------------+
| DATABASE DEFINITIONS |
+----------------------+

There are several database formats that can be used for the alias files
and for general maps.  When used for alias files they interact in an
attempt to be back compatible.

The three options are NEWDB (the new Berkeley DB package), NDBM (the
older DBM implementation -- the very old V7 implementation is no
longer supported), and NIS (Network Information Services).  Used alone
these just include the support they indicate.  [If you are using NEWDB,
get the latest version from FTP.CS.Berkeley.EDU in /ucb/4bsd.  DO NOT
use the version from the Net2 distribution!  However, if you are on
BSD/386 or 386BSD-based systems, use the one that already exists
on your system.  You may need to define OLD_NEWDB to do this.]

If NEWDB and NDBM are defined (but not NIS), then sendmail will read
NDBM format alias files, but the next time a newaliases is run the
format will be converted to NEWDB; that format will be used forever
more.  This is intended as a transition feature.  [Note however that
the NEWDB library also catches and maps NDBM calls; you will have to
back out this feature to get this to work.  See ``Quirks'' section
below for details.]

If all three are defined, sendmail operates as described above, and also
looks for the file /var/yp/Makefile.  If it exists, newaliases will
build BOTH the NEWDB and NDBM format alias files.  However, it will
only use the NEWDB file; the NDBM format file is used only by the
NIS subsystem.

If NDBM and NIS are defined (regardless of the definition of NEWDB
or the existance of /var/yp/Makefile), sendmail adds the special
tokens "YP_LAST_MODIFIED" and "YP_MASTER_NAME", both of which are
required if the NDBM file is to be used as an NIS map.

All of -DNEWDB, -DNDBM, and -DNIS are normally defined in the DBMDEF
line in the Makefile.


+---------------+
| COMPILE FLAGS |
+---------------+

Whereever possible, I try to make sendmail pull in the correct
compilation options needed to compile on various environments based on
automatically defined symbols.  Some machines don't seem to have useful
symbols availble, requiring the following compilation flags in the
Makefile:

SOLARIS		Define this if you are running Solaris 2.0 or higher.
SOLARIS_2_3	Define this if you are running Solaris 2.3 or higher.
NeXT		Define this if you are on a NeXT box.  (This one may
		be pre-defined for you.)  There are other hacks you
		have to make -- see below.
_AIX3		Define this if you are IBM AIX 3.x.
RISCOS		Define this if you are running RISC/os from MIPS.
_SCO_unix_	Define this if you are on SCO UNIX.

If you are a system that sendmail has already been ported to, you
probably won't have to touch these.  But if you are porting, you may
have to tweak the following compilation flags in conf.h in order to
get it to compile and link properly:

SYSTEM5		Adjust for System V.
SYS5SIGNALS	Use System V signal semantics -- the signal handler
		is automatically dropped when the signal is caught.
		If this is not set, use POSIX/BSD semantics, where the
		signal handler stays in force until an exec or an
		explicit delete.  Implied by SYSTEM5.
SYS5SETPGRP	Use System V setpgrp() semantics.  Implied by SYSTEM5.
HASFLOCK	Set this if you prefer to use the flock(2) system call
		rather than using fcntl-based locking.  Fcntl locking
		has some semantic gotchas, but many vendor systems
		also interface it to lockd(8) to do NFS-style locking.
		For this reason, this should not be set unless you
		don't have an alternative.
HASUNAME	Set if you have the "uname" system call.  Implied by
		SYSTEM5.
HASUNSETENV	Define this if your system library has the "unsetenv"
		subroutine.
HASSTATFS	Define this if you have the statfs(2) system call.  It's
		not a disaster to get this wrong -- but you do lose the
		queue free space code.
HASUSTAT	Define this if you have the ustat(2) system call.  It's
		not a disaster to get this wrong -- but you do lose the
		queue free space code.
HASSETSID	Define this if you have the setsid(2) system call.  This
		is implied if your system appears to be POSIX compliant.
HASINITGROUPS	Define this if you have the initgroups(3) routine.
HASSETVBUF	Define this if you have the setvbuf(3) library call.
		If you don't, setlinebuf will be used instead.  This
		defaults on if your compiler defines __STDC__.
HASSETREUID	Define this if you have setreuid(2) ***AND*** root can
		use setreuid to change to an arbitrary user.  This second
		condition is not satisfied on AIX 3.x.  You may find that
		your system has setresuid(2), (for example, on HP-UX) in
		which case you will also have to #define setreuid(r, e)
		to be the appropriate call.  Some systems (such as Solaris)
		have a compatibility routine that doesn't work properly,
		but may have "saved user ids" properly implemented so you
		can ``#define setreuid(r, e) seteuid(e)'' and have it work.
		The important thing is that you have a call that will set
		the effective uid independently of the real or saved uid
		and be able to set the effective uid back again when done.
		There's a test program in ../test/t_setreuid.c that will
		try things on your system.  Setting this improves the
		security, since sendmail doesn't have to read .forward
		and :include: files as root.  There are certain attacks
		that may be unpreventable without this call.
HASLSTAT	Define this if you have symbolic links (and thus the
		lstat(2) system call).  This improves security.  Unlike
		most other options, this one is on by default, so you
		need to #undef it in conf.h if you don't have symbolic
		links (these days everyone does).
GIDSET_T	The type of entries in a gidset passed as the second
		argument to getgroups(2).  Historically this has been an
		int, so this is the default, but some systems (such as
		IRIX) pass it as a gid_t, which is an unsigned short.
		This will make a difference, so it is important to get
		this right!  However, it is only an issue if you have
		group sets.
SLEEP_T		The type returned by the system sleep() function.
		Defaults to "unsigned int".  Don't worry about this
		if you don't have compilation problems.
ARBPTR_T	The type of an arbitrary pointer -- defaults to "void *".
		If you are an very old compiler you may need to define
		this to be "char *".
LA_TYPE		The type of load average your kernel supports.  These
		can be LA_SUBR (4) if you have the getloadavg(3) routine,
		LA_MACH (5) to use MACH-style load averages (calls
		processor_set_info()), LA_FLOAT (3) if you read kmem and
		interpret the value as a floating point number, LA_INT (2)
		to interpret as a long integer, or LA_SHORT (6) to
		interpret as a short integer.  These last three have
		several other parameters that they try to divine: the
		name of your kernel, the name of the variable in the
		kernel to examine, the number of bits of precision in
		a fixed point load average, and so forth.  In desparation,
		use LA_ZERO (1) -- it always returns the load average as
		"zero" (and does so on all architectures).  The actual
		code is in conf.c -- it can be tweaked if you are brave.
ERRLIST_PREDEFINED
		If set, assumes that some header file defines sys_errlist.
		This may be needed if you get type conflicts on this
		variable -- otherwise don't worry about it.
WAITUNION	The wait(2) routine takes a "union wait" argument instead
		of an integer argument.  This is for compatibility with
		old versions of BSD.
SCANF		You can set this to extend the F command to accept a
		scanf string -- this gives you a primitive parser for
		class definitions -- BUT it can make you vulnerable to
		core dumps if the target file is poorly formed.


+-----------------------+
| COMPILE-TIME FEATURES |
+-----------------------+

There are a bunch of features that you can decide to compile in, such
as selecting various database packages and special protocol support.
Several are assumed based on other compilation flags -- if you want to
"un-assume" something, you probably need to edit conf.h.  Compilation
flags that add support for special features include:

NDBM		Include support for "new" DBM library for aliases and maps.
		Normally defined in the Makefile.
NEWDB		Include support for Berkeley "db" package (hash & btree)
		for aliases and maps.  Normally defined in the Makefile.
NIS		Define this to get NIS (YP) support for aliases and maps.
		Normally defined in the Makefile.
USERDB		Include support for the User Information Database.  Implied
		by NEWDB in conf.h.
IDENTPROTO	Define this as 1 to get IDENT (RFC 1413) protocol support.
		This is assumed unless you are running on Ultrix or
		HP-UX, both of which have a problem in the UDP
		implementation.  You can define it to be 0 to explicitly
		turn off IDENT protocol support.
MIME		Include support for MIME-encapsulated error messages.
LOG		Set this to get syslog(3) support.  Defined by default
		in conf.h.  You want this if at all possible.
NETINET		Set this to get TCP/IP support.  Defined by default
		in conf.h.  You probably want this.
NETISO		Define this to get ISO networking support.
SMTP		Define this to get the SMTP code.  Implied by NETINET
		or NETISO.
NAMED_BIND	Define this to get DNS (name daemon) support, including
		MX support.  The specs you must use this if you run
		SMTP.  Defined by default in conf.h.
QUEUE		Define this to get queueing code.  Implied by NETINET
		or NETISO; required by SMTP.  This gives you other good
		stuff -- it should be on.
DAEMON		Define this to get general network support.  Implied by
		NETINET or NETISO.  Defined by default in conf.h.  You
		almost certainly want it on.
MATCHGECOS	Permit fuzzy matching of user names against the full
		name (GECOS) field in the /etc/passwd file.  This should
		probably be on, since you can disable it from the config
		file if you want to.  Defined by default in conf.h.
SETPROCTITLE	Try to set the string printed by "ps" to something
		informative about what sendmail is doing.  Defined by
		default in conf.h.


+---------------------+
| DNS/RESOLVER ISSUES |
+---------------------+

Many systems have old versions of the resolver library.  At a minimum,
you should be running BIND 4.8.3; older versions may compile, but they
have known bugs that should give you pause.

Common problems in old versions include "undefined" errors for
dn_skipname.

Some people have had a problem with BIND 4.9; it uses some routines
that it expects to be externally defined such as strerror().  It may
help to link with "-l44bsd" to solve this problem.


+-------------------------------------+
| OPERATING SYSTEM AND COMPILE QUIRKS |
+-------------------------------------+

SunOS 4.x (Solaris 1.x)
	You may have to use -lresolv on SunOS.  However, beware that
	this links in a new version of gethostbyname that does not
	understand NIS, so you must have all of your hosts in DNS.

	Some people have reported problems with the SunOS version of
	-lresolv and/or in.named, and suggest that you get a newer
	version.  The symptoms are delays when you connect to the
	SMTP server on a SunOS machine or having your domain added to
	addresses inappropriately.  There is a version of BIND
	version 4.9 on gatekeeper.DEC.COM in pub/BSD/bind/4.9.

	There is substantial disagreement about whether you can make
	this work with resolv+, which allows you to specify a search-path
	of services.  Some people report that it works fine, others
	claim it doesn't work at all (including causing sendmail to
	drop core when it tries to do multiple resolv+ lookups for a
	single job).  I haven't tried resolv+, as we use DNS exclusively.

	Should you want to try resolv+, it is on ftp.uu.net in
	/networking/ip/dns.

Solaris 2.x (SunOS 5.x)
	To compile for Solaris, be sure you use -DSOLARIS.

	From a correspondent:

	   For solaris 2.2, I have

		hosts:      files dns

	   in /etc/nsswitch.conf and /etc/hosts has to have the fully
	   qualified host name. I think "files" has to be before "dns"
	   in /etc/nsswitch.conf during bootup.

	To the best of my knowledge, Solaris does not have the
	gethostbyname problem described above.

	The Solaris "syslog" function is apparently limited to something
	about 90 characters because of a kernel limitation.  If you have
	source code, you can probably up this number.  The syslogd patch
	is included in kernel jumbo patch for Solaris 2.2 as of revision
	-39 or so.  At least one person is running with patch 100999-45
	and their long lost sendmail logging is finally showing up.

OSF/1
	If you are compiling on OSF/1 (DEC Alpha), you must use
	-non_shared (otherwise it core dumps on startup).  You may also
	need -mld to get the nlist() function, although some versions
	apparently don't need this.

	Also, the enclosed makefile removed /usr/sbin/smtpd; if you need
	it, just create the link to the sendmail binary.

NeXT
	If you are compiling on NeXT, you will have to create an empty
	file "unistd.h" and create a file "dirent.h" containing:

		#include <sys/dir.h>
		#define dirent	direct

	(The Makefile.NeXT should try to do both of these for you.)

	Apparently, there is a bug in getservbyname on Nextstep 3.0
	that causes it to fail under some circumstances with the
	message "SYSERR: service "smtp" unknown" logged.  You should
	be able to work around this by including the line:

		OOPort=25

	in your .cf file.

	You may have to use -DNeXT.

BSDI (BSD/386) 1.0, NetBSD 0.9, FreeBSD 1.0
	The "m4" from BSDI won't handle the config files properly.
	I haven't had a chance to test this myself.

	The M4 shipped in FreeBSD and NetBSD 0.9 don't handle the config
	files properly. One must use either GNU m4 1.1 or the PD-M4
	recently posted in comp.os.386bsd.bugs (and maybe others).
	NetBSD-current includes the PD-M4 (as stated in the NetBSD file
	CHANGES).

	FreeBSD 1.0 RELEASE has uname(2) now. Use -DUSEUNAME in order to
	use it (look into Makefile.FreeBSD). NetBSD-current may have
	it too but it has not been verified.

	You cannot port the latest version of the Berkeley db library
	and use it with sendmail without recompiling the world.  This
	is because C library routines use the older version which have
	incompatible header files -- the result is that it can't read
	other system files, such as /etc/passwd, unless you use the
	new db format throughout your system.  You should normally just
	use the version of db supplied in your release.  You may need
	to use -DOLD_NEWDB to make this work -- this turns off some
	new interface calls (for file locking) that are not in older
	versions of db.  You'll get compile errors if you need this
	flag and don't have it set.

4.3BSD
	If you are running a "virgin" version of 4.3BSD, you'll have
	a very old resolver and be missing some header files.  The
	header files are simple -- create empty versions and everything
	will work fine.  For the resolver you should really port a new
	version (4.8.3 or later) of the resolver; 4.9 is available on
	gatekeeper.DEC.COM in pub/BSD/bind/4.9.  If you are really
	determined to continue to use your old, buggy version (or as
	a shortcut to get sendmail working -- I'm sure you have the
	best intentions to port a modern version of BIND), you can
	copy ../contrib/oldbind.compat.c into src and add
	oldbind.compat.o to OBJADD in the Makefile.

Linux
	From: Karl London <karl@borg.demon.co.uk>
	Subject: Little bit to add to a readme for Linux for 8.6
	Date: Fri, 10 Sep 1993 20:16:05 +0100 (BST)

	Below is a copy of a section of the /usr/include/unistd.h from
	linux libc-4.4.1 which needs changing because of a bug in the
	header files. Should be fixed for future releases..

	Karl

	The #if 0 and #endif are new!!

	-------

	   If OPTS begins with `--', then non-option arguments
	   are treated as arguments to the option '\0'.
	   This behavior is specific to the GNU `getopt'.  */
	#if 0
	extern int getopt __P ((int __argc, char *__const * __argv,
				__const char *__opts));
	#endif
	extern int opterr;
	extern int optind;

A/UX
	Date: Tue, 12 Oct 1993 18:28:28 -0400 (EDT)
	From: "Eric C. Hagberg" <hagberg@med.cornell.edu>
	Subject: Fix for A/UX ndbm

	I guess this isn't really a sendmail bug, however, it is something
	that A/UX users should be aware of when compiling sendmail 8.6.

	Apparently, the calls that sendmail is using to the ndbm routines
	in A/UX 3.0.x contain calls to "broken" routines, in that the
	aliases database will break when it gets "just a little big"
	(sorry I don't have exact numbers here, but it broke somewhere
	around 20-25 aliases for me.), making all aliases non-functional
	after exceeding this point.

	What I did was to get the gnu-dbm-1.6 package, compile it, and
	then re-compile sendmail with "-lgdbm", "-DNDBM", and using the
	ndbm.h header file that comes with the gnu-package. This makes
	things behave properly.

	I suppose porting the New Berkeley db package is another route,
	however, I made a quick attempt at it, and found it difficult
	(not easy at least); the gnu-dbm package "configured" and
	compiled easily.

DG/UX
	Apparently, /bin/mail doesn't work properly for delivery on
	DG/UX -- the person who has this working, Douglas Anderson
	<dlander@afterlife.ncsc.mil>, used procmail instead.

Non-DNS based sites
	This version of sendmail always tries to connect to the Domain
	Name System (DNS) to resolve names, regardless of the setting
	of the `I' option.  On most systems that are not running DNS,
	this will fail quickly and sendmail will continue, but on some
	systems it has a long timeout.  If you have this problem, you
	will have to recompile without NAMED_BIND.  Some people have
	claimed that they have successfully used "OI+USEVC" to force
	sendmail to use a virtual circuit -- this will always time out
	quickly, but also tells sendmail that a failed connection
	should requeue the message (probably not what you intended).
	A future release of sendmail will correct this problem.

Both NEWDB and NDBM
	If you use both -DNDBM and -DNEWDB, you must delete the module
	ndbm.o from libdb.a and delete the file "ndbm.h" from the files
	that get installed (that is, use the OLD ndbm.h, not the new
	ndbm.h).  This compatibility module maps ndbm calls into DB
	calls, and breaks things rather badly.

GNU getopt
	I'm told that GNU getopt has a problem in that it gets confused
	by the double call.  Use the version in conf.c instead.


+--------------+
| MANUAL PAGES |
+--------------+

The manual pages have been written against the -mandoc macros
instead of the -man macros.  The latest version of groff has them
included.  You can also get a copy from FTP.UU.NET in directory
/systems/unix/bsd-sources/share/tmac.


+-----------------------------+
| DESCRIPTION OF SOURCE FILES |
+-----------------------------+

The following list describes the files in this directory:

Makefile	The makefile used here; this version only works with
		the new Berkeley make.
Makefile.dist	A trimmed down version of the makefile that works with
		the old make.
READ_ME		This file.
TRACEFLAGS	My own personal list of the trace flags -- not guaranteed
		to be particularly up to date.
alias.c		Does name aliasing in all forms.
arpadate.c	A subroutine which creates ARPANET standard dates.
clock.c		Routines to implement real-time oriented functions
		in sendmail -- e.g., timeouts.
collect.c	The routine that actually reads the mail into a temp
		file.  It also does a certain amount of parsing of
		the header, etc.
conf.c		The configuration file.  This contains information
		that is presumed to be quite static and non-
		controversial, or code compiled in for efficiency
		reasons.  Most of the configuration is in sendmail.cf.
conf.h		Configuration that must be known everywhere.
convtime.c	A routine to sanely process times.
daemon.c	Routines to implement daemon mode.  This version is
		specifically for Berkeley 4.1 IPC.
deliver.c	Routines to deliver mail.
domain.c	Routines that interface with DNS (the Domain Name
		System).
err.c		Routines to print error messages.
envelope.c	Routines to manipulate the envelope structure.
headers.c	Routines to process message headers.
macro.c		The macro expander.  This is used internally to
		insert information from the configuration file.
main.c		The main routine to sendmail.  This file also
		contains some miscellaneous routines.
map.c		Support for database maps.
mci.c		Routines that handle mail connection information caching.
parseaddr.c	The routines which do address parsing.
queue.c		Routines to implement message queueing.
readcf.c	The routine that reads the configuration file and
		translates it to internal form.
recipient.c	Routines that manipulate the recipient list.
savemail.c	Routines which save the letter on processing errors.
sendmail.h	Main header file for sendmail.
srvrsmtp.c	Routines to implement server SMTP.
stab.c		Routines to manage the symbol table.
stats.c		Routines to collect and post the statistics.
sysexits.c	List of error messages associated with error codes
		in sysexits.h.
trace.c		The trace package.  These routines allow setting and
		testing of trace flags with a high granularity.
udb.c		The user database interface module.
usersmtp.c	Routines to implement user SMTP.
util.c		Some general purpose routines used by sendmail.
version.c	The version number and information about this
		version of sendmail.  Theoretically, this gets
		modified on every change.

Eric Allman

(Version 8.33, last update 12/01/93 11:34:48)