SENDMAIL CONFIGURATION FILES This document describes the sendmail configuration files. It explains how to create a sendmail.cf file for use with sendmail. It also describes how to set options for sendmail which are explained in the Sendmail Installation and Operation guide (doc/op/op.me). To get started, you may want to look at tcpproto.mc (for TCP-only sites) and clientproto.mc (for clusters of clients using a single mail host), or the generic-*.mc files as operating system-specific examples. Table of Content: INTRODUCTION AND EXAMPLE A BRIEF INTRODUCTION TO M4 FILE LOCATIONS OSTYPE DOMAINS MAILERS FEATURES HACKS SITE CONFIGURATION USING UUCP MAILERS TWEAKING RULESETS MASQUERADING AND RELAYING USING LDAP FOR ALIASES, MAPS, AND CLASSES LDAP ROUTING ANTI-SPAM CONFIGURATION CONTROL STARTTLS SMTP AUTHENTICATION ADDING NEW MAILERS OR RULESETS ADDING NEW MAIL FILTERS QUEUE GROUP DEFINITIONS NON-SMTP BASED CONFIGURATIONS WHO AM I? ACCEPTING MAIL FOR MULTIPLE NAMES USING MAILERTABLES USING USERDB TO MAP FULL NAMES MISCELLANEOUS SPECIAL FEATURES SECURITY NOTES TWEAKING CONFIGURATION OPTIONS MESSAGE SUBMISSION PROGRAM FORMAT OF FILES AND MAPS DIRECTORY LAYOUT ADMINISTRATIVE DETAILS +--------------------------+ | INTRODUCTION AND EXAMPLE | +--------------------------+ Configuration files are contained in the subdirectory "cf", with a suffix ".mc". They must be run through "m4" to produce a ".cf" file. You must pre-load "cf.m4": m4 ${CFDIR}/m4/cf.m4 config.mc > config.cf Alternatively, you can simply: cd ${CFDIR}/cf ./Build config.cf where ${CFDIR} is the root of the cf directory and config.mc is the name of your configuration file. If you are running a version of M4 that understands the __file__ builtin (versions of GNU m4 >= 0.75 do this, but the versions distributed with 4.4BSD and derivatives do not) or the -I flag (ditto), then ${CFDIR} can be in an arbitrary directory. For "traditional" versions, ${CFDIR} ***MUST*** be "..", or you MUST use -D_CF_DIR_=/path/to/cf/dir/ -- note the trailing slash! For example: m4 -D_CF_DIR_=${CFDIR}/ ${CFDIR}/m4/cf.m4 config.mc > config.cf Let's examine a typical .mc file: divert(-1) # # Copyright (c) 1998-2002 Sendmail, Inc. and its suppliers. # All rights reserved. # Copyright (c) 1983 Eric P. Allman. All rights reserved. # Copyright (c) 1988, 1993 # The Regents of the University of California. All rights reserved. # # By using this file, you agree to the terms and conditions set # forth in the LICENSE file which can be found at the top level of # the sendmail distribution. # # # This is a Berkeley-specific configuration file for HP-UX 9.x. # It applies only to the Computer Science Division at Berkeley, # and should not be used elsewhere. It is provided on the sendmail # distribution as a sample only. To create your own configuration # file, create an appropriate domain file in ../domain, change the # `DOMAIN' macro below to reference that file, and copy the result # to a name of your own choosing. # divert(0) The divert(-1) will delete the crud in the resulting output file. The copyright notice can be replaced by whatever your lawyers require; our lawyers require the one that is included in these files. A copyleft is a copyright by another name. The divert(0) restores regular output. VERSIONID(`') VERSIONID is a macro that stuffs the version information into the resulting file. You could use SCCS, RCS, CVS, something else, or omit it completely. This is not the same as the version id included in SMTP greeting messages -- this is defined in m4/version.m4. OSTYPE(`hpux9')dnl You must specify an OSTYPE to properly configure things such as the pathname of the help and status files, the flags needed for the local mailer, and other important things. If you omit it, you will get an error when you try to build the configuration. Look at the ostype directory for the list of known operating system types. DOMAIN(`CS.Berkeley.EDU')dnl This example is specific to the Computer Science Division at Berkeley. You can use "DOMAIN(`generic')" to get a sufficiently bland definition that may well work for you, or you can create a customized domain definition appropriate for your environment. MAILER(`local') MAILER(`smtp') These describe the mailers used at the default CS site. The local mailer is always included automatically. Beware: MAILER declarations should always be at the end of the configuration file. The general rules are that the order should be: VERSIONID OSTYPE DOMAIN FEATURE local macro definitions MAILER LOCAL_CONFIG LOCAL_RULE_* LOCAL_RULESETS There are a few exceptions to this rule. Local macro definitions which influence a FEATURE() should be done before that feature. For example, a define(`PROCMAIL_MAILER_PATH', ...) should be done before FEATURE(`local_procmail'). ******************************************************************* *** BE SURE YOU CUSTOMIZE THESE FILES! They have some *** *** Berkeley-specific assumptions built in, such as the name *** *** of their UUCP-relay. You'll want to create your own *** *** domain description, and use that in place of *** *** domain/Berkeley.EDU.m4. *** ******************************************************************* +----------------------------+ | A BRIEF INTRODUCTION TO M4 | +----------------------------+ Sendmail uses the M4 macro processor to ``compile'' the configuration files. The most important thing to know is that M4 is stream-based, that is, it doesn't understand about lines. For this reason, in some places you may see the word ``dnl'', which stands for ``delete through newline''; essentially, it deletes all characters starting at the ``dnl'' up to and including the next newline character. In most cases sendmail uses this only to avoid lots of unnecessary blank lines in the output. Other important directives are define(A, B) which defines the macro ``A'' to have value ``B''. Macros are expanded as they are read, so one normally quotes both values to prevent expansion. For example, define(`SMART_HOST', `smart.foo.com') One word of warning: M4 macros are expanded even in lines that appear to be comments. For example, if you have # See FEATURE(`foo') above it will not do what you expect, because the FEATURE(`foo') will be expanded. This also applies to # And then define the $X macro to be the return address because ``define'' is an M4 keyword. If you want to use them, surround them with directed quotes, `like this'. Notice: ------- This package requires a post-V7 version of m4; if you are running the 4.2bsd, SysV.2, or 7th Edition version. SunOS's /usr/5bin/m4 or BSD-Net/2's m4 both work. GNU m4 version 1.1 or later also works. Unfortunately, the M4 on BSDI 1.0 doesn't work -- you'll have to use a Net/2 or GNU version. GNU m4 is available from ftp://ftp.gnu.org/pub/gnu/m4/m4-1.4.tar.gz (check for the latest version). EXCEPTIONS: DEC's m4 on Digital UNIX 4.x is broken (3.x is fine). Use GNU m4 on this platform. +----------------+ | FILE LOCATIONS | +----------------+ sendmail 8.9 has introduced a new configuration directory for sendmail related files, /etc/mail. The new files available for sendmail 8.9 -- the class {R} /etc/mail/relay-domains and the access database /etc/mail/access -- take advantage of this new directory. Beginning with 8.10, all files will use this directory by default (some options may be set by OSTYPE() files). This new directory should help to restore uniformity to sendmail's file locations. Below is a table of some of the common changes: Old filename New filename ------------ ------------ /etc/bitdomain /etc/mail/bitdomain /etc/domaintable /etc/mail/domaintable /etc/genericstable /etc/mail/genericstable /etc/uudomain /etc/mail/uudomain /etc/virtusertable /etc/mail/virtusertable /etc/userdb /etc/mail/userdb /etc/aliases /etc/mail/aliases /etc/sendmail/aliases /etc/mail/aliases /etc/ucbmail/aliases /etc/mail/aliases /usr/adm/sendmail/aliases /etc/mail/aliases /usr/lib/aliases /etc/mail/aliases /usr/lib/mail/aliases /etc/mail/aliases /usr/ucblib/aliases /etc/mail/aliases /etc/sendmail.cw /etc/mail/local-host-names /etc/mail/sendmail.cw /etc/mail/local-host-names /etc/sendmail/sendmail.cw /etc/mail/local-host-names /etc/sendmail.ct /etc/mail/trusted-users /etc/sendmail.oE /etc/mail/error-header /etc/sendmail.hf /etc/mail/helpfile /etc/mail/sendmail.hf /etc/mail/helpfile /usr/ucblib/sendmail.hf /etc/mail/helpfile /etc/ucbmail/sendmail.hf /etc/mail/helpfile /usr/lib/sendmail.hf /etc/mail/helpfile /usr/share/lib/sendmail.hf /etc/mail/helpfile /usr/share/misc/sendmail.hf /etc/mail/helpfile /share/misc/sendmail.hf /etc/mail/helpfile /etc/service.switch /etc/mail/service.switch /etc/sendmail.st /etc/mail/statistics /etc/mail/sendmail.st /etc/mail/statistics /etc/mailer/sendmail.st /etc/mail/statistics /etc/sendmail/sendmail.st /etc/mail/statistics /usr/lib/sendmail.st /etc/mail/statistics /usr/ucblib/sendmail.st /etc/mail/statistics Note that all of these paths actually use a new m4 macro MAIL_SETTINGS_DIR to create the pathnames. The default value of this variable is `/etc/mail/'. If you set this macro to a different value, you MUST include a trailing slash. Notice: all filenames used in a .mc (or .cf) file should be absolute (starting at the root, i.e., with '/'). Relative filenames most likely cause surprises during operations (unless otherwise noted). +--------+ | OSTYPE | +--------+ You MUST define an operating system environment, or the configuration file build will puke. There are several environments available; look at the "ostype" directory for the current list. This macro changes things like the location of the alias file and queue directory. Some of these files are identical to one another. It is IMPERATIVE that the OSTYPE occur before any MAILER definitions. In general, the OSTYPE macro should go immediately after any version information, and MAILER definitions should always go last. Operating system definitions are usually easy to write. They may define the following variables (everything defaults, so an ostype file may be empty). Unfortunately, the list of configuration-supported systems is not as broad as the list of source-supported systems, since many of the source contributors do not include corresponding ostype files. ALIAS_FILE [/etc/mail/aliases] The location of the text version of the alias file(s). It can be a comma-separated list of names (but be sure you quote values with commas in them -- for example, use define(`ALIAS_FILE', `a,b') to get "a" and "b" both listed as alias files; otherwise the define() primitive only sees "a"). HELP_FILE [/etc/mail/helpfile] The name of the file containing information printed in response to the SMTP HELP command. QUEUE_DIR [/var/spool/mqueue] The directory containing queue files. To use multiple queues, supply a value ending with an asterisk. For example, /var/spool/mqueue/qd* will use all of the directories or symbolic links to directories beginning with 'qd' in /var/spool/mqueue as queue directories. The names 'qf', 'df', and 'xf' are reserved as specific subdirectories for the corresponding queue file types as explained in doc/op/op.me. See also QUEUE GROUP DEFINITIONS. MSP_QUEUE_DIR [/var/spool/clientmqueue] The directory containing queue files for the MSP (Mail Submission Program, see sendmail/SECURITY). STATUS_FILE [/etc/mail/statistics] The file containing status information. LOCAL_MAILER_PATH [/bin/mail] The program used to deliver local mail. LOCAL_MAILER_FLAGS [Prmn9] The flags used by the local mailer. The flags lsDFMAw5:/|@q are always included. LOCAL_MAILER_ARGS [mail -d $u] The arguments passed to deliver local mail. LOCAL_MAILER_MAX [undefined] If defined, the maximum size of local mail that you are willing to accept. LOCAL_MAILER_MAXMSGS [undefined] If defined, the maximum number of messages to deliver in a single connection. Only useful for LMTP local mailers. LOCAL_MAILER_CHARSET [undefined] If defined, messages containing 8-bit data that ARRIVE from an address that resolves to the local mailer and which are converted to MIME will be labeled with this character set. LOCAL_MAILER_EOL [undefined] If defined, the string to use as the end of line for the local mailer. LOCAL_MAILER_DSN_DIAGNOSTIC_CODE [X-Unix] The DSN Diagnostic-Code value for the local mailer. This should be changed with care. LOCAL_SHELL_PATH [/bin/sh] The shell used to deliver piped email. LOCAL_SHELL_FLAGS [eu9] The flags used by the shell mailer. The flags lsDFM are always included. LOCAL_SHELL_ARGS [sh -c $u] The arguments passed to deliver "prog" mail. LOCAL_SHELL_DIR [$z:/] The directory search path in which the shell should run. LOCAL_MAILER_QGRP [undefined] The queue group for the local mailer. USENET_MAILER_PATH [/usr/lib/news/inews] The name of the program used to submit news. USENET_MAILER_FLAGS [rsDFMmn] The mailer flags for the usenet mailer. USENET_MAILER_ARGS [-m -h -n] The command line arguments for the usenet mailer. NOTE: Some versions of inews (such as those shipped with newer versions of INN) use different flags. Double check the defaults against the inews man page. USENET_MAILER_MAX [100000] The maximum size of messages that will be accepted by the usenet mailer. USENET_MAILER_QGRP [undefined] The queue group for the usenet mailer. SMTP_MAILER_FLAGS [undefined] Flags added to SMTP mailer. Default flags are `mDFMuX' for all SMTP-based mailers; the "esmtp" mailer adds `a'; "smtp8" adds `8'; and "dsmtp" adds `%'. RELAY_MAILER_FLAGS [undefined] Flags added to the relay mailer. Default flags are `mDFMuX' for all SMTP-based mailers; the relay mailer adds `a8'. If this is not defined, then SMTP_MAILER_FLAGS is used. SMTP_MAILER_MAX [undefined] The maximum size of messages that will be transported using the smtp, smtp8, esmtp, or dsmtp mailers. SMTP_MAILER_MAXMSGS [undefined] If defined, the maximum number of messages to deliver in a single connection for the smtp, smtp8, esmtp, or dsmtp mailers. SMTP_MAILER_MAXRCPTS [undefined] If defined, the maximum number of recipients to deliver in a single connection for the smtp, smtp8, esmtp, or dsmtp mailers. SMTP_MAILER_ARGS [TCP $h] The arguments passed to the smtp mailer. About the only reason you would want to change this would be to change the default port. ESMTP_MAILER_ARGS [TCP $h] The arguments passed to the esmtp mailer. SMTP8_MAILER_ARGS [TCP $h] The arguments passed to the smtp8 mailer. DSMTP_MAILER_ARGS [TCP $h] The arguments passed to the dsmtp mailer. RELAY_MAILER_ARGS [TCP $h] The arguments passed to the relay mailer. SMTP_MAILER_QGRP [undefined] The queue group for the smtp mailer. ESMTP_MAILER_QGRP [undefined] The queue group for the esmtp mailer. SMTP8_MAILER_QGRP [undefined] The queue group for the smtp8 mailer. DSMTP_MAILER_QGRP [undefined] The queue group for the dsmtp mailer. RELAY_MAILER_QGRP [undefined] The queue group for the relay mailer. RELAY_MAILER_MAXMSGS [undefined] If defined, the maximum number of messages to deliver in a single connection for the relay mailer. SMTP_MAILER_CHARSET [undefined] If defined, messages containing 8-bit data that ARRIVE from an address that resolves to one of the SMTP mailers and which are converted to MIME will be labeled with this character set. UUCP_MAILER_PATH [/usr/bin/uux] The program used to send UUCP mail. UUCP_MAILER_FLAGS [undefined] Flags added to UUCP mailer. Default flags are `DFMhuU' (and `m' for uucp-new mailer, minus `U' for uucp-dom mailer). UUCP_MAILER_ARGS [uux - -r -z -a$g -gC $h!rmail ($u)] The arguments passed to the UUCP mailer. UUCP_MAILER_MAX [100000] The maximum size message accepted for transmission by the UUCP mailers. UUCP_MAILER_CHARSET [undefined] If defined, messages containing 8-bit data that ARRIVE from an address that resolves to one of the UUCP mailers and which are converted to MIME will be labeled with this character set. UUCP_MAILER_QGRP [undefined] The queue group for the UUCP mailers. FAX_MAILER_PATH [/usr/local/lib/fax/mailfax] The program u