****************************************************************************** File: sendmail.txt Version 3.0 16-Apr-1995 Niel Kempson ****************************************************************************** Configuring sendmail for use with the Warp Internet Access Kit ============================================================== Contents -------- 1. Introduction 2. Assumptions 3. Configuring sendmail 3.1 What's in a name ? 3.2 Customising the sendmail configuration file 3.3 Delivering mail to UltiMail/2 3.4 Delivering mail to LAMail 3.5 The TZ environment variable 4. The HOSTS file 5. Sendmail aliases 6. Running the sendmail daemon 7. Testing your sendmail setup 8. Sendmail error codes 9. Frequently encountered problems (FEPs) 10. What if it still doesn't work ? 11. Useful references 12. Change log 1. Introduction --------------- Please make sure that you have read the accompanying file 00README.TXT which explains the purpose of this kit. The critical link in the SMTP chain is the sendmail.exe program. It delivers outgoing messages using SMTP and also acts as a server waiting for incoming messages. This document tells describes how to configure sendmail to work on your Warp/IAK system to exchange mail with the outside world using SMTP. The instructions are by no means comprehensive and they are probably unclear in places so please feed back any constructive suggestions (including typos) so that I can improve this kit. All of the information in this guide has been gleaned from books, examination of binary files etc. There's nothing in here that could possibly be construed as official IBM information. 2. Assumptions -------------- Throughout this document I have assumed that the IAK software has been installed under the C:\TCPIP directory. If you have not installed it in this directory, you will need to adjust the examples quoting path specifications to suit your system setup. The sendmail specific file sendmail.uml contains path specifications so please check it carefully if your setup isn't installed in the default location. 3. Configuring sendmail ----------------------- Sendmail's behaviour is largely defined by a single configuration file, the contents of which resemble a knitting pattern! The Warp IAK does not provide a working sendmail configuration file for use with SMTP mail, so I have included my working configuration file. It was derived from the standard configuration provided with IBM TCP/IP, which in turn was derived from the Berkeley Unix distribution. 3.1 What's in a name ? ---------------------- When sendmail starts, it looks for a configuration file. If a file is not explicitly specified, sendmail assumes a default name for the configuration file of c:\tcpip\etc\sendmail.cf. On Unix systems, the default file is /etc/sendmail.cf, and for this reason sendmail configuration files are often called "sendmail.cf" files. The actual file used can be specified on the sendmail command line using the -C qualifier: sendmail # use c:\tcpip\etc\sendmail.cf sendmail -Cxx.yy # use xx.yy sendmail -Cc:\tcpip\etc\sendmail.uml # use c:\tcpip\etc\sendmail.uml To complicate matters, UltiMail/2 (and News Reader/2) always invoke sendmail with the -Cc:\tcpip\etc\sendmail.uml qualifier to force sendmail to use a non-default configuration file. In contrast, LAMail (the mailer provided with IBM TCP/IP) doesn't explicitly specify a configuration file when invoking sendmail - it leaves sendmail to use its default. In this kit, you may see references to sendmail.cf and sendmail.uml which are confusing. The contents of the file tell sendmail how to behave, the name of the file used by sendmail is determined by the command line used to start it. Sendmail started by Configuration file used ----------------------------------------------------------------- LAMail c:\tcpip\etc\sendmail.cf News Reader/2 c:\tcpip\etc\sendmail.uml UltiMail/2 c:\tcpip\etc\sendmail.uml sendmail c:\tcpip\etc\sendmail.cf sendmail -Cc:\tcpip\etc\sendmail.uml c:\tcpip\etc\sendmail.uml (The last two are examples of starting sendmail from the command line.) If you're in any doubt, just copy sendmail.uml to sendmail.cf but remember to keep the two in step. 3.2 Customising the sendmail configuration file ----------------------------------------------- This kit includes an example configuration file (sendmail.uml) that I use to allow UltiMail/2 Lite to work as an SMTP client rather than the usual POP client. As supplied, the configuration file supports: o my official host name: snowyowl.demon.co.uk o mail also accepted for other aliases: sos-gate.demon.co.uk, snowyowl.com, snowyowl.co.uk & sos.co.uk o IBM Warp IAK installed in c:\tcpip o all outgoing mail is sent to post.demon.co.uk for onward routing and delivery You will need to edit this file and customise it for your setup. NOTE: You must use an editor that preserves TAB characters. Do NOT use the EPM or TEDIT editors that come with OS/2 - they expand TABs into spaces and will cause the configuration file to be useless. The E editor is OK. Search for the string "---EDIT---" in this file and edit the following line(s) in accordance with the notes in the adjacent comment block. There are 10 occurrences of "---EDIT---" to check. PLEASE make sure that you check each of them before firing up sendmail. The changes that you need to make are summarised below: EDIT---01 define the name of your host (without any domain appended), plus any aliases within the same domain for which you will accept incoming mail. NOTE: You must define the 'Cw' macro as well as the 'Dw' macro. 9 out of 10 problems reported by people with umsmtp02 were caused by not defining Cw. I hope that the sendmail.uml file is now totally clear in this respect. EDIT---02 define the domain in which your host lives. EDIT---03 define the "smart" mail relay, to which you send all outgoing mail for onward transmission. EDIT---04 define the location of the sendmail aliases file. EDIT---05 define the location of the sendmail help text file. EDIT---06 define the directory holding mail messages queued for transmission. EDIT---07 define the location of the sendmail statistics file. EDIT---08 define any aliases in another domain for which you will accept incoming mail. NOTE: most people don't have more than one domain name and therefore will not want to enable this option. EDIT---09 define any aliases in another domain for which you will accept incoming mail. NOTE: most people don't have more than one domain name and therefore will not want to enable this option. EDIT---10 define the command used to deliver incoming messages to your local mail program (e.g. UltiMail/2, LAMail). NOTE: make sure that the Mlocal definition is all on one (long) line. Do not allow your editor to wrap it over two lines. Remember that the sendmail.uml contains notes above each of the "EDIT---" points, explaining what you need to do. If they are unclear, please let me know. 3.3 Delivering mail to UltiMail/2 ---------------------------------- If you use UltiMail/2 as your local mail program, you need to: o make sure that you have selected the appropriate "Mlocal" line under "EDIT---10" to call the umailer.exe program. o copy the configured sendmail.uml to c:\tcpip\etc\sendmail.uml. o copy sendmail.hf to c:\tcpip\etc\sendmail.hf. o read the accompanying file ultimail.txt 3.4 Delivering mail to LAMail ------------------------------ If you use LAMail as your local mail program, you need to: o make sure that you have selected the appropriate "Mlocal" line under "EDIT---10" to call the mail.exe program. o copy the configured sendmail.uml to c:\tcpip\etc\sendmail.cf. o copy sendmail.hf to c:\tcpip\etc\sendmail.hf. 3.5 The TZ environment variable -------------------------------- OS/2 itself does not appear to support timezones, but many applications use the TZ environment variable to determine the local timezone and adapt accordingly. Sendmail uses TZ, but if it is not defined, it assumes US West Coast time. When your sendmail handles a message, it inserts a "Received:" line into the message header block like this: Received: by yourhost.your.domain (IBM OS/2 SENDMAIL VERSION 1.3.6)/(3.0sos) id AA0019; Sun, 16 Apr 95 19:21:15 BST The "19:21:15 BST" indicates that sendmail thinks it is in the UK, operating under British Summer time (GMT + 0100). If the TZ environment variable has not bee set, the header will look like: Received: by yourhost.your.domain (IBM OS/2 SENDMAIL VERSION 1.3.6)/(3.0sos) id AA0019; Sun, 16 Apr 95 19:21:15 -0800 where the "-0800" indicates 8 hours behind GMT. It's best to set TZ in your CONFIG.SYS file so that all TZ-aware applications can determine your local time zone. The command to use is SET TZ=SSSwwDDD where SSS the three letter abbreviation of the timezone. ww the number of hours WEST of GMT (Universal Time) in this timezone. Timezones EAST of GMT have negative values. DDD (optional) the three letter abbreviation of the timezone when daylight saving time is in effect. If this part of the string is not present it is assumed that daylight saving time is never in effect. Examples of valid TZ settings (though the names may be wrong) are: SET TZ=NST-12NDT New Zealand Time SET TZ=EET-2EST East European Time SET TZ=CET-1CST Central European Time SET TZ=UTC0 Coordinated universal time (GMT) SET TZ=GMT0BST Greenwich Mean Time, British Summer Time SET TZ=AST4ADT US Atlantic Standard Time SET TZ=EST5EDT US Eastern Standard Time SET TZ=CST6CDT US Central Standard Time SET TZ=MST7MDT US Mountain Standard Time SET TZ=PST8PDT US Pacific Standard Time SET TZ=YST9YDT Yukon Standard Time SET TZ=HST10HDT Hawaii Standard Time 4. The HOSTS file ----------------- When connected to the Internet, you will normally use the Domain Name Service (DNS) to resolve host names and addresses. When you try to queue or deliver a mail message, sendmail attempts to resolve the IP address of destination host. If your dial-up link isn't running, sendmail will be unable to access the DNS to resolve the host and will bounce the message with an "error 68 - unknown host" message. If the DNS is unavailable, IBM TCP/IP will look in the c:\tcpip\etc\hosts file for the host name. Since you can't reasonably put all possible destination hosts in your hosts file, the best way to avoid this problem is always to send outgoing mail via a "smart" mail host and make sure that this host is included in the hosts file. Make sure that the DV macro is defined in sendmail.uml to send mail via a "smart" mail host, usually your provider's mail host, and make sure that this host is defined in the hosts file. A minimum hosts file would be: 127.0.0.1 localhost a.b.c.d yourhost.your.domain yourhost # change this line w.x.y.z smart.mail.host # change this line I strongly recommend that you create such a hosts file. For Demon Internet subscribers, I strongly recommend that you route all outgoing mail via post.demon.co.uk and edit your sendmail.uml and hosts files to contain these entries: sendmail.uml: #---EDIT---03--- DVpost.demon.co.uk hosts: 127.0.0.1 localhost 158.152.1.72 post.demon.co.uk post 158.152.x.y yourhost.demon.co.uk yourhost # change this line 5. Sendmail aliases ------------------- Sendmail supports an optional external alias file to allow redirection of SMTP mail. By default, the alias file is c:\tcpip\etc\aliases and is in the following format: # # Comment lines begin with hashes # alias: real-address alias: real-1,real-2 The alias must be a local name (i.e. no "@" in the name), but the real-address part can be non-local. Aliases are not case-sensitive, but aliases referenced by other aliases MUST be lower case. You can use the aliases file to ensure that incoming mail is routed to a single mailbox: # Alias file postmaster: kempson root: kempson MAILER-DAEMON: kempson help: kempson,smith If you are using your dial-up machine as a mail gateway between a local network and the Internet, the alias file provides a convenient means of forwarding incoming mail to the internal network users. It's a good idea to alias postmaster (which every Internet host must support) to your normal e-mail address. For example, Internet mail to snowyowl.com users will arrive via the PPP/SLIP connection and then could be forwarded to systems on the internal network by using an alias file like: # Alias file postmaster: kempson help: kempson,smith kempson: kempson@host1.snowyowl.com jones: jones@host2.snowyowl.com smith: smith@host2.snowyowl.com When sending out mail, the user systems should ensure that the "Reply-To" address is set to that of the dial-up gateway: Reply-to: John Smith and that the local machines forward their mail to the dial-up gateway for onward delivery. Remember that the aliases file is optional - sendmail will function perfectly well if you don't feel the need to create one. For Unix users, there is no equivalent to the "newaliases" or "sendmail -bi" commands to build an indexed database of aliases - the alias file is read each time sendmail is started. 6. Running the sendmail daemon ------------------------------ To receive SMTP mail, your system must be running the sendmail daemon when the dial-up connection to the Internet is active. It will listen for incoming SMTP connections (receiving mail) and will periodically examine the local mail queue and attempt to send any messages waiting there. The command used to start the sendmail daemon is: c:\tcpip\bin\sendmail -Cc:\tcpip\etc\sendmail.uml -d1.1 -bd -q5m where the options mean: -Cc:\tcpip\etc\sendmail.uml specify the configuration file -d1.1 log incoming messages ("-d" generates *lots* of debugging information) -bd run in background ('daemon') mode -q5m check the outgoing queue every 5 minutes You need to start the sendmail daemon *after* the PPP/SLIP connection is up and running. If you try to start it beforehand, sendmail will stop with the error message "TCP/IP not functioning; exit sendmail". A convenient place to start sendmail is in a separate command file that tests to see if the link is up and running before launching any network applications. The file should look something like: ECHO Waiting for SLIP link to start ... slipwait 600 IF ERRORLEVEL 1 GOTO noslip ECHO SLIP link is running, starting sendmail ... start /n sendmail -Cc:\tcpip\etc\sendmail.uml -d1.1 -bd -q5m GOTO exitlabel :noslip ECHO SLIP not running - no daemons started :exitlabel In this example, SLIPWAIT waits for up to 600 seconds to see if the SLIP connection is running. If it is, SLIPWAIT exits with an ERRORLEVEL of 0, otherwise an ERRORLEVEL of 1 indicates that the link has not been started. The bad news is that SLIPWAIT does not detect when a PPP link has been successfully established and IBM hasn't provided a PPPWAIT command :-( IBM's sendmail is broadly compatible with the Unix implementations of sendmail v5.65, but not the newer sendmail v8. Some of the command line options available are: -bd, -bt, -C, -d, -d#.#, -q