Lyris Technologies, Inc. 2070 Allston Way, Suite 101 Berkeley, CA 94704 510-549-4350 Fax: (510) 549-4351 http://www.lyristechnologies.com Introduction 1 Contents Introduction 7 What is MailShield?............................................................................................................. 7 Overview................................................................................................................ 7 How MailShield Works .......................................................................................... 7 MailShield and your Mail Server ............................................................................ 7 Installation 9 Configure MailShield........................................................................................................... 9 Installing on Windows........................................................................................................ 11 Upgrading on Windows ........................................................................................ 11 Uninstalling on Windows...................................................................................... 12 Installing on Unix .............................................................................................................. 12 Upgrading on Unix............................................................................................... 13 Uninstalling on Unix ............................................................................................ 14 High Mail Loads on Unix ..................................................................................... 15 Automatic Restart on Unix ................................................................................... 16 Starting MailShield ............................................................................................................ 16 Command-Line Options ..................................................................................................... 17 Logging Options................................................................................................... 18 Windows NT Service............................................................................................ 19 Windows 95 Service............................................................................................. 19 Unix Background Daemon.................................................................................... 19 Feature Reference 21 Always Approve ................................................................................................................ 21 Approved MAIL FROM: text ............................................................................... 21 Approved RCPT TO: text ..................................................................................... 21 Approved To: Header text..................................................................................... 22 Banned .............................................................................................................................. 22 Banned From: header............................................................................................ 22 Banned HELO text ............................................................................................... 22 Banned MAIL FROM: text ................................................................................... 22 Banned MIME Filename text ................................................................................ 23 Banned RCPT TO: text......................................................................................... 23 Banned Received: header text ............................................................................... 23 Banned Subject: prefix.......................................................................................... 23 Banned Subject: text ............................................................................................. 24 Banned TCP/IP addresses ..................................................................................... 24 Banned To: text .................................................................................................... 24 Banned X-Mailer: text .......................................................................................... 24 Banned body text.................................................................................................. 24 Banned domain names.......................................................................................... 25 Banned header text ............................................................................................... 25 Introduction 2 Banned message text ............................................................................................ 25 Basic Configuration ........................................................................................................... 25 Admin email address ............................................................................................ 25 Admin Interface Port Number............................................................................... 26 Admin Interface TCP/IP Address.......................................................................... 26 Admin Interface Password.................................................................................... 26 Append text to SMTP welcome message............................................................... 26 Canonize From: addresses..................................................................................... 27 Check Recipient Addresses Dynamically .............................................................. 27 Configuration reload check................................................................................... 28 DNS servers ......................................................................................................... 29 Disable Reverse DNS ........................................................................................... 29 Helpful refuse message......................................................................................... 30 Large messages pass-through................................................................................ 30 Local domain names............................................................................................. 31 Mail Merge Support ............................................................................................. 31 MailShield server activation code.......................................................................... 32 SMTP receive port................................................................................................ 32 SMTP server ........................................................................................................ 33 Simultaneous Connection Limit ............................................................................ 33 TCP/IP addresses.................................................................................................. 33 Counter Measures .............................................................................................................. 34 Tarpit Excessive RCPT TO:.................................................................................. 34 Hostnames to tarpit............................................................................................... 34 Slow if too many recipients................................................................................... 35 TCP/IP addresses to tarpit..................................................................................... 36 Tarpit delay.......................................................................................................... 36 Enforce Internet standards .................................................................................................. 37 Reject no Date: header.......................................................................................... 37 Reject no From: header......................................................................................... 37 Reject no Subject: header...................................................................................... 37 Reject no To: header............................................................................................. 38 Reject no hostname............................................................................................... 38 Require valid host for HELO................................................................................ 38 Filter Results...................................................................................................................... 39 Append helpful info.............................................................................................. 39 Backup mail server ............................................................................................... 39 Forward rejected mail........................................................................................... 40 Mark subject instead of refusing ........................................................................... 41 Junk Mail Detection........................................................................................................... 41 DUL: Block Dialup Users..................................................................................... 41 Max Received: HELO text size............................................................................. 42 RBL+ Service....................................................................................................... 42 Realtime Blackhole List........................................................................................ 43 Relay Spam Stopper ............................................................................................. 44 Reject empty MAIL FROM.................................................................................. 44 Reject empty MAIL FROM with multiple recipients ............................................. 45 Reject forged Date:............................................................................................... 45 Reject forged Message-Id ..................................................................................... 45 Reject invalid From: header .................................................................................. 46 Reject invalid MAIL FROM................................................................................. 46 Reject invalid To: header ...................................................................................... 47 Reject source routed mail...................................................................................... 47 Reject very long attachment filenames .................................................................. 48 Limits ................................................................................................................................ 48 Max message lines................................................................................................ 48 Introduction 3 Max message size................................................................................................. 49 Max recipients...................................................................................................... 49 Maximum RCPT TO recipients............................................................................. 49 Logging ............................................................................................................................. 49 Log Level............................................................................................................. 49 Log filename ........................................................................................................ 50 System Log .......................................................................................................... 50 Mail Relaying .................................................................................................................... 51 Hostnames to allow relaying................................................................................. 51 Reject unauthorized relaying................................................................................. 51 TCP/IP addresses allow to relay............................................................................ 52 Working with Mail Servers 53 Generic Setup with 2 Machines .......................................................................................... 53 Sendmail............................................................................................................................ 54 Forward to Another Address................................................................................. 54 Forward to Another Port ....................................................................................... 56 Forward to Another Machine ................................................................................ 57 Post.Office......................................................................................................................... 57 MDaemon.......................................................................................................................... 58 Qmail................................................................................................................................. 59 MetaInfo Sendmail............................................................................................................. 60 Netscape Mail Server ......................................................................................................... 61 MailSite............................................................................................................................. 62 Exim.................................................................................................................................. 63 NTmail .............................................................................................................................. 64 Microsoft IMS / IIS Mail.................................................................................................... 65 Lotus Notes r4.61............................................................................................................... 66 Lotus Domino r5................................................................................................................ 67 Microsoft Exchange ........................................................................................................... 68 AltaVista Mail ................................................................................................................... 68 SLMail .............................................................................................................................. 69 LSMTP.............................................................................................................................. 70 Imail .................................................................................................................................. 71 Frequently Asked Questions 73 Common Questions............................................................................................................ 73 What does MailShield Do? ................................................................................... 73 How does MailShield work?................................................................................. 73 Does it work with everything? .............................................................................. 74 Why is Relaying a problem? ................................................................................. 74 Can it protect against Relaying?............................................................................ 75 Will it slow mail down?........................................................................................ 76 Will it add to my overhead?.................................................................................. 76 How effective is it?............................................................................................... 76 What is the false-positive rate?.............................................................................. 76 Can Legitimate mail be rejected? .......................................................................... 77 What if I reject legitimate mail?............................................................................ 78 Can it be less aggressive?...................................................................................... 78 What about Mailing Lists?.................................................................................... 78 What about Usenet Spam?.................................................................................... 79 Does MailShield help ISP's? ................................................................................. 79 Does MailShield help Users? ................................................................................ 80 What about Users in the Field? ............................................................................. 80 Introduction 4 Does MailShield have other uses?......................................................................... 80 Is this different from Sendmail?............................................................................ 81 What about Outgoing Mail?.................................................................................. 81 What about dialup accounts?................................................................................. 81 Can it protect my children?................................................................................... 82 Is this the end of spam?......................................................................................... 82 Can Spammers Bypass MailShield?...................................................................... 83 What about Legislation? ....................................................................................... 83 How can I buy MailShield?................................................................................... 84 Answers for Power Users ................................................................................................... 84 About Regular Expressions................................................................................... 84 Blocking Email Attachments ................................................................................ 85 Save All Mail in Text Files ................................................................................... 85 Virtual Domains ................................................................................................... 86 User-specific Settings........................................................................................... 88 Troubleshooting................................................................................................................. 88 Test Messages not being refused........................................................................... 88 DNS Problems...................................................................................................... 89 Error: Unable to listen .......................................................................................... 90 The MailShield Language 91 What is it?.......................................................................................................................... 91 MailShield Rule Scripts...................................................................................................... 91 Mail Information Variables ................................................................................................ 93 Common Mistakes ............................................................................................................. 94 Limitations......................................................................................................................... 94 MailShield Language Reference ......................................................................................... 95 Accept.................................................................................................................. 95 Add - +................................................................................................................. 95 And - &&............................................................................................................. 95 AppendFile........................................................................................................... 96 Array2String ........................................................................................................ 96 Array assignment.................................................................................................. 96 Array reference..................................................................................................... 97 Associative array assignment ................................................................................ 97 Associative Array reference.................................................................................. 97 Assoc2String........................................................................................................ 97 BodyPrepend........................................................................................................ 97 chdir..................................................................................................................... 98 Chop .................................................................................................................... 98 Chr....................................................................................................................... 98 CommitData......................................................................................................... 98 CommitHeaderBody............................................................................................. 98 CommitHeaders.................................................................................................... 99 CommitSmtpData................................................................................................. 99 Continue............................................................................................................... 99 CountOccurence................................................................................................... 99 CountRecipients ................................................................................................... 99 CreateFile........................................................................................................... 100 DisableLogType ................................................................................................. 100 DisplayAssoc...................................................................................................... 101 DisplayArray...................................................................................................... 101 DNSALookup .................................................................................................... 101 DNSCnameLookup ............................................................................................ 101 DNSMXLookup................................................................................................. 101 Introduction 5 DNSRBLLookup................................................................................................ 101 DNSRevLookup................................................................................................. 102 Do...................................................................................................................... 102 DomainFromEmail............................................................................................. 102 EmailAddressValid ............................................................................................ 102 EmailDomainValid............................................................................................. 103 EnableLogType .................................................................................................. 103 eq....................................................................................................................... 103 Exists ................................................................................................................. 104 Exit .................................................................................................................... 104 Extract ............................................................................................................... 104 ExtractEmailAddress.......................................................................................... 104 FileToArray........................................................................................................ 105 FileToAssoc ....................................................................................................... 105 Greater Than, Less Than..................................................................................... 105 Hangup .............................................................................................................. 106 HeaderAppend ................................................................................................... 106 HeaderDeleteKey ............................................................................................... 106 HeaderExists ...................................................................................................... 106 HeaderGet .......................................................................................................... 107 HeaderGetAll ..................................................................................................... 107 HeaderMimeGetAllArray ................................................................................... 107 HeaderSet........................................................................................................... 108 if ........................................................................................................................ 108 Index Command................................................................................................. 109 IpInRange .......................................................................................................... 110 IsIpAddress ........................................................................................................ 111 IsOnRbl.............................................................................................................. 111 IpToHostname.................................................................................................... 112 Join.................................................................................................................... 112 Keys................................................................................................................... 112 Length................................................................................................................ 112 LogMessage ....................................................................................................... 113 LongestLength ................................................................................................... 113 LongestLengthInArray........................................................................................ 114 Message ............................................................................................................. 114 MessageAppend ................................................................................................. 114 NameFromEmail ................................................................................................ 114 ne....................................................................................................................... 114 Not - ! ................................................................................................................ 115 Numeric equality................................................................................................ 115 Numeric inequality............................................................................................. 115 Or - ||.................................................................................................................. 115 PickRandom....................................................................................................... 116 Pop..................................................................................................................... 116 Print ................................................................................................................... 116 Push................................................................................................................... 116 RandomString .................................................................................................... 117 ReadFile............................................................................................................. 117 Regindex Command ........................................................................................... 117 Regular expressions............................................................................................ 119 Refuse................................................................................................................ 120 Require .............................................................................................................. 120 Return................................................................................................................ 120 Scalar variable assignment.................................................................................. 120 SendBCCNow.................................................................................................... 121 Introduction 6 SendEmail.......................................................................................................... 121 Shift ................................................................................................................... 121 Sleep.................................................................................................................. 122 Split ................................................................................................................... 122 String concatenation........................................................................................... 122 Substr................................................................................................................. 123 Subroutine definitions......................................................................................... 123 Subtract - - ......................................................................................................... 123 System............................................................................................................... 124 TRUE and FALSE.............................................................................................. 124 Undef ................................................................................................................. 124 Unshift ............................................................................................................... 124 Upper Lower Case.............................................................................................. 125 Values................................................................................................................ 125 Appendix 127 What is new in this version?............................................................................................. 127 New in Version 2.0............................................................................................. 127 New in Version 1.5............................................................................................. 128 New In Version 1.1 ............................................................................................ 132 New in Version 1.04........................................................................................... 133 New in Version 1.0 beta 3................................................................................... 133 New in Version 1.0 beta 2................................................................................... 135 Operating System Platforms ............................................................................................. 136 Software License Agreement ............................................................................................ 136 Introduction 7 Introduction What is MailShield? Overview MailShield is a general purpose Internet mail filtering tool. It can be used to block junk mail, prohibit mail relaying, diffuse mail bomb attacks and other mail filtering tasks, such as intelligent routing and automatic responses. How MailShield Works MailShield works by accepting mail on behalf of your regular mail server. The mail that is acceptable is automatically forwarded to your mail server for regular delivery. MailShield refuses the mail that is unacceptable. You can also have MailShield redirect, tag or rewrite mail that is being delivered. Internet mail is delivered by using a TCP/IP protocol called SMTP. When someone tries to send mail to you, they are making a TCP/IP connection to you, and they are exchanging SMTP commands. At each step of the SMTP command exchange, MailShield checks its rules to see if there is any action which should be taken. These rules are scripts written in the MailShield Language. Most users do not need to edit these scripts, as the default scripts work well for most users. If you are a power user, however, you can change the scripts to do anything you like. Such as, completely control how MailShield processes mail. The scripts are written in a language called "The MailShield Language", which is a simple language, very similar to a subset of the Perl Language. MailShield and your Mail Server Instead of your mail server receiving mail, MailShield receives mail on behalf of your mail server and forwards acceptable mail to your mail server. Because MailShield has powerful filtering capabilities, your mail server's ability to filter mail is greatly expanded. Generally, there are three ways to have MailShield work with your mail server: 1) To have MailShield forward mail to another port on the same machine. Introduction 8 2) To have MailShield forward mail to another TCP/IP address on the same machine. 3) To have MailShield forward mail to another machine, where your mail server is running. In all these cases the outside world connects to your MailShield server and does not know of the location of your real mail server. Also, MailShield server forwards to your mail server. If you have a firewall, you can further protect your mail server by disallowing outside connections to it, and only allowing MailShield through. Installation 9 Installation Configure MailShield MailShield settings are stored in plain text files, each of which contains one setting. The configuration files are stored in the 'config' directory in the directory you installed MailShield in. You can configure MailShield by changing various settings, as appropriate for your site. Hand editing the text files is acceptable, however using the Admin Web GUI is easier. As of MailShield version 2.0, you can use the Admin Web GUI to alter your MailShield settings. The Admin Web GUI is a convenient and efficient tool to view your configuration and quickly adjust your settings. The Admin Web GUI is powered by a built-in web server. Within the Admin Web GUI, all features are organized by category, so you can easily navigate among related features. For a complete description of every MailShield setting, see Feature Reference. 1) MailShield and your Mail Server The first step in configuring MailShield is to decide how MailShield and your mail server will coexist. Any SMTP mail server can work with MailShield if you use two machines. With this setup, you install MailShield on a machine without a mail server, then tell MailShield the TCP/IP address of your mail server (by editing smtpserv.txt see SMTP server), and finally change your DNS records so that MailShield is now the mail server for your domain. For instructions on this technique, see Generic Setup with 2 Machines. Installation 10 If you want MailShield to run on the same machine as your mail server, please refer to the directions appropriate to your mail server: Sendmail, Post.Office, Qmail, MetaInfo Sendmail, Netscape Mail Server, NTmail, Lotus Domino r5 The way to have Domino coexist with MailShield is to have Domino listen to another port besides port 25 (the SMTP mail default port). Let MailShield listen on port 25 and then tell MailShield to forward mail on to Domino. Here are the steps to have Domino and MailShield coexist: Move Domino to another port To change the SMTP incoming port number, go to "Domino Administrator", "Server/Current Server Document" then click on the "Ports" tab, then the "Internet Ports" tab, then change the number "25" to "26" in the "TCP/IP Port Number" row of the "Mail (SMTP Inbound". Save the document, then stop and restart your Domino server. Install and Configure MailShield * Install MailShield. * You will now need to set the SMTP Server setting in MailShield. If you are installing MailShield on Windows, the setup program will ask you for the TCP/IP and port of your mail server (this is the 4th configuration question). If you are not installing on Windows, or have already installed on Windows, and now need to reconfigure MailShield, you can set this value by editing smtpserv.txt. If you moved Notes to port 26, your Notes SMTP server is now located at: 127.0.0.1 26 You are now ready to use MailShield! You can start MailShield in the foreground with the command "shield start". If you are running Unix, you can also run MailShield in the background with "shield -bd". On Windows NT, you can also run MailShield as a service. See Command- Line Options. Initially, we recommend that you run MailShield in the foreground, so that any error messages are immediately displayed. Microsoft Exchange, AltaVista Mail, MailSite, Exim, MDaemon, SLMail, Imail, Microsoft IMS / IIS Mail, Lotus Notes, Microsoft IMS / IIS Mail, LSMTP.. 2) Basic MailShield Setup Now that MailShield is set to coexist with your mail server, you need to give MailShield some information about your site. This will allow it to accept your organization's mail and reject unauthorized relay attempts. Installation 11 Domain Name Server: Next, you need to tell MailShield the TCP/IP address of your DNS server. If you installed MailShield on Windows, this was the 2nd question asked by the setup program. The file dns.txt holds this setting. See DNS servers. Location of your Mail Server: Next, you need to tell MailShield the TCP/IP addresses and port number of your Mail Server. This tells MailShield where to send mail to. If you installed MailShield on Windows, this was the 4th (and final) question asked by the setup program. If you followed the instructions above, in "1) MailShield and your mail server", then you have already set this option. You can change this setting by editing smtpserv.txt. See SMTP server. Server Activation Code: If you purchased MailShield, you received a serial number from us. Now, point your browser at http://www.lyris.com/store/mailshield/register_ms. html to register your serial number, and to receive a server activation code. Once you receive the code, you can enter it in activate.txt. If you did not purchase MailShield, you can still use it and it will be full-featured, except, that every message that goes through MailShield will have an evaluation footer appended to it. See Mail Merge Support Enable MailShield mail merge support Determines whether MailShield's support for mail merge codes in email should be enabled or not. Enabling mail merge support means that MailShield will check every message going through it to see if the email message contains a MailShield mail merge code in it. For example, MailShield supports obtaining text from the HTTP GET command as a mail merge code. One use of this feature is insert HTTP based advertisements into your email messages. Here is an example of a MailShield HTTP mail merge code: <!-- merge type="httpget" url="http://www.corp.com/cgi-bin/getad" --> The code above instructs MailShield to perform an HTTP GET command on the URL http://www.corp.com/cgi-bin/getad and to replace the mail merge code with whatever text is returned by the URL. If the URL is invalid, or the URL does not return any text, the mail merge code will be replaced with a blank. The URL must be a http:// style URL. A port number may be specified on the URL, as in: http://www.corp.com:81/cgi-bin/getad and is optional. If multiple recipients are listed in the email message, the mail merge code will be fetched once for each recipient, and separate email messages will be generated for each recipient. An optional parameter for this mail merge code is the cookie="xxx" option. Specify cookie="xxx" and MailShield will send this "xxx" value as the cookie to the web server when performing the HTTP GET command. You can optionally use the code $subst('recip.emailaddr') in the cookie= line and MailShield will replace it with the email address of the recipient of that email message. An example of a mail merge code with a cookie is: Installation 12 <!-- merge type="httpget" url="http://www.corp.com/cgi-bin/getad" cookie="$subst('recip.emailaddr') --> By default, the MailShield mail merge feature is disabled, and is set to FALSE. Set it to TRUE to enable the MailShield mail merge feature. Filename: mailmerg.txt MailShield server activation code. Admin Web GUI Port: For Windows users, the installer preconfigures your web server port. For UNIX users, you must do this yourself. In any event, to configure the port used by the web interface, you must edit webport.txt. The default port is 81. See Admin Interface Port Number. Admin Web GUI TCP/IP Address: The MailShield Admin Interface by default only listens to the localhost address (127.0.0.1). If you want to configure the admin interface to listen to another IP address instead, you must edit the webtcpip.txt file. You will need to edit this file if you plan to remotely administer MailShield using the Admin Interface. See Admin Interface TCP/IP Address. Admin Web GUI Password: The Admin Interface will use the password you specify. If you are on Windows, the installer prompted you for a password. Use "admin" as the user, and the password you specified. On UNIX, you must manually edit the password by modifying password.txt. The format of the password entry is login:password, where login is the name you want to login as, and password is the password for that user. That way, you can specify multiple entries. If the password.txt file is empty, the login screen will accept any username and an empty password. See Admin Interface Password. * At this point, you may use the admin web gui to complete your configuration: you can access the admin web interface by pointing your browser to http://localhost:81 (or specify a different port number if you are not using port 81.) Local Domain Names: First, specify the domain names that your organization accepts mail for. If you installed MailShield on Windows, this was the first question asked by the setup program. The file localdom.txt holds this setting. See Local domain names. TCP/IP Addresses allowed to Relay: Next, you need to tell MailShield the TCP/IP addresses used by your organization. This tells MailShield who is allowed to use the MailShield mail server as a relay host. If you installed MailShield on Windows, this was the 3rd question asked by the setup program. The file okrelayt.txt holds this setting. See TCP/IP addresses allow to relay. How to treat unwanted email: If you installed on Windows you were asked if unwanted email should be rejected, it should have its subject marked or if it should be forwarded to another email address. You can change these settings by hand for whatever platform you installed MailShield on; see Mark subject instead of refusing or Forward rejected mail. Start MailShield: On Windows, you can click on the "Run MailShield Now" icon or you also have the option of running MailShield as a background service. On Unix, you run MailShield with the "start" (foreground) or "-bd" (background) command line options. For more information, see Starting MailShield. 3) Advanced MailShield Setup Installation 13 Other MailShield options: MailShield is very powerful, has many features and options. For a complete description of every MailShield setting, see Feature Reference. For serious Techies: If you are very technically oriented, you may also be interested in editing the rule scripts that MailShield uses, so that you can completely change how MailShield handles incoming email. These scripts control everything MailShield does, which use a fully documented scripting language specialized for email processing. If you interested in these capabilities, see MailShield Rule Scripts. Installing on Windows To install MailShield on Windows NT or Windows 95, follow these instructions: 1) Download MailShield for Windows from our web site (http://www.lyris.com/store/mailshield/). 2) Run the .EXE file that you downloaded. It should be called mshield.exe. 3) The setup program will then guide you through the installation process. 4) Read Configure MailShield. 5) If you want to install MailShield as a service, see Windows NT Service or Windows 95 Service. Upgrading on Windows CRITICAL UPGRADE NOTICE: MailShield version 2 cannot be used for free, even in the trial capacity that previous versions offered. If you upgrade to this version of MailShield without a license, you will be limited to 20 test messages, after which MailShield will stop working until a license is installed. To evaluate MailShield v2, email sales@lyris.com for a temporary license. If you have not yet purchased MailShield, and are using a previous version, you can easily upgrade to v2 by purchasing a license. If you already have MailShield on your Windows system and want to upgrade to a newer version of MailShield, follow the steps for Installing on Windows. At the beginning of the setup program, you will be asked if you are upgrading a previous installation. You will then need to specify the directory where MailShield is installed. All the MailShield files will be replaced with the new MailShield files, except for your existing configuration files, which will be preserved. (optional) If you changed by hand any of the rule files (those files in /shield/rules), you will need to reapply your changes to the new MailShield rule files. We recommend that you hand-apply these changes with a text editor. However, you can decide to stay with your old rule files, but if you do, you will not get any of the new features that might be present in the new rule files. If you want to overwrite the new rule files with your old rule files, use a command such as "copy /bk/shield/rules/*.* /shield/rules/". Installation 14 Uninstalling on Windows If you already have MailShield on your Windows system and want to remove it, you can use the uninstall program. On Windows NT 4 and Windows 95, go to "control panel", and then to "add/remove programs". Scroll down the list, and choose to remove MailShield. On Windows NT 3.51, a "uninstall MailShield" icon was created in your MailShield group. Note: If you installed the MailShield service, so that MailShield starts automatically upon bootup, you should first remove the service before uninstalling MailShield. See Windows NT Service or Windows 95 Service for more information. Installing on Unix To install MailShield on Unix, follow these instructions: 1) Change the user to root. You must be root to install and run MialShield 2) Download MailShield for Unix from our web site (http://www.lyris.com/store/mailshield/). 3) Make a temporary directory. For example, /opt/tmp. 4) Put the MailShield file you downloaded into the temporary directory. 5) Uncompress and untar the file you downloaded. For example, if you downloaded shsols.tar.gz, the steps would be: gunzip shsols.tar.gz tar xf shsols.tar And if you downloaded shsols.tar.Z, the steps would be: compress -d shsols.tar.Z tar xf shsols.tar The tar file will create a "shield" directory under the current directory, containing all MailShield components. For example, if you stored the compressed file into your temporary directory /opt/tmp, MailShield would be in /opt/tmp/shield 6) Move the entire directory to the final location where you want MailShield to reside. For example, if you want MailShield to be in /opt/shield, you would run the command: mv /opt/tmp/shield /opt/shield Or, if you would prefer to copy, rather than move, you would issue the command: cp -r /opt/tmp/shield /opt/shield 7) Edit the config/dns.txt file by adding the IP address of your DNS server. 8) Start MailShield with the following command: ./shield start The screen output will indicate an error if there is no destination SMTP server defined. Ignore this error for now. Note: to stop MailShield when running in the foreground, use Ctrl+C. 9) You can now finish configuring your MailShield installation using the Admin Web GUI. To access the Admin Web GUI, point your browser to: Installation 15 http://localhost:81 Note: If you have already configured your Admin Web GUI to use a port other than port 81, you should point your browser to that port instead. You will find that editing your MailShield configuration via the Admin Web GUI is convenient and intuitive. Please note that the default login name is "admin" and the default password is "" (no password). Read Configure MailShield for details. 10) If you want to install MailShield as a background service, which starts upon bootup, add the command: /opt/shield/shield -bd To the appropriate startup script. On Solaris, for example, we add this command to the /etc/rc2.d/S72inetsvc script. Alternatively, you can place the script given below into one of your "rc" directories, to have MailShield automatically start up and shut down with the system. On Solaris, we create this file as /etc/rc2.d/S96shield. Here are the contents of the script: #!/bin/sh #ident "@(#)shield 1.0 98/4/3 " # MailShield startup script, # Place this in /etc/rc2.d/ (or elsewhere, depending # on Unix platform) state=$1 case $state in 'start') ulimit -n 512 # Set high file descriptors /opt/shield/shield -bd # start MailShield ;; 'stop') kill -15 `cat /etc/shield.pid` ;; *) echo "Usage: S96shield { start | stop }" ;; esac Upgrading on Unix CRITICAL UPGRADE NOTICE: MailShield version 2 cannot be used for free, even in the trial capacity that previous versions offered. If you upgrade to this version of MailShield without a license, you will be limited to 20 test messages, after which MailShield will stop working until a license is installed. To evaluate MailShield v2, email sales@lyris.com for a temporary license. If you have not yet purchased MailShield, and are using a previous version, you can easily upgrade to v2 by purchasing a license. If you already have MailShield on your Unix system and want to upgrade to a newer version of MailShield, follow the same steps for Installing on Unix with the following changes. Installation 16 1) Stop the MailShield process, with the command: kill -15 `cat /etc/shield.pid` 2) Move your current MailShield installation to another directory. For example, this command will move /opt/shield to /opt/bk/shield: mv /opt/shield /opt/bk/shield 3) Move the new files in: You now want to move the files from the installation directory to your production MailShield directory. For example, this command will work if the new files (from the tar file you downloaded) are in /opt/tmp: mv /opt/tmp/shield /opt/shield 4) Copy the old config directory to 'cfgold' You now want to copy the 'config' directory from your previous installation, into a directory named 'cfgold' in your new installation directory (i.e., your MailShield production directory). For example, this command would restore your configuration files, if you had backed up to /opt/bk/shield, and your installation was in /opt/shield: cp -r /opt/bk/shield/config /opt/shield/cfgold 5) Merge the old config files with the new files. This step will apply all the settings from your previous configuration into your new config files. Briefly, what this means is that all the text lines after the "#" comments will be extracted from your old files and will replace the non-comment lines in the new files. To perform this step, change to the MailShield directory (cd /opt/shield) and issue the following command: shield tcl tcllib/upcfg.tcl The "upcfg.tcl" script should run with no errors. If you have any problems, you can always restore your backup, or use the config files from the old installation with the new version of MailShield. 6) You are now done upgrading MailShield, and you should now be able to start MailShield back up. See Command-Line Options. 7) (optional) If you changed by hand any of the rule files (those files in /opt/shield/rules), you will need to reapply your changes to the new MailShield rule files. We recommend that you hand-apply these changes with a text editor. However, you can decide to stay with your old rule files, but if you do, you will not get any of the new features that might be present in the new rule files. If you want to overwrite the new rule files with your old rule files, use a command such as "cp /opt/bk/shield/rules/* /opt/shield/rules/." Uninstalling on Unix If you already have MailShield on your Unix system and want to remove it, here are the steps you should take: * Stop the MailShield process, with the command: kill -15 `cat /etc/shield.pid` * Delete any startup scripts you created on your own. * Set your mail server back to how you had it set before you installed MailShield. * Set your DNS records back to how you had them before MailShield * Remove the MailShield directory. For example: Installation 17 rm -rf /opt/shield High Mail Loads on Unix If you are going to have a very large number of simultaneous email connections (i.e., a high load) going through your MailShield server, it is a good idea to make sure your Unix system has enough socket descriptors allocated for MailShield to run properly. Most Unix operating systems have a per-process descriptor limit. Because MailShield is multithreaded, it can accept many simultaneous connections, and use up your descriptor limit. Thus, for high load systems, you will need to increase your descriptor limit. To determine your current descriptor limit, type: ulimit -n On Solaris systems, the default is 64, which MailShield can exhaust fairly easily. On Solaris, you can increase the descriptor limit in the entire system by appending the following lines to your /etc/system file and then rebooting: set rlim_fd_max=0x400 set rlim_fd_cur=0x300 On other Unix systems, this limit is set differently. In general, you can change the descriptor limit of the current shell with the command: ulimit -n 768 And then checking with the command: ulimit -n To make sure that the limit was indeed reset to 768. If your version of Unix accepts this, you may want to write a small shell script called "start_mailshield" with the following contents: cd /opt/shield ulimit -n 768 shield -bd Note: If you run into the descriptor limit while MailShield is running, the console where MailShield is running will display errors about not being able to bind to some tcp/ip addresses (because there are no descriptors left). The error message you will see will be something like this: Tcp_Connection_Receiver::DoTcpRecv 2 exception: system_call_failure: ::bind ( 4, // descriptor() 0xef20bac8, // (sockaddr*) address 16 // size ) [socket.cpp:163] Error: unable to listen to TCP/IP address: 206.13.32.3 Thus, if you see this kind of error after you have been running MailShield for a while, then you know that you need to increase your descriptor limit. Installation 18 Automatic Restart on Unix You may want to configure MailShield on your Unix system so that if MailShield stopped running for some reason, it would be automatically restarted by your system. MailShield might stop running because an admin user specifically killed it, a problem caused it to crash (i.e., running extremely low on memory) or some other reason. To have MailShield restart if the process is ever terminated, edit your /etc/inittab file, and add a line such as this: sh:2345:respawn:/opt/shield/shield start >/tmp/s.log Note: You must not start MailShield up with the -bd option in the inittab file. If you do, the system init script will become confused and think that MailShield has exited (because -bd causes an immediate exit, even though a background process remains). The system init script will launch copies of MailShield as fast as it can. You will have dozens of these running and your system will slow down. If you use the syntax above, using the "start" command, you will not have any problems. Note: If you use this technique, you should not have MailShield start in your rc.d script, as these two approaches are mutually exclusive. Either use this inittab approach, or use the rc.d script approach to starting MailShield. Restarting to free up memory The way that Unix memory allocation works is, a process is given memory from the system memory pool when it needs it, but when that process is finished with that memory, the memory does not go back to the system pool, but stays in the application pool. That is why MailShield will appear to use more memory than it currently is using. The total process memory usage is always what the peak usage was at some time. If the peak usage was very high, MailShield might have used a lot of memory (say, 50mb of RAM) and this is memory that could be used for other purposes, if it were reclaimed. For this reason, you might want to set MailShield up to automatically respawn itself when stopped (as detailed above), and then set up a cron job to stop MailShield on a scheduled basis. The command to cleanly stop MailShield is: kill -15 `cat /etc/shield.pid` Put this command into your crontab file, scheduled at whatever interval you want. When MailShield exits, it will automatically be restarted, and your memory will be reclaimed. Starting MailShield These are the various ways you have of starting MailShield running on your machine. 1) On Windows, the setup program creates an icon titled "Run MailShield Now". Installation 19 2) To start MailShield in the foreground on Windows or Unix, use the command "shield start". You would type: shield start 3) On Windows NT, to start MailShield as a service, use the command "shield - install". You would type: shield -install Then go to the "services" control panel and start MailShield. 4) On Windows 95, to install MailShield as a service, use the command "shield - install95". You would type: shield -install95 The next time you reboot, MailShield will start automatically. On Windows 95, MailShield is always run as a foreground application, so you should start it as explained in step #1 above. 5) On Unix, to start MailShield as a background daemon, type: shield -bd Command-Line Options On the MailShield command line, the following options are available: start - Starts MailShield in the foreground. help - Give command line help. logfile=<filename> - Append a copy of the MailShield activity log to the given file. debug - Display MailShield internal program information (for debugging purposes). Examples: shield start shield start log_smtp shield start logfile=log.txt You can also specify multiple options, and they are executed in the order given. For example, to log everything except program parsing, you would specify: shield start log_all no_log_program_parse Note: The log file name can be permanently specified in the logname.txt configuration file. nopid - (Unix only) Do not write the MailShield process ID out to /etc/shield.pid as would normally do by default Installation 20 Logging Options Any of these flags may be placed on the command line to enable or disable a log type. For examples: shield start log_smtp Here are all the command line logging options: log_config/no_log_config - enable/disable logging of configuration information. log_script_log/no_log_script_log - enable/disable script execution information. log_smtp/no_log_smtp - enable/disable script execution information. log_urgent/no_log_urgent - enable/disable urgent information (enabled by default). log_program_parse/no_log_program_parse - enable/disable information about parsing of the MailShield scripts. log_program_output/no_log_program_output - enable/disable logging of output statements from the MailShield scripts. log_program_list/no_log_program_list - enable/disable displaying (tracing) of MailShield scripts as they run. log_major/no_log_major - enable/disable displaying of information of major consequences (enabled by default). log_script_log/no_log_script_log - enable/disable script execution information. log_refuse/no_log_refuse - enable/disable displaying SMTP connection refusals. log_all - enable all log options. log_none - disable all log options. The first letter of each line in the log indicates what kind of log entry it is. These letters are defined as follows: log_config = c log_database = d log_major = m log_nntp = n log_program_list = l log_program_output = o log_program_parse = p log_refuse = r log_script_log = t log_smtp = s log_urgent = u Here is a sample log entry, of type "log_smtp" (notice that 's' is the first letter): s [03/19/98 21:10:48] RELAY_SUCCESS - from <sk@lyris.net> to <jman@shelby.com> [207.90.155.32]- [207.90.155.44 25] Installation 21 Windows NT Service You can install MailShield as a Windows NT service, so that it runs in the background, starting automatically upon bootup. The command line options for installing or removing the MailShield Windows NT service are: shield -install Installs MailShield as a Windows NT service shield -remove Remove MailShield as a Windows NT service For example, to Install MailShield as an NT service, you would use the command "shield -install", and you would type: cd \shield shield -install If you installed MailShield as a service, and later want to uninstall MailShield, you should first remove the MailShield service. To Remove the MailShield Service, you would use the command "shield -remove", and you would type: cd \shield shield -remove Windows 95 Service You can install MailShield as a Windows 95 service, so that it starts automatically upon bootup. MailShield is not able to run "hidden" on Windows 95, only MailShield for Windows NT can do this. The command line options for installing or removing the MailShield Windows 95 service are: shield -install95 Installs MailShield as a Windows 95 service shield -remove95 Remove MailShield as a Windows 95 service For example, to Install MailShield as a Windows 95 service, you would use the command "shield -install95", and you would type: cd \shield shield -install95 If you installed MailShield as a service, and later want to uninstall MailShield, you should first remove the MailShield service. To Remove the MailShield Service, you would use the command "shield -remove95", and you would type: cd \shield shield -remove95 Unix Background Daemon You can install MailShield as a background daemon, so that it runs in the background, starting automatically upon bootup. The command line option for running MailShield as a background daemon is: Installation 22 -bd - runs MailShield as a background daemon. Same effect as sendmail's -bd option. For example: /opt/shield/shield -bd Feature Reference 23 Feature Reference MailShield features have settings defined by various configuration text files. The files are then read by scripts, which then perform the various filtering activities in MailShield. For example, you can place a list of "forbidden words" in a text file and MailShield will automatically reject any message that contains them. For information about MailShield scripts, see MailShield Rule Scripts. The following chapters explain every feature that comes built into the rule files that come with MailShield. The features are roughly grouped by the category of feature that they are. Always Approve Approved MAIL FROM: text Email addresses you always accept email from A file containing text which, if the connected host sends to you in the SMTP "MAIL FROM" command, results in the message being approved for delivery and/or relaying. In other words, messages with these MAIL FROM values can send you anything. The "MAIL FROM" command is the email address where error mail notifications are to be sent. In regular personal mail, this is the same address as the From: address in the message text. With list server mail, this is sometimes a different address (for handling the bounces separately). Filename: okmailfr.txt Approved RCPT TO: text Email addresses that bypass MailShield, always receiving mail Set the email addresses that mail should always be accepted to. If any of the recipients of an email address is an address listed here, the entire message is accepted. This setting only applies to the value given in the SMTP RCPT TO: <> command, which specifies the actual recipient of the email message (as opposed to the To: message header, which can be any email address). Feature Reference 24 You can enter a complete email address, such as "bob@somewhere.com", or just a text fragment, such as "@somewhere.com" Filename: okrcptto.txt Approved To: Header text Email addresses that bypass MailShield, always receiving mail Set the text that, if seen in the To: header of the message, means that the mail should always be accepted. You can enter a complete email address, such as "bob@somewhere.com", or just a text fragment, such as "@somewhere.com". You can also use this to specify exceptions to the ban rules, so that for example, certain messages with invalid To: lines are nonetheless accepted. Filename: okto.txt Banned Banned From: header Reject email if this text appears in the From: header Reject messages that have any of the defined text appear in their message From: header. The From: header is the portion of an email message, which is read by the recipient, which looks like this: > From: "Jane Somebody" <jane@somewhere.com> Filename: banfrom.txt Banned HELO text Reject email if this text appears in the HELO command Text which, if the connected host sends in the SMTP "HELO" command, results in the message being rejected. Put each banned text phrase on a separate line. Filename: banhelo.txt Banned MAIL FROM: text Reject email if this text appears in the MAIL FROM command A file containing text which, if the connected host sends in the SMTP "MAIL FROM" command, results in the message being refused. The "MAIL FROM" command is the email address where error mail notifications are to be sent. In regular personal mail, this is the same address as the From: address in Feature Reference 25 the message text. With list server mail, this is sometimes a different address (for handling the bounces separately). Filename: banmfrom.txt Banned MIME Filename text Reject email if this text appears in any MIME file attachments Reject messages that have any of the defined text appear in the filenames of the file attachments included with an attachment. This filter can be used to block attachment types that you do not want your mail system to accept. For example, many companies ban all executable attachments, such as those ending with .exe, .zip, .com or .bat. Still others might have bad Microsoft Word documents, because they might have a macro virus in them: Word documents can be banned by looking for .doc in the filename. This filter automatically extracts all the attachment filenames in a MIME message, and compares the filenames with the ban text you specify below. If there is a match, the message is rejected. Filename: banfname.txt Banned RCPT TO: text Reject email if this text appears in the RCPT TO command Set the email addresses that mail should not be accepted to. If any of the recipients of an email address is an address listed here, the entire message is rejected. This setting only applies to the value given in the SMTP RCPT TO: <> command, which specifies the actual recipient of the email message (as opposed to the To: message header, which can be any email address). Filename: banrcpt.txt Banned Received: header text Reject email if this text appears in the Received: header If any of these lines of text appear anywhere in the Received: header of the message, then this message will be rejected. Each line defines a separate banned header text string. Filename: banrecv.txt Banned Subject: prefix Reject email if this text prefixes the Subject: header If any of these lines of text appear as the first few characters of the subject of the message, then this message will be rejected. Feature Reference 26 Some states have passed laws that require advertising messages to put the words AD: or ADV: as the beginning of the subject line. You may want to block messages that declare themselves in this way to be advertisements, by specifying "ad:" and "adv:" as the settings for this feature. Each line defines a separate banned subject prefix string. Filename: bansubjp.txt Banned Subject: text Reject email if this text appears in the Subject: header If any of these lines of text appear in the subject of the message, then this message will be rejected. Each line defines a separate banned subject text string. Filename: bansubj.txt Banned TCP/IP addresses Reject email if the sender is one of these TCP/IP addresses A file containing TCP/IP addresses, one on each line, of hosts which are not permitted to send mail to MailShield. Also, ranges of TCP/IP addresses may be specified, in the form "207.90.2.1-207.90.2.128" Filename: bantcpip.txt Banned To: text Reject email if this text appears in the To: header If any of these lines of text appear in the To: header of the message, then this message will be rejected. Each line defines a separate banned To: header text string. Filename: banto.txt Banned X-Mailer: text Reject email if this text appears in the X-Mailer: header If any of these lines of text appear in the X-Mailer" header of the message, then this message will be rejected. Each line defines a separate banned X-Mailer: text string. Many email programs identify themselves in the X-Mailer programs and MailShield can automatically block the known spam-creating programs. Filename: banxmail.txt Banned body text Reject email if this text appears in the message body Feature Reference 27 If any of these lines of text appear anywhere in the body of the message, then this message will be rejected. Each line defines a separate banned body text string. Filename: banbody.txt Banned domain names Reject email if sender is one of these banned domain names Domain names, one on each line, who are not permitted to send mail. Note: MailShield determines the host name of the connecting host by performing a reverse name lookup on their TCP/IP address. For example: > junkmail4you.com Filename: bandom.txt Banned header text Reject email if this text appears in the header If any of these lines of text appear anywhere in the header of the message, then this message will be rejected. Each line defines a separate banned header text string. Filename: banhdr.txt Banned message text Reject email if this banned text appears anywhere in the message If any of these lines of text appear anywhere in the message (header or body), then this message will be rejected. Each line defines a separate banned text string. Filename: bantext.txt Basic Configuration Admin email address Email address of the MailShield administrator Sets the email address of the MailShield system administrator. This address is provided to Lyris Technologies, Inc. so that they can inform the MailShield system administrator of important new versions. This address will remain confidential. Example: > admin@somewhere.com Filename: admin.txt Feature Reference 28 Admin Interface Port Number Port number used by the Admin Web GUI Specify the port number on which the MailShield Admin Web GUI should run. If the port number is anything but 80, you must specify the port number in the URL you use to access the Web GUI (i.e. http://localhost:81 vs. http://localhost). Note: The default port number is 81 Example: > 81 Filename: webport.txt Admin Interface TCP/IP Address TCP/IP address used by the Admin Web GUI Specify the TCP/IP address the MailShield Admin Web GUI uses. If you want to access the Admin GUI remotely, the TCP/IP address should be set to the TCP/IP address of the machine rather than 127.0.0.1. Note: an address of 0 disables the web interface. If no address is provided then the server will accept all connection requests. For example: > 192.168.1.124 Filename: webtcpip.txt Admin Interface Password User Password pairs used used to authenticate Admin Web GUI requests Specify the users and passwords which can use the Admin Web GUI. For Windows usesrs, the installer prompts for a password, which is paired with an "admin" entry in the password.txt file. For UNIX users, this file must be edited by hand to force authentication when the admin web GUI is accessed. The format of an entry is as follows: user:password You can specify as many users as you like. Place each entry on a line by itself. Filename: password.txt Append text to SMTP welcome message Text will be appended to the SMTP welcome message This setting appends text to the welcome message that is displayed when a mail server connects to MailShield. Feature Reference 29 Some organizations like to state their email receiving policy, such as "UCE not wanted", at this point. The CAUCE organization is trying to set up a law where the words "UCE not wanted" serve as a warning to the sender and if unsolicited commercial email (UCE) is sent, then this is a cause for a lawsuit. By default, this setting is blank. A sample setting would be: > (UCE not wanted) Note: The extra space before the parentheses. MailShield will append the text exactly as you put it, and will not insert its own space. So, if you do want a space before your appended text, be sure to put one in. Filename: begintxt.txt Canonize From: addresses Convert From: addresses into canonical domain name format for these domains Sets the domain names that you want MailShield to canonize when they appear in the From: address of email. For example, if your mail program sends mail out with a From like that looks like these: From: bob@mail.yourdomain.com or From: jane@exchange.yourdomain.com You may want MailShield to get rid of the "mail" or "exchange" part of the from address, so that the From: looks like this: From: bob@yourdomain.com or From: jane@yourdomain.com This is known as "canonizing" the From: address, because the address is converting into its "canonical" form. For example, if your company domain names were "mycompany.com" and "myothercompany.com", you would specify: > mycompany.com > myothercompany.com When MailShield sees any From: address with these domain names, the email will be rewritten to just have the domain name, and no mention of a hostname. Filename: canonize.txt Check Recipient Addresses Dynamically Whether MailShield should dynamically check the email recipient names given to it Sets whether MailShield should dynamically check your mail server after each recipient, in order to inform the sender whether an individual recipient is valid or not. With this feature disabled, MailShield will automatically accept all recipient names, and when MailShield relays the message to your mail server, it will reject the entire message if any of the recipients are invalid. This is a standard behavior for mail Feature Reference 30 relay servers. Because MailShield does not know beforehand what recipients your mail server will accept, MailShield cannot inform the sender of what recipients are valid until MailShield actually communicates with your mail server. Since the communication does not occur until MailShield relays to your mail server, at which point it is too late to tell the sender which exact recipients (if there were several). An example will help make this more clear. Say, that for your domain "corp.com", you have valid accounts for "jane@corp.com" and "bob@corp.com". If someone mistypes and tries to send mail to "janr@corp.com", then when MailShield tries to relay the message to your mail server, your mail server rejects the message - so far, no problem. But, if someone mistypes only one recipient, and sends the message to "janr@corp.com" (mistype) and "bob@corp.com" (correct), then when MailShield relays the message, the mail server rejects "janr", and thus MailShield must reject the entire message. The sender gets an error that the message was undeliverable, the recipient that caused the problem and they must send the message again with the invalid recipient removed in order for the message to be sent. For many companies, this is not a big inconvenience. However, this behavior, with MailShield added in front of your mail server, is slightly different from the behavior before MailShield was added. Before MailShield was added, if a message was sent to "janr" and "bob", then "bob" would receive the message, and the sender would receive an error message that "janr" did not receive the message. MailShield can duplicate the original behavior by dynamically checking whether your mail server will accept a given email address, and telling the sender this during the recipient definition stage (RCPT TO) of the mail sending transaction. MailShield does this by connecting to your SMTP server after a recipient is specified, and doing a mini-smtp session, where the initial negotiation and recipient is specified. MailShield records whether or not the mail server accepts the given recipient address. The results of this lookup are cached in memory, so that the lookup need only be performed once. Note: Positive (recipient accepted) lookups are only cached, while failures (recipient not accepted) are not cached, so you do not have to restart MailShield after adding a user account to your mail server. Some mail servers are configured to automatically accept all recipient addresses, and to return a separate error message by email if a recipient was incorrectly specified. With these mail servers, this feature is unneeded, and in fact, will not work, since the mail server will never tell MailShield that a recipient is invalid. In general, most mail servers, such as "Sendmail", do immediately reject invalid recipients during the SMTP session, and are compatible with this feature. Note: This dynamic testing is performed whenever a recipient is specified, regardless of whether the recipient is a local domain user, or a relay request. The reason for this is to guarantee that the mail server will definitely accept the recipient address when it comes to time to do the relaying. By default, this feature is disabled. Filename: chkrcpt.txt Configuration reload check Check how frequently to see if config files have changed Feature Reference 31 Sets how often MailShield checks the configuration file modification to see if the MailShield configuration should be reloaded. When MailShield starts up, it keeps track of the names of all the configuration files that were loaded. Then, on a regular interval, MailShield checks to see if any of those files have been modified. If they have been modified, then MailShield automatically reloads its configuration, so that the latest settings take effect. When you are first setting MailShield up, you will probably want to set this to something small, such as 5 seconds. Once your MailShield setup is basically finished, set it to something larger, such as 300 seconds (i.e., 5 minutes). Checking the configuration files to see if they have been modified takes a small amount of CPU time. On most machines, this will not matter, but if you are trying to keep your CPU usage to an absolute minimum, you can slow the checking. By default, this setting is set to a 30-second interval. Filename: check.txt DNS servers TCP/IP addresses of your DNS servers Sets the TCP/IP address of the DNS server that MailShield should use. Example: > 207.105.6.2 You can specify multiple DNS servers by separating each with a comma. If several DNS servers are specified, MailShield will load balance between them. Another example: > 207.105.1.6,207.43.15.5 Note: You must have a DNS server set in order for MailShield to work properly. Filename: dns.txt Disable Reverse DNS Set if reverse DNS lookups are performed on incoming mail Sets whether or not MailShield performs a reverse DNS lookup when a TCP/IP connection is made to MailShield. Explanation: To send mail to a host on the Internet, a mail server makes a TCP/IP connection to another mail server. When you use MailShield, then MailShield is your mail server. MailShield can look up the TCP/IP address of the other mail server and determine the hostname and domain of the connecting machine. This is called a "reverse lookup" because a name is determined from the TCP/IP address, as opposed to a "forward lookup", which is where a TCP/IP address is determined from a hostname. MailShield uses this reverse DNS lookup information in several places: 1) in the Received: header it inserts, 2) for okrelayd.txt, i.e.: domains approved for relaying feature, 3) in the bandom.txt file, i.e.: banned domains, 4) in the noname.txt file, i.e.: connecting host has no name and 5) in the tarpitd.txt file, i.e.: hostnames to tarpit. Feature Reference 32 However, if you are not using any of these features, you may not want to have MailShield perform the reverse DNS lookup, as it does take a little bit of time for the reverse lookup to be performed. Note: MailShield maintains its own in-memory DNS cache for both forward and reverse DNS lookups, and is thus more efficient than most mail servers in performing reverse DNS lookups over the long term. By default, reverse DNS lookups not disabled. If you want to disable reverse DNS lookups, be sure that you are not using any of the features listed above. To disable reverse DNS lookups, set this value to TRUE. Filename: offrdns.txt Helpful refuse message Whether refused messages should get a helpful message When MailShield refuses a message, you have the option of MailShield giving a helpful refuse message, which indicates exactly why the message was refused. Or, you can have MailShield give a less helpful message, which does not tell the sender exactly why the message was refused. For security reasons, you might not want to give the senders of refused mail any information about why you refused their mail. On the other hand, if you refused mail that you did not mean to, the helpful refuse message will tell the sender what the problem was, and the sender can usually work around it. The MailShield "refuse" log entries always display the helpful refuse message, so that you can see exactly why a message was refused. We recommend that this setting be enabled. By default, it is enabled. Filename: refushlp.txt Large messages pass-through Allow very large messages to bypass anti-spam body tests Sets the size beyond which an email message is able to bypass the anti-spam tests that MailShield places on the message body. The reason for this feature is that very large messages are usually messages with binary attachments, and there is little reason in testing the attachment for suspicious body text that would mark it as junk mail. Testing very large messages takes a significant amount of CPU and memory, and some sites, particularly if extremely large attachments are sent through (such as attachments over 10mb), might wish to gain a performance increase by letting these messages through. Note: This feature only lets the body text bypass the tests. All the other tests that MailShield performs still apply. Example: > 500,000 Feature Reference 33 The default value for this setting is 500,000, as in 100 kilobytes. The number is expressed in a byte value. Filename: large.txt Local domain names Your Internet domain names Sets the domain names that you want to receive email for. Any domain names not listed here will be understood as non-local (i.e., remote) and MailShield will interpret any email address To: an unlisted domain name as a request to relay mail. For example, if your company domain names are "mycompany.com" and "myothercompany.com", you would specify: > mycompany.com > myothercompany.com Note: MailShield checks the RCPT TO: values against the text that you specify, as the RCPT TO: values are the actual recipients on an email message, as opposed to whatever is listen in the To: header of the text. If you do not understand what this means, don't worry, it will just work the way you expect. Filename: localdom.txt Mail Merge Support Enable MailShield mail merge support Determines whether MailShield's support for mail merge codes in email should be enabled or not. Enabling mail merge support means that MailShield will check every message going through it to see if the email message contains a MailShield mail merge code in it. For example, MailShield supports obtaining text from the HTTP GET command as a mail merge code. One use of this feature is insert HTTP based advertisements into your email messages. Here is an example of a MailShield HTTP mail merge code: <!-- merge type="httpget" url="http://www.corp.com/cgi-bin/getad" --> The code above instructs MailShield to perform an HTTP GET command on the URL http://www.corp.com/cgi-bin/getad and to replace the mail merge code with whatever text is returned by the URL. If the URL is invalid, or the URL does not return any text, the mail merge code will be replaced with a blank. The URL must be a http:// style URL. A port number may be specified on the URL, as in: http://www.corp.com:81/cgi-bin/getad and is optional. If multiple recipients are listed in the email message, the mail merge code will be fetched once for each recipient, and separate email messages will be generated for each recipient. An optional parameter for this mail merge code is the cookie="xxx" option. Specify cookie="xxx" and MailShield will send this "xxx" value as the cookie to the web server when performing the HTTP GET command. You can optionally use the code Feature Reference 34 $subst('recip.emailaddr') in the cookie= line and MailShield will replace it with the email address of the recipient of that email message. An example of a mail merge code with a cookie is: <!-- merge type="httpget" url="http://www.corp.com/cgi-bin/getad" cookie="$subst('recip.emailaddr') --> By default, the MailShield mail merge feature is disabled, and is set to FALSE. Set it to TRUE to enable the MailShield mail merge feature. Filename: mailmerg.txt MailShield server activation code MailShield activation code If you purchased MailShield, you received a serial number from us. You will now need to register your server with us, in order receive a server activation code. Go to this web page: http://www.lyris.com/store/mailshield/register_ms.html This web page allows you to register your server and receive a server activation code. A server activation code is obtained by entering your serial number, and the first TCP/IP address of this machine (the machine that is running MailShield). If you are unsure what your first TCP/IP address is, you can have MailShield tell you what it is by running the command line "shield tcpip" from the MailShield program directory. Once you enter this information, a unique activation code, valid for your server, will be given to you. If you need to change the TCP/IP address that your serial number is registered for, you can go back to the web site, and reregister your serial number for a different TCP/IP address. You are not allowed to use one MailShield license on multiple machines: a separate license must be purchase for each machine. A MailShield serial number looks like this: SHI-YOURCOMPANY-SIC While a MailShield server activation code looks like this: ACT-207.90.155.3-YOURCOMPANY-PQE Without an activation code, MailShield will be full featured, but will run in an evaluation mode by appending an evaluation footer to every email message. Filename: activate.txt SMTP receive port TCP/IP port number MailShield should receive mail on Sets the TCP/IP port that MailShield listens on for SMTP mail The Internet default for SMTP mail is port 25. If none is set, the default of "25" is used. For example: Feature Reference 35 > 25 Note: MailShield must be restarted in order for a change in this setting to take effect. Filename: smtpport.txt SMTP server TCP/IP address and port number of your mail server Sets the TCP/IP address and port number of the SMTP server that MailShield should pass mail to. For example, if you have configured your mail server to listen to port 2025, so that MailShield receives regular mail on port 25, and should forward this mail to your mail server, the setting would be: > 127.0.0.1 2025 Note: The TCP/IP address is separated from the port number by using a space. Filename: smtpserv.txt Simultaneous Connection Limit Limit the number of simultaneous connections MailShield makes Sets the maximum number of TCP/IP connections that MailShield will accept. Some mail servers are unable to handle a large load of incoming connections. If these mail servers are overloaded, they either start crash, refuse connections or other undesirable behavior when that limit is reached. To solve this problem with the destination mail server, you can limit MailShield to not accept more than a set number of simultaneous connections, so that the destination server will not be given more connections than this. Note: Most mail servers are able to handle a high load without any problems. Another possible use for this feature is to limit load that MailShield will place on your system. By lowering the number of connections that MailShield can accept at once, you also place a limit on how much work MailShield can do at once, and this may effect the system load. If no connection limit is set, the default of "500" is used. For example: > 500 Filename: connects.txt TCP/IP addresses Sets the TCP/IP addresses MailShield should listen to. Sets the TCP/IP addresses to listen to. If this setting is blank, MailShield listens to all the TCP/IP addresses on this machine. Feature Reference 36 For example, if your machine has two TCP/IP addresses, 207.105.6.153 and 207.105.6.154, and you only want MailShield to listen on 207.105.6.154, you would type: > 207.105.6.154 To have MailShield explicitly listen to both TCP/IP addresses, you would separate each TCP/IP address with a carriage return, like so: > 207.105.6.153 > 207.105.6.154 If no TCP/IP addresses are set, then MailShield will listen to all the TCP/IP addresses on this machine. Note: On Solaris, this will be all the TCP/IP addresses for the primary Ethernet interface. Note: When MailShield has to send mail to your mail server, it creates an outbound connection, and that the first TCP/IP address you list here is used for all outbound MailShield TCP/IP connections. Note: MailShield must be restarted in order for a change in this setting to take effect. This setting is not dynamically reloaded. Filename: tcpip.txt Counter Measures Tarpit Excessive RCPT TO: Slow down RCPT TO when too many RCPT TO commands are given Introduces a 5 second delay in the SMTP connection after each RCPT TO command, after the number of recipients (ie: RCPT TO commands) reaches this specified threshold. Some spamming programs probe email servers with the RCPTO TO command to identify what email addresses are valid on a given mail server. This feature in MailShield is meant to discourage this sort of probing, since MailShield will make the probing perform very slowly. A setting of zero means that this feature is never enabled. Filename: rcpttar.txt Hostnames to tarpit Slow down connections from these Internet hostnames Sets the domain names of the hosts, which should have their mail connections, slowed down through "tarpitting". Tarpitting is a technique which aims to discourage people who send junk mail from sending it to you. Here is how the argument goes: if junk mailers have their messages refused right away, then they lose very little by trying to send to you in the future, because they will know right away if the mail will not be accepted, and thus can continue sending. However, if it takes a long time for the junk mailer to be told Feature Reference 37 that their message is being refused, then their mail sending will be slower, and they will have an incentive for removing you from their junk mail list. This technique is called "tarpitting" because it gets the junk mailers "stuck" in a "pit of tar" where it is difficult for them to get out and move quickly. The analogy being that animals who get stuck in tar learn to avoid it in the future. Whether tarpitting works in the real world is not known, as there is very little information available about the junk mailer's practices. Given that most junk mail is not delivered by the originator, but by some relay host, in most cases the junk mailer will never be aware of the tarpitting. But, perhaps the relay host will then be more motivated to secure their mail servers so that they cannot be used as unauthorized relay hosts. The problem with the theory of tarpitting is that it assumes that the mail server will notice the tarpitting. We are not aware of any mail server performance analysis programs that indicate to the sender that something like tarpitting is going on. You define hostname patterns for any host that might connect to you. You can repeat the commands if you need to define multiple hosts. For example, if you wanted to tarpit all mail from "junkmail.com", you would specify: > junkmail.com Filename: tarpitd.txt Slow if too many recipients For approved relaying, delay slightly if too many recipients This setting causes MailShield to pause for 2 seconds after each recipient if the number of recipients exceeds the given number. For example, if more than 50 recipients are CC'd on a message, and this setting is set to 20, then MailShield will pause 2 seconds for recipients 30 through 50, causing a total delay of 40 seconds. This feature is useful in situations where you want to prevent your own users from using your server for bulk mailing. "Spam" software works by sending a single message and a huge BCC: list to the server, and letting the mail server do the actual work of mail delivery. Thus, when someone wants to send mail to 100,000 people, they need to send the message body just a few times, and give a huge BCC list. This allows the sender to put the entire sending load on the mail server, and the person doing the bulk mailing can disconnect quickly. With this delay in place, MailShield would make it prohibitively slow to send to 100,000 people # in this way: it would take 55 hours to send to 100,000 people with this feature enabled. Another nice aspect of this feature is that the sender cannot work around it by talking to many different mail servers: if the pause threshold is low (such as at 5 recipients), then any MailShield protected mail server will cause the delay. If the sender attempts to bypass the restriction by sending fewer than 5 recipients, then sending will also be very slow for them, because they will have to transfer the message body many more times than with the BCC technique. Finally, this technique has the advantage of only mildly inconveniencing legitimate users, as the 2-second delay for small BCC lists is tolerable. For example, if the threshold is 5 users, and someone BCC's 7 people, there will only be a 4-second delay in sending. Feature Reference 38 We recommend that all ISP's enable this feature at some low number (such as 5), but that companies who trust their users set the number fairly high (perhaps at 50) The default setting is 50. Filename: slowdown.txt TCP/IP addresses to tarpit Slow down connections from these TCP/IP addresses Sets the TCP/IP addresses of the hosts, which should have their mail connections, slowed down through "tarpitting". Tarpitting is a technique which aims to discourage people who send junk mail from sending it to you. Here is how the argument goes: if junk mailers have their messages refused right away, then they lose very little by trying to send to you in the future, because they will know right away if the mail will not be accepted, and can continue sending. However, if it takes a long while for the junk mailer to be told that their message is being refused, then their mail sending will be slower, and they will have an incentive for removing you from their junk mail list. This technique is called "tarpitting" because it gets the junk mailers "stuck" in a "pit of tar" where it is difficult for them to get out and move quickly. The analogy being that animals who get stuck in tar learn to avoid it in the future. Whether tarpitting works in the real world is not known, as there is very little information available about the junk mailer's practices. Given that most junk mail is not delivered by the originator, but by some relay host, in most cases the junk mailer will never be aware of the tarpitting. But, perhaps the relay host will then be more motivated to secure their mail servers so that they cannot be used as unauthorized relay hosts. The problem with the theory of tarpitting is that it assumes that the mail server will notice the tarpitting. We are not aware of any mail server performance analysis programs that indicate to the sender that something like tarpitting is going on. You define TCP/IP ranges for any host that might connect to you. You can repeat the commands if you need to define multiple ranges. For example, if you wanted to tarpit TCP/IP addresses from 207.90.2.1 to 207.90.2.128 you would specify: > 207.90.2.1-207.90.2.128 Another example, if you wanted to tarpit a specific single TCP/IP address, you would specify: > 207.90.2.13 Filename: tarpitt.txt Tarpit delay Number of seconds to slow down "junk" sites sending to you If tarpitting is enabled (by defining hostnames or TCP/IP addresses to tarpit), then this setting defines how many seconds MailShield pauses after each SMTP command, in order to delay the connection. Feature Reference 39 Note: If you delay longer than 10 minutes, it is likely that the other end will hang up on you first. The default setting is "30" seconds. Filename: tardelay.txt Enforce Internet standards Reject no Date: header Reject messages that are missing a Date: header Reject any mail that does not have a Date: header in it. Internet standards do not require that every message have a Date: line in them, but almost all email programs insert a Date: header in the messages they create. Usually, messages without a Date: header were created by some sort of automated program, and the programmer did not bother to have a Date: inserted in the header. Occasionally, programs for sending spam make this same mistake and so checking for the presence of a Date: header will reject a fair number of automated messages and some spam as well. By default, this setting is disabled. Filename: nodate.txt Reject no From: header Reject messages that are missing a From: header Reject any mail that does not have a From: header in it. Internet standards dictate that all mail must have a From: header in it. Any mail that does not have a From: header in it is invalid, or may be junk mail. The From: header is the portion of an email message, which is read by the recipient, which looks like this: > From: "Jane Somebody" <jane@somewhere.com> We recommend that this feature be enabled. By default, this setting is enabled. Filename: nofrom.txt Reject no Subject: header Reject messages that do not have a Subject: header Reject any mail that does not have a Subject: header in it. Internet standards do not require that every message have a Subject: line in them, but it is widely considered basic email etiquette to have a Subject: line on your message. Feature Reference 40 The Subject: header is the portion of an email message, which is read by the recipient, which looks like this: > Subject: Please send me your price list Note: Some mailing list packages prefer that messages sent to them have no Subject line on them, so that the command message consists only of a single command, on the first line. If you are running such a mailing list program at your organization, you should not enable this feature, as this kind of email is legitimate when sent to a mailing list program. By default, this setting is disabled. Filename: nosubj.txt Reject no To: header Reject messages that do not have a To: header Reject any mail that does not have a To: header in it. Internet standards dictate that all mail must have a To: header in it. Any mail that does not have a To: header in it is invalid, or may be junk mail. We recommend that this feature be enabled. By default, this setting is enabled. Filename: noto.txt Reject no hostname Reject messages sent from machines with no Internet hostname When a host attempts to send mail to MailShield, MailShield can check the TCP/IP address of the connecting host, to see if that TCP/IP address has a host name on the Internet. This is commonly known as a "reverse DNS lookup" Internet mail standards require that mail servers have a reverse DNS host entry. It is a common practice to refuse email from connecting mail servers who do not meet this requirement. However, some mail servers have improperly configured DNS, and have not set up their DNS servers for "reverse DNS lookups", and so will be rejected. Sites that send junk mail often do not set up reverse DNS lookups, as the hostname this gives and provides investigators with information about the sender of the junk mail. We recommend that this feature be enabled. By default, this setting is disabled. Filename: noname.txt Require valid host for HELO Require SMTP sender to specify a valid host for HELO command Feature Reference 41 Some bulk mail programs send a TCP/IP address, or some random text, rather than a hostname as the value for the HELO command. The HELO command is supposed to be given by a connecting SMTP host, to identify who they are. Because the HELO text can be used to trace the source of junk mail, these bulk mail programs attempt to conceal their identity by sending a useless value instead. Every mail server on the Internet should have reverse DNS lookups defined, and thus should provide a valid hostname as a HELO value. We recommend that this setting be enabled. By default, this setting is disabled. Filename: helohost.txt Filter Results Append helpful info Append to message headers helpful connection information With every message that MailShield approves, MailShield can optionally append to the header of the message various useful pieces of information. Because this information is added to the header, most users will not be inconvenienced by it and will not see it unless they enable an option in their mail reading program to view headers. The information appended is: 1) the value of the HELO command, 2) the value of the MAIL FROM command, 3) the value of the RCPT-TO command(s), 4) the TCP/IP address and hostname of the sender. This information can be useful if junk mail is received, to determine who sent it, to whom it was sent, and other after-the-fact detection work. We recommend that this setting be enabled, but depending on the email program that your users have, they may not be able to see this information (some email programs never show headers) and others might be inconvenienced by it (if they cannot disable their view headers option). By default, this setting is enabled. Filename: smtpinfo.txt Backup mail server Instead of refusing junk mail, forward it to this mail server Sets the TCP/IP address and port number of the SMTP server that MailShield should forward unwanted mail to. In order to use this feature, you will need to set up a separate email server that is capable of receiving mail for your users. Any mail that has been defined as unwanted will be sent to this server. You will need to specify a TCP/IP address and port number. Feature Reference 42 For example, if you have configured another mail server to be on the same machine as MailShield, acting as a repository for rejected mail, and that mail server is configured to listen on port 2026, the setting would be > 127.0.0.1 2026 Note: The TCP/IP address is separated from the port number by using a space. Note: This feature will cause MailShield to no longer refuse unwanted mail, but instead to accept it. The reason for this is that if MailShield refused a mail message before receiving it, there would be no way for the message to be sent to a backup (since MailShield had not received it yet). Also, since MailShield does deliver the message somewhere, when MailShield rejects a message, the sending mail server often will try to send the message again, and each time it did that, you would receive an additional copy of the message. So, this feature causes the MailShield filters to mark a message as unwanted, and accept the message, rather than the default behavior of having MailShield simply rejecting the message. By default, the value for this option is blank. Filename: backmail.txt Forward rejected mail Instead of refusing junk mail, forward it to this email address Sets the email address of the person who should receive suspicious email. This is optional, and means that instead of rejecting suspicious mail, MailShield should forward it to this email address, so that they can review it, and do with it as they please. For example: > john@mycompany.com Note: This feature will cause MailShield to no longer refuse unwanted mail, but instead to accept it. The reason for this is that if MailShield refused a mail message before receiving it, there would be no way for the message to be sent to this other address (since MailShield had not received it yet). Also, since MailShield does deliver the message somewhere, when MailShield rejects a message, the sending mail server often will try to send the message again, and each time it did that, you would receive an additional copy of the message. So, this feature causes the MailShield filters to mark a message as unwanted, and accept the message, rather than the default behavior of having MailShield simply rejecting the message. The default value for this option is blank. Filename: forwmail.txt Feature Reference 43 Mark subject instead of refusing Instead of refusing junk mail, mark the Subject: with this text This option will prepend the text you specify on the Subject: line of any message that would instead be refused. By setting this text, you tell MailShield that mail that would otherwise be refused should not be refused, and should have its subject marked instead. Note: This feature will cause MailShield to no longer refuse unwanted mail, but instead to accept it. The reason for this is that if MailShield refused a mail message, there would be no way for the message to be marked and delivered to you (since MailShield had not received it yet). Also, since MailShield does deliver the message somewhere, when MailShield rejects a message, the sending mail server often will try to send the message again, and each time it did that, you would receive an additional copy of the message. So, to be clear, this feature causes the MailShield filters to mark a message as unwanted, accept the message, and mark the subject, rather than the default behavior of having MailShield simply reject the message. The default value for this setting is blank. Filename: marksubj.txt Junk Mail Detection DUL: Block Dialup Users Whether to use the MAPS DUL list to block dialup accounts from connecting directly to you. The MAPS Dialup User List, or DUL, is a blacklist of TCP/IP addresses used by ISP's for dialup accounts. Almost all email for dialup accounts is sent through the ISP's mail servers, provided by the ISP for that purpose. However, people sending large quantities of junk mail do not always like to use their ISP's mail servers, because the ISP can notice the junk mail and disconnect their account. For this reason, the latest spam-sending programs send email directly from a dialup account to your server. Since legitimate mail is very rarely sent this way (directly from a dialup account), the DUL attempts to list all the TCP/IP addresses used by dialup accounts in order to refuse email being sent directly from those TCP/IP addresses. Of course, even if the DUL is activated, people with dialup accounts can still send email to you, but they will do it by sending their email through their ISP, which is how the vast majority of dialup-account authored email is sent. The MAPS DUL has a low false false-positive rate because so few people send email directly from dialup accounts. It is an effective way to block spam from these direct- sending kind of spam-sending programs. For more information about the MAPS DUL, see http://maps.vix.com/dul/ By default, this setting is disabled. Feature Reference 44 Filename: dul.txt Max Received: HELO text size Reject a message if a Received: HELO text line is larger than this There is a bug in the popular Sendmail program, which is exploited by people sending junk mail to hide their identity. This is how the bug works: if a very long name is given to Sendmail on the HELO command line, the memory buffer in Sendmail 'overflows' and the real TCP/IP address of the sender is not displayed in the Received: line that the receiving Sendmail prepends to the message. Normally, this Received: line identifies the original sender, but by overflowing the HELO command, the Received: header line overflows its maximum size, and no TCP/IP address is given. Instead, just all text given on the HELO string is given, Sendmail does not have enough size in its buffer to display the TCP/IP address of the original sender. Unless a sending hostname really is very long (more than 200 characters), there is no reason why a large string should be passed on the HELO command line. For this reason, you may want to block messages that have very long Received: HELO text lines, because it probably means that the message was relayed through a Sendmail server and used the HELO overflow trick to conceal its identity. MailShield identifies the text in the Received: headers that is after the "from", as in "Received: from ... (etc." where the ... is the text from the original HELO command. If this ... text is very long, it likely means that the sender exploited this bug in sendmail, and that the message is likely junk mail. A setting such as 200 is a reasonable value to use for this feature. By default, this feature is set to 0, for no maximum Received: HELO line size. Filename: maxrecv.txt RBL+ Service Whether to use the RBL+ to determine if mail is junk mail RBL+ Master Service provides one-step access to a combination of databases maintained by MAPS. These databases contain the Internet Protocol addresses ("I.P. addresses") of Internet sites which do not follow MAPS' suggested email abuse policies. Included in these databases are Internet sites which support spamming (the sending of unsolicited commercial or bulk email), and Internet sites which allow their resources to be abused by spammers. Subscribers to MAPS' services can utilize the information in these databases to decide whether or not to accept email which originates from these sites, thereby greatly reducing the amount of unwanted email traffic which enters their system and ties up their resources. RBL+ Master Service combines access to MAPS' three most popular databases, the Realtime Blackhole List ("RBL"), the Relay Spam Stopper List ("RSS"), and the Dial-Up User List ("DUL"), allowing RBL+ Master Service subscribers to poll all three databases with a single query. The RBL+ Service is not a free service; you must subscribe to this service for a fee. This blacklist is maintained independently of MailShield. For more information about the RBL+, see http://mail-abuse.org/rbl+/ Feature Reference 45 The RBL is an effective way of drastically reducing the amount of spam that you receive. However, if you enable the RBL test, it is likely that you will also accidentally refuse valid email. The reason for this is that the RBL bans all email coming from a given set of TCP/IP addresses. For example, if an ISP has been banned because they allow spam from their mail servers, then all mail from that ISP will be banned, not just the spam. For this reason, the RBL is as much a political act as it is a technical solution for solving spam. Because the RBL inconveniences innocent people, those innocent people complain to their ISPs, and this, in turn, forces the ISP to enact stronger anti- spam measures, in order to get off the RBL ban list. In this regard, the RBL is similar to a product boycott. We do not recommend that this setting be enabled if it is important to you to not reject valid mail. On the other hand, if you fully understand the implications of the RBL for your system's mail, and you want to participate, then you should enable this feature, as the RBL has been effective in getting ISPs to secure their relay hosts in order be removed from the ban. By default, this setting is disabled. Filename: rbl-plus.txt Realtime Blackhole List Whether to use the RBL to determine if mail is junk mail The Real-time Blackhole List, or RBL, is a blacklist of Internet TCP/IP addresses known to send spam, or by hosts considered friendly to spam. This blacklist is maintained independently of MailShield. For more information about the RBL, see http://maps.vix.com/rbl/ The RBL is an effective way of drastically reducing the amount of spam that you receive. However, if you enable the RBL test, it is likely that you will also accidentally refuse valid email. The reason for this is the RBL bans all email coming from a given set of TCP/IP addresses. For example, if an ISP has been banned because they allow spam from their mail servers, then all mail from that ISP will be banned, not just the spam. For this reason, the RBL is as much a political act as it is a technical solution for solving spam. Because the RBL inconveniences innocent people, those innocent people complain to their ISP's, and this, in turn, forces the ISP to enact stronger anti- spam measures, in order to get off the RBL ban list. In this regard, the RBL is similar to a product boycott. We do not recommend that this setting be enabled if it is important to you to not reject valid mail. On the other hand, if you fully understand the implications of the RBL for your system's mail, and you want to participate, then you should enable this feature, as the RBL has been effective in getting ISP's to secure their relay hosts in order be removed from the ban. By default, this setting is disabled. Filename: rbl.txt Feature Reference 46 Relay Spam Stopper Whether to use the RSS to determine if mail is junk mail The Relay Spam Stopper List, or RSS, is a listing of Internet TCP/IP addresses known to relay spam. Note: this is not a listing of hosts that generate spam, only those hosts that are openly relaying spam. This blacklist is maintained independently of MailShield. For more information about the RSS, see http://maps.vix.com/rss/ The RSS is an effective way of drastically reducing the amount of spam that you receive. However, if you enable the RSS test, it is likely that you will also accidentally refuse valid email. The reason for this is that the RBL bans all email coming from a given set of TCP/IP addresses. For example, if an ISP has been banned because they have relayed spam from their mail servers, then all mail from that ISP will be banned, not just the spam. For this reason, the RSS is as much a political act as it is a technical solution for solving spam. Because the RSS inconveniences innocent people, those innocent people complain to their ISPs, and this, in turn, forces the ISP to enact stronger anti- spam measures, in order to get off the RSS ban list. In this regard, the RSS is similar to a product boycott. We do not recommend that this setting be enabled if it is important to you to not reject valid mail. On the other hand, if you fully understand the implications of the RSS for your system's mail, and you want to participate, then you should enable this feature, as the RSS has been effective in getting ISPs to secure their relay hosts in order be removed from the ban. By default, this setting is disabled. Filename: rss.txt Reject empty MAIL FROM Reject messages that have an empty MAIL FROM: value Reject any mail that has an empty MAIL FROM: <> value. Internet standards allow empty an empty MAIL FROM: <> when receiving email. This is a completely legitimate practice, and many automated programs send mail with a blank MAIL FROM value. For instance, mail delivery error reports are often sent with a blank MAIL FROM, so that they cannot bounce back and cause a mail loop. Primitive list servers do not have the programming intelligence to handle bounce reports and will also send mail with a blank MAIL FROM. Nonetheless, you may choose to reject mail with a blank MAIL FROM. Some spam is sent out in this way, and you might not wish to receive mail delivery error reports. We do not advise most people to enable this setting, as it this rule does violate common Internet practice. But, we leave the choice up to you. We recommend that this feature be disabled. By default, this setting is disabled. Filename: nomfrom.txt Feature Reference 47 Reject empty MAIL FROM with multiple recipients When the MAIL FROM of a message is blank, reject messages with multiple recipients Message with a blank MAIL FROM value are allowed on the Internet, because they are used by mail programs to report errors and the blank MAIL FROM is used to prevent mail loops (automated programs can't endlessly send automated messages to each other with a blank MAIL FROM, since this return address is not included). However, the only usual legitimate use of a blank MAIL FROM is for these mail systems to exchange bounce information (such as "message undeliverable messages). Human beings should not be sending messages with a blank MAIL FROM to each other, and it certainly should not be the case that a message with a blank MAIL FROM is being delivered to multiple people. People who send junk mail sometimes exploit this blank MAIL FROM capability to hide who they are, to further evade identification. Since system messages are almost always only To: one account, and not to several, it is legitimate to reject messages that have a blank MAIL FROM but which attempt to send to multiple recipients. This filter will reject a message that has a blank MAIL FROM, if more than one recipient is specified with the RCPT TO command. This filter has a very low false positive rate, and can be useful for blocking certain kinds of junk mail. By default, this setting is disabled. Filename: onercpt.txt Reject forged Date: Reject messages that use an obviously invalid Date: header Some programs, which are sold to send junk mail, use a forged Date: header that contains invalid information. Normal mail servers do not include this invalid information, and so this is a strong indicator of junk mail. We recommend that this setting be enabled. The default setting is enabled. Filename: rejfdate.txt Reject forged Message-Id Reject messages that use an obviously invalid Message-Id: Some programs which are sold to send junk mail use a forged Message-Id: header which contains invalid information. Normal mail servers do not include this invalid information, and so this is a strong indicator of junk mail. We recommend that this setting be enabled. By default, this setting is enabled. Filename: rejfid.txt Feature Reference 48 Reject invalid From: header Reject email where the domain name in the From: is invalid Reject any mail where the From: header appears to be invalid. If the email address specified in the From: header does not have a domain name or if the domain name specified does not appear in the Internet DNS records, then the From: is considered invalid. The From: header is the portion of an email message, which is read by the recipient, which looks like this: > From: "Jane Somebody" <jane@somewhere.com> A common technique with junk mail is to put an invalid email address in the From: header so that the recipient of the email message cannot respond. For example, this is an example of an invalid From: > From: "Junk Mail Masters" <junkmail@junkmail.headquarters> Note: MailShield only tests the domain name. If the domain is valid, but the email address isn't a real user for that domain, i.e., <xyz12345@juno.com>, then it will not be rejected based on this test. However, it may be rejected by one of the other configuration options. Mail with just a user name, such as "bob" will be considered invalid by this option. For example: > From: bob Junk mail sometimes comes addressed like this, so that it appears to be coming from a local user. MailShield, however, knows when mail is being sent from a local machine (and therefore, a local user is acceptable) by the hostname or TCP/IP address of the machine, which is defined in the MailShield configuration. In this way, only mail sent from local hosts can be addressed From: a local user, and any mail from outside your domain may not be. We recommend that this feature be enabled. By default, this setting is enabled. Filename: badfrom.txt Reject invalid MAIL FROM Reject email where the domain name in the MAIL FROM: is invalid MailShield can check the SMTP MAIL FROM value to see if it is valid. MailShield will perform a basic syntactical test, to ensure that the email address is well formed. MailShield will also do a DNS lookup on the host name of the MAIL FROM email address, to make sure that it comes from a valid Internet host name. Rejecting mail if the email address in MAIL FROM is invalid is a common practice among mail servers, and is a recommended for MailShield. By default, this setting is enabled. Filename: badmfrom.txt Feature Reference 49 Reject invalid To: header Reject email where the domain name in the To: is invalid Reject any mail where the To: header appears to be invalid. The To: header is the portion of an email message, which is read by the recipient, which looks like this: > To: "Jane Somebody" <jane@money4u.com> If the email address specified in the To: header does not have a domain name, or if the domain name specified does not appear in the Internet DNS records, then the To: is considered invalid. For example, this to: > To: friend@public.com Specifies the "public.com" domain, which is not a real domain, and so MailShield detects this and rejects the message. A common technique with junk mail is to put an invalid email address in the To: header so that the recipient of the email message cannot respond, nor can they determine who the message was really to. Internet mail standards require that some sort of correctly formatted email address be in the To: header. MailShield takes this requirement further, actually checking to ensure that the To: points to a real domain name, as well as performing other, more stringent syntax checks. Note: MailShield only tests the domain name. If the domain is valid, but the email address isn't a real user for that domain, i.e., <xyz12345@juno.com>, then it will not be rejected based on this test. However, it may be rejected by one of the other configuration options. Mail with just a user name, such as "bob" will be considered invalid by this option. Junk mail sometimes comes addressed like this, so that it appears to be coming from a local user. MailShield, however, knows when mail is being sent from a local machine (and therefore, a local user is acceptable) by the hostname or TCP/IP address of the machine, which is defined in the MailShield configuration. In this way, only mail sent from local hosts can be addressed From: a local user, and any mail from outside your domain may not be. We recommend that this feature be enabled. By default, this setting is enabled. Filename: badto.txt Reject source routed mail Reject messages that use obsolete "source routing" method Optionally reject mail sent to you that has a percent sign in the MAIL FROM field, which indicates a source-routed address. A source-routed address is an email address which gateways through another host. For example, the address "john%somewhere.com@elsewhere.com" is actually "john@somewhere.com", but it first gets delivered to "elsewhere.com", which then forwards the mail on to "somewhere.com". Source routed address are legitimate according to Internet standards, but their use is "deprecated" (i.e., discouraged) by the standards. Feature Reference 50 Some older networks still use source-routed addresses (for example, BITNET), but most do not. In 1997, AOL banned all source-routed email from their network, so that most remaining source-routed sites upgraded their sites to not use source routing. It is not clear how effective banning source-routed email is in getting rid of junk mail, but since AOL did it, MailShield provides the option as well. By default, this setting is disabled. Filename: rejsrc.txt Reject very long attachment filenames Reject messages have attachments with very long filenames There is a well known security flaw in several mail programs, where an email is sent with a file attachment to the victim, and the filename of the attachment is extremely long. When the victim reads the message, their mail program crashes due to the very long length of the filename, and it is theoretically possible that the sender of the message could run any program they want on the victims computer. While the ability to crash email clients with this security flaw has been demonstrated, and is well known, the ability to run an arbitrary program on the client machine by exploiting this flaw has only been theorized: there are currently no known exploits of this theory. Nonetheless, if you use a mail client known to have this security flaw, you might want to have MailShield check for very long filenames in attachments and have MailShield reject messages that appear to use this exploit. This setting determines the filename length that is considered 'too large' and rejects messages with attachments larger than this number. A setting of 100 should be plenty large to allow normal attachments through while prohibiting the exploitation of this security flaw. A setting of 0 disables this feature. By default, this feature is disabled. Filename: maxflen.txt Limits Max message lines Refuse message longer than this many lines If the message being received has more lines than this given size, then the message is rejected. The default is 250,000 lines (about 25mb). Note: The MailShield line count includes both the header and the body of the message. Filename: maxlines.txt Feature Reference 51 Max message size Reject messages larger than this byte size If the message being received is larger than this size (in bytes), then the message is rejected. The default maximum size is 20 megabytes (20000000). Note: The MailShield size count includes both the header and the body of the message. Filename: maxsize.txt Max recipients Reject messages with more than this number of recipients If the message being received has more recipients listed in the To: CC: and BCC: headers (combined), then reject this message. Junk mail will sometimes list a large number of recipients in the CC: list of the message. This setting will reject mail with too large a recipient list. The default is 100 recipients. Filename: maxrecip.txt Maximum RCPT TO recipients Refuse message with more than this number of RCPT TO: recipients Sets the maximum number of recipients that may be named in a single email message. Internet standards dictate that this be 100 recipients. Most mail servers are internally set to 50 recipients, but most legitimate mail does not need to specify more than 20 recipients. The default setting is 100 recipients. Filename: maxrcpt.txt Logging Log Level The amount of detail to include in the log Determines how much information about MailShield's activity should be placed in the log. If this setting is not defined, or equal to 0, then the default amount of logging takes place. If this setting is "1", then more information about unwanted email is logged, such as the "From:", "To:" and "Subject:". Currently, 0 or 1 are the only log level settings. Feature Reference 52 The default setting is 1 - log more information about rejections. This is an example of a log level 0 refusal message: r [1998.04.12 11:59:38] Refusing message because '550 Body To: is missing or empty. Filename: loglevel.txt Log filename File name of the MailShield log file Optionally log MailShield activity to this file. If a filename is specified, all MailShield activity will be logged to this file. If no filename is specified, no disk logging will take place. Log entries for mail that succeeds look like this: s [03/19/98 21:10:48] RELAY_SUCCESS - from <sk@lyris.net> to <jman@shelby.com> [207.90.155.32]-[207.90.155.44 25] While mail that was accepted by MailShield, but rejected by your mail server looks like this: s [03/19/98 17:20:44] RELAY_FAILED - from <mopt@bellsouth.net> to <win@shelby.com> [205.152.0.50]-[207.90.155.44 25] CODE: 550 LAST- MESSAGE:550 <win@shelby.com>... User unknown Note: You should specify a full path to the log file. For example (on Windows): > c:.txt Another example (on Unix): > /opt/shield/log.txt Filename: logname.txt System Log Whether to log information into the system log Defines whether MailShield logging information is saved to the system specific log facility. On Unix, this is the "syslog" facility. On Windows NT, this is the "Event Log" facility. On Unix, you may decide that you prefer to have all MailShield log information saved in "syslog", rather than in MailShield's own log file. You can do this using this feature. On Windows NT, this feature is currently not available, but will be available in the future. On Windows NT, you need to be very careful with the Event Viewer, because it has a tendency to "fill up", and then your system will not work reliably. Also, the NT Event Viewer is a resource-intensive logging facility, and thus can slow down your application if heavy significant logging takes place. By default, this setting is disabled. Feature Reference 53 Filename: syslog.txt Mail Relaying Hostnames to allow relaying The Internet host names to be allowed to relay through you Sets the domain names of the hosts that are allowed to relay mail through MailShield. This prevents unauthorized mail relaying. You define hostname patterns for any host that might connect to you. You can repeat the commands if you need to define multiple hosts. Any host who is not listed below will be automatically forbidden from relaying through you. For example, if your company domain is "mycompany.com" you can allow all hosts in your domain to relay through you by specifying: > mycompany.com If you are unsure if all your local hosts have reverse name lookups defined, then you should also enter the TCP/IP address range of your local hosts in the okrelayt.txt file. The reason for this is that in order for this feature to work with a particular host, MailShield must be able to determine the host's name by looking at their TCP/IP address, so a DNS reverse name lookup must be defined for that host. If no reverse name is defined for a host, then MailShield will not be able to confirm that they are a local host, and their mail may be treated as unauthorized relaying. Filename: okrelayd.txt Reject unauthorized relaying Whether or not to enforce mail relaying rules If someone is trying to send mail through your mail server, and has not been listed as a local host or local tcp/ip address (as defined in the MailShield configuration), then this is considered unauthorized mail relaying. It is common practice for junk mail to be relayed through other people's mail servers in order to offload the work to some other machine, and to disguise the origin of the junk mail. At our company, it took only 3 weeks before our mail server was discovered and started being abused as a relay host for junk mail. Besides stealing your machine and Internet bandwidth resources, unauthorized relaying also makes junk mail cheaper for the junk mailers, as they do not have to bear the resource cost of sending their own mail. Also, if you do not reject relaying from your domain, it is possible that your mail server will be "blacklisted" and that all mail, whether junk mail or not, will be rejected. We highly recommend that you enable this setting. By default, this setting is enabled. Filename: norelay.txt Feature Reference 54 TCP/IP addresses allow to relay The TCP/IP address to be allowed to relay through you Sets the TCP/IP addresses which are allowed to relay mail through MailShield. This prevents unauthorized mail relaying. You can put multiple lines in if you need to define multiple TCP/IP address ranges. Any TCP/IP address that is not listed below will be automatically forbidden from relaying through you. For example, if your TCP/IP addresses were from 207.90.2.1 and 207.90.2.128 you would specify: > 207.90.2.1-207.90.2.128 Another example, if you wanted to allow a specific single TCP/IP address, you would specify: > 207.90.2.13 By default, the TCP/IP address "127.0.0.1", which stands for the "local host" is approved for relaying. Filename: okrelayt.txt Working with Mail Servers 55 Working with Mail Servers Generic Setup with 2 Machines This section explains a simple process for installing MailShield that will work with any mail server. This method uses two machines: MailShield will run on one machine, and your mail server runs on another. You then change your DNS settings so that email is delivered to MailShield instead of being delivered to your regular mail server. Finally, you instruct MailShield to forward all mail it receives on to your regular mail server. The first step is to install MailShield on a machine that is not running any Mail Server. You need to inform MailShield to forward mail to your mail server, which is running on the other machine, at another TCP/IP address. This is done by editing the smtpserv.txt file. If you are installing MailShield on Windows, the MailShield setup program will directly ask you for this setting, when it asks "please enter the TCP/IP address and port number of your SMTP server." answer as indicated below. For example, if your mail server is at TCP/IP address "207.105.6.10", and is a regular SMTP service (i.e., running on port 25), the setting would be: 207.105.6.10 25 If you are unsure what TCP/IP address your mail server is running on, you should consult a system administrator. MailShield cannot forward mail correctly if it is not given the correct TCP/IP address of your mail server. Now, you will need to have the person who administers your DNS records change your DNS settings so that mail for your domain(s) is sent to the MailShield machine, instead of to your mail server. MailShield will take care of forwarding mail to your mail server. For example, if your domain is called "yourdomain.com", and your mail server is called "mail.yourdomain.com", you might find a DNS entry like so: yourdomain.com. IN MX mail.yourdomain.com. You would then add an 'A' record for your MailShield server, which defines the TCP/IP address of the machine running MailShield, like so: shield.yourdomain.com. IN A 207.90.14.4 Working with Mail Servers 56 Finally, you would change the MX record for your domain from using "mail.yourdomain.com" to instead use "shield.yourdomain.com", like so: yourdomain.com. IN MX shield.yourdomain.com. You are now ready to use MailShield! You can start MailShield in the foreground with the command "shield start". On Windows NT, you can run MailShield as a service. See Command-Line Options. If you are running Unix, you can run MailShield in the background with "shield -bd". Initially, we recommend that you run MailShield in the foreground, so that any error messages are immediately displayed. Sendmail This section explains how to configure your system if you are running the Sendmail mail server. MailShield runs its own SMTP daemon for accepting email. If you are on Unix, you are probably running "Sendmail" (or some other mail server), you will need to decide which method you want to use so that MailShield can both receive email and forward it to Sendmail. 1) MAILSHIELD FORWARDS TO ANOTHER TCP/IP ADDRESS: assign two TCP/IP addresses to this machine. Tell Sendmail to run on one TCP/IP address and MailShield runs on the other. 2) MAILSHIELD FORWARDS TO ANOTHER PORT: move Sendmail to another port and inform MailShield to forward mail to sendmail on the alternate port. 3) MAILSHIELD FORWARDS TO ANOTHER MACHINE: install MailShield on a machine with no mail server, and inform MailShield to forward mail to a different machine, which is running your mail server. Method "1" is the easiest approach. Method "2" is recommended for most sites. Depending on your needs, you may find method "3" acceptable, especially if your mail server cannot have its TCP/IP address or port number redefined. Forward to Another Address In this scenario, your machine uses two TCP/IP addresses and has two machine names. Sendmail will run on one TCP/IP address, and receive mail there. MailShield will run on the other TCP/IP address, and receive mail there. The advantage of this approach is that it is very straightforward to set up. For example, if your machine is named "apollo.mycorp.com" and has the TCP/IP address "207.105.6.10", you might also assign your machine the TCP/IP address "207.105.6.11" and have Sendmail listen to that address. MailShield would listen on the .10 address and forward email to sendmail on the .11 address. Add a new TCP/IP address The first step in implementing this method is to obtain, from your network administrator, a second TCP/IP address. A DNS hostname for your second machine is not needed. Working with Mail Servers 57 The next step is to configure Sendmail to use only one TCP/IP address. If you do not do this, Sendmail will automatically use all the TCP/IP addresses on your machine and none will be available for MailShield. To restrict Sendmail to one TCP/IP address, add the following line to the top of your /etc/mail/sendmail.cf file: OOAddr=207.105.6.11 Substituting your 1st TCP/IP address for 207.105.6.11. This Sendmail option is explained in the "Options" chapter of the O'Reilly Sendmail book. You will now need to restart Sendmail. Be sure to telnet to port 25 on each TCP/IP address to ensure that Sendmail is using the correct TCP/IP address. apollo# telnet 207.105.6.11 25 Trying 207.105.6.11... Connected to 207.105.6.11. Escape character is '^]'. 220 apollo.mycorp.com ESMTP Sendmail 8.8.5/8.8.5; Mon, 16 Jun 1997 apollo# telnet 207.105.6.10 25 Trying 207.105.6.10... telnet: Unable to connect to remote host: Connection refused Configure MailShield You will now need to tell MailShield to use the 1st TCP/IP address. This is done by editing the tcpip.txt file. In this example, the setting would be: 207.105.6.10 You now need to inform MailShield to forward mail to your mail server, which is running on the other TCP/IP address. This is done by editing the smtpserv.txt file. In this example, the setting would be: 207.105.6.11 25 Change your DNS settings to point to MailShield You will now need to change your corporate DNS setup so that mail is no longer sent directly to your mail server, but is instead sent to MailShield. If you do not know about DNS, you will need help from your system administrator. For example, if your company is named "yourcompany.com", and now receives mail at "mail.yourcompany.com", you would change this from this: yourcompany.com. IN MX 10 mail.yourcompany.com. to this: yourcompany.com. IN MX 10 shield.yourcompany.com. You are now ready to use MailShield! You can start MailShield in the foreground with the command "shield start". Working with Mail Servers 58 If you are running Unix, you can run MailShield in the background with "shield -bd". On Windows NT, you can run MailShield as a service. See Command-Line Options. Initially, we recommend that you run MailShield in the foreground, so that any error messages are immediately displayed. Adding a TCP/IP Address Adding a TCP/IP address on Windows 95/NT Go to the Control Panel, Click on Networks, Click on Protocols, Click on TCP/IP, Click on Advanced, and you will see a list of TCP/IP addresses. You can add additional TCP/IP addresses on this screen. Adding a TCP/IP address on Solaris You can add this TCP/IP address to your Solaris system with a command such as this: ifconfig le0:1 207.105.6.11 up In this example, the Ethernet adapter "le0" has been assigned a second address (with the ":1") of "207.105.6.11" and is now up. You might want to add this command to a startup file, such as /etc/rc2.d/S72inetsvc so that this command executes automatically at system startup. Forward to Another Port The first step is to configure Sendmail to listen to another TCP/IP port. If you do not do this, Sendmail will automatically listen to port 25, which will conflict with MailShield. To have Sendmail listen to another TCP/IP port, add the following line to the top of your /etc/mail/sendmail.cf file: OOPort=26 This Sendmail option is explained in the "Options" chapter of the O'Reilly Sendmail book. You will now need to restart Sendmail. Be sure to telnet to port 25 and port 26 to ensure that Sendmail is using the correct TCP/IP address. apollo# telnet 207.105.6.11 26 Trying 207.105.6.11... Connected to 207.105.6.11. Escape character is '^]'. 220 apollo.mycorp.com ESMTP Sendmail 8.8.5/8.8.5; Mon, 16 Jun 1997 apollo# telnet 207.105.6.11 25 Trying 207.105.6.11... telnet: Unable to connect to remote host: Connection refused Working with Mail Servers 59 You now need to inform MailShield to forward mail to your mail server, which is running on the other TCP/IP port. This is done by editing the smtpserv.txt file. In this example, the setting would be: 127.0.0.1 26 You are now ready to use MailShield! You can start MailShield in the foreground with the command "shield start". If you are running Unix, you can run MailShield in the background with "shield -bd". On Windows NT, you can run MailShield as a service. See Command-Line Options. Initially, we recommend that you run MailShield in the foreground, so that any error messages are immediately displayed. Forward to Another Machine See Generic Setup with 2 Machines. Post.Office The way to have Post.Office coexist with MailShield is to have Post.Office listen to another port besides port 25 (the SMTP mail default port). Let MailShield listen on port 25 and then tell MailShield to forward mail on to Post.Office. Here are the steps to have Post.Office and MailShield coexist: Move Post.Office to Another Port Here are the instructions, copied directly from Post.Office FAQ item titled "Changing Port Numbers". NT only: How do I change the SMTP Port 25 something else? That information is stored in the registry and can be modified for Post.Office. 1. As a local NT Administrator for that host, open the Registry Editor. 2. Within HKEY_LOCAL_MACHINE select: SOFTWARE -> Software.com -> post.office -> SMTP-Accept -> Config 3. Double-click on the "Socket" Key to edit it. 4. Change the value from 25 to 26 (for example) and click on OK. 5. If you do not have permission to save this value, you will need to: select the Security Menu Option -> Owner-> Take Ownership; select the Security Menu Option again -> Permissions -> ; highlight your administrative self; select the Type of Access Pull Down and select Full Control; select OK; now try the edit the Socket Key. 6.You will now need to stop and start the Post.Office service in your Control Panel - Services Window. UNIX only: How do I change the SMTP Port 25 in UNIX or SunOS to something else? Working with Mail Servers 60 You can update some database information in UNIX by E-mailing to configuration and specifying the appropriate parameters. As always, think safety first. You should save a copy of: /var/spool/post.office/config/SMTP-Accept as a backup so you can restore it if necessary. From an account with Postmaster privileges, perform the following. 1. If you do not already have one, add a "form security password to the security form. 2. Construct a mail message to "configuration@yourhost" 3. The body should contain: Postmaster-Password: [your PM password] Form-Security-Password: [your FS password] (This is on the Security form and can't be blank) Form: [Global Field Setup] Form-Identifier: [None] SMTP-Accept/Config/Socket: [26] (or whatever port you want) 4. Send the message to configuration. Install and Configure MailShield * Install MailShield (if installing on Windows, read below). * You will now need to set the SMTP Server setting in MailShield. If you are installing MailShield on Windows, the setup program will ask you for the TCP/IP and port of your mail server (this is the 4th configuration question). If you are not installing on Windows, or have already installed on Windows, and now need to reconfigure MailShield, you can set this value by editing smtpserv.txt. If you moved Post.Office to port 26, your SMTP server is now located at: 127.0.0.1 26 You are now ready to use MailShield! You can start MailShield in the foreground with the command "shield start". If you are running Unix, you can also run MailShield in the background with "shield -bd". On Windows NT, you can also run MailShield as a service. See Command- Line Options. Initially, we recommend that you run MailShield in the foreground, so that any error messages are immediately displayed. MDaemon The way to have MDaemon coexist with MailShield is to have MDaemon listen to another port besides port 25 (the SMTP mail default port). Let MailShield listen on port 25 and then tell MailShield to forward mail on to MDaemon. Here are the steps to have MDaemon and MailShield coexist: Move MDaemon to Another Port Working with Mail Servers 61 Go to the "Setup" pull down menu, and choose the "Primary Domain" choice. A window labeled "Primary Domain Configuration" should appear. Click on the tab labeled "Ports & DNS" Locate the option that is labeled: "Listen for inbound SMTP events on this TCP port: [25]". Change the number "25" to another free port, such as "26" Click on the button labeled "Bind to new port values now" Click on the "ok" button. Install and Configure MailShield * Install MailShield (if installing on Windows, read below). * You will now need to set the SMTP Server setting in MailShield. If you are installing MailShield on Windows, the setup program will ask you for the TCP/IP and port of your mail server (this is the 4th configuration question). If you are not installing on Windows, or have already installed on Windows, and now need to reconfigure MailShield, you can set this value by editing smtpserv.txt. If you moved MDaemon to port 26, your SMTP server is now located at: 127.0.0.1 26 You are now ready to use MailShield! You can start MailShield in the foreground with the command "shield start". If you are running Unix, you can also run MailShield in the background with "shield -bd". On Windows NT, you can also run MailShield as a service. See Command- Line Options. Initially, we recommend that you run MailShield in the foreground, so that any error messages are immediately displayed. Qmail The simplest way to have MailShield coexist with Qmail is to give MailShield its own TCP/IP address on your system. Here are the steps to do this: Add a new TCP/IP address * Add a new TCP/IP address to your system. Make sure that MetaInfo Sendmail is not using it, by telnetting to port 25 of that TCP/IP address. There should be no connection accepted when you try this telnet command. * Add a DNS 'A' record for this new TCP/IP address, for example: shield.yourcompany.com. IN A 207.105.16.6 * Tell Qmail not to listen to this new TCP/IP address. You must be running Qmail under "tcpserver" to do this. Consult your tcpserver documentation on how to do this. Install and Configure MailShield * Install MailShield (if installing on Windows, read below). Working with Mail Servers 62 * You will now need to set the SMTP Server setting in MailShield. If you are installing MailShield on Windows, the setup program will ask you for the TCP/IP and port of your mail server (this is the 4th configuration question). * If you are not installing on Windows, or have already installed on Windows, and now need to reconfigure MailShield, you can set this value by editing smtpserv.txt. * For example, if Qmail is listening on "207.105.16.2", you would specify: 207.105.16.2 25 * If you are installing on Windows, finish the installation. * You will now need to tell MailShield to only listen to one TCP/IP address: the free TCP/IP address you just created. This is done by editing the bind.txt file. For example, if your free TCP/IP address is 207.105.16.6, you would enter: 207.105.16.6 Change your DNS settings to point to MailShield You will now need to change your corporate DNS setup so that mail is no longer sent directly to your mail server, but is instead sent to MailShield. If you do not know about DNS, you will need help from your system administrator. For example, if your company is named "yourcompany.com", and now receives mail at "mail.yourcompany.com", you would change this from this: yourcompany.com. IN MX 10 mail.yourcompany.com. to this: yourcompany.com. IN MX 10 shield.yourcompany.com. You are now ready to use MailShield! You can start MailShield in the foreground with the command "shield start". You can also run MailShield as a service. See Command-Line Options. Initially, we recommend that you run MailShield in the foreground, so that any error messages are immediately displayed. MetaInfo Sendmail MailShield and MetaInfo Sendmail coexist by using different TCP/IP addresses on the same machine. Add a new TCP/IP address * Add a new TCP/IP address to your system. Make sure that MetaInfo Sendmail is not using it, by telnetting to port 25 of that TCP/IP address. There should be no connection accepted when you try this telnet command. * Add a DNS 'A' record for this new TCP/IP address, for example: shield.yourcompany.com. IN A 207.105.16.6 Working with Mail Servers 63 Install and Configure MailShield * Install MailShield (if installing on Windows, read below). * You will now need to set the SMTP Server setting in MailShield. If you are installing MailShield on Windows, the setup program will ask you for the TCP/IP and port of your mail server (this is the 4th configuration question). * If you are not installing on Windows, or have already installed on Windows, and now need to reconfigure MailShield, you can set this value by editing smtpserv.txt. * For example, if MetaInfo Sendmail is listening on "207.105.16.2", you would specify: 207.105.16.2 25 * If you are installing on Windows, finish the installation. * You will now need to tell MailShield to only listen to one TCP/IP address: the free TCP/IP address you just created. This is done by editing the bind.txt file. For example, if your free TCP/IP address is 207.105.16.6, you would enter: 207.105.16.6 Change your DNS settings to point to MailShield You will now need to change your corporate DNS setup so that mail is no longer sent directly to your mail server, but is instead sent to MailShield. If you do not know about DNS, you will need help from your system administrator. For example, if your company is named "yourcompany.com", and now receives mail at "mail.yourcompany.com", you would change this from this: yourcompany.com. IN MX 10 mail.yourcompany.com. to this: yourcompany.com. IN MX 10 shield.yourcompany.com. You are now ready to use MailShield! You can start MailShield in the foreground with the command "shield start". You can also run MailShield as a service. See Command-Line Options. Initially, we recommend that you run MailShield in the foreground, so that any error messages are immediately displayed. Netscape Mail Server The way to have Netscape Mail Server coexist with MailShield is to have Netscape listen to another port besides port 25 (the SMTP mail default port). Let MailShield listen on port 25 and then tell MailShield to forward mail on to the Netscape Mail Server. Here are the steps to have Netscape Mail Server and MailShield coexist: Move Netscape Mail to Another Port Working with Mail Servers 64 * Use the registry editor (regedt32.exe) to move Netscape Mail Server port 26. The key you want to change is located at HKEY_LOCAL_MACHINE\Software\Netscape\MailServer\SMTP- Accept\Config\Socket Change this value from "25" to "26" * Restart your Netscape Mail Server. Install and Configure MailShield * Install MailShield (if installing on Windows, read below). * You will now need to set the SMTP Server setting in MailShield. If you are installing MailShield on Windows, the setup program will ask you for the TCP/IP and port of your mail server (this is the 4th configuration question). If you are not installing on Windows, or have already installed on Windows, and now need to reconfigure MailShield, you can set this value by editing smtpserv.txt. If you moved Netscape Mail Server to port 26, your SMTP server is now located at: 127.0.0.1 26 You are now ready to use MailShield! You can start MailShield in the foreground with the command "shield start". If you are running Unix, you can also run MailShield in the background with "shield -bd". On Windows NT, you can also run MailShield as a service. See Command- Line Options. Initially, we recommend that you run MailShield in the foreground, so that any error messages are immediately displayed. MailSite The way to have MailSite coexist with MailShield is to have MailSite listen to another port besides port 25 (the SMTP mail default port). Let MailShield listen on port 25 and then tell MailShield to forward mail on to MailSite. Here are the steps to have MailSite and MailShield coexist: Move MailSite to another port * Use the registry editor (regedt32.exe) to move MailSite to port 26. The key you want to create is located at HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ SMTPRS\Parameters This key holds certain configuration information relating exclusively to the SMTPRS service (Please note that your version of the product may use a different name for the SMTPRS service, such as SMTPRA.). You should create a new value (use "Edit/Add Value" menu) with a Value Name of "PortNo", a Data Type of REG_DWORD, and a Data of "26" (be sure to choose Radix: "Decimal"). * Restart MailSite. Working with Mail Servers 65 Install and Configure MailShield * Install MailShield (if installing on Windows, read below). * You will now need to set the SMTP Server setting in MailShield. If you are installing MailShield on Windows, the setup program will ask you for the TCP/IP and port of your mail server (this is the 4th configuration question). If you are not installing on Windows, or have already installed on Windows, and now need to reconfigure MailShield, you can set this value by editing smtpserv.txt. If you moved MailSite to port 26, your SMTP server is now located at: 127.0.0.1 26 You are now ready to use MailShield! You can start MailShield in the foreground with the command "shield start". If you are running Unix, you can also run MailShield in the background with "shield -bd". On Windows NT, you can also run MailShield as a service. See Command- Line Options. Initially, we recommend that you run MailShield in the foreground, so that any error messages are immediately displayed. Exim The way to have Exim coexist with MailShield is to have Exim listen to another port besides port 25 (the SMTP mail default port). Let MailShield listen on port 25 and then tell MailShield to forward mail on to Exim. Here are the steps to have Exim and MailShield coexist: Move Exim to another port * Locate the daemon_smtp_service option in your Exim configuration file. By default, this option is unset. You should set it to another port number besides 25. In this example we will use port 26. Here is the Exim documentation on this feature: Option: daemon_smtp_service Type: string Default: unset This option specifies the numerical port number or the service name equivalent on which the daemon is to listen for incoming SMTP calls. It is overridden by `-oX' on the command line. If this option is not set, the service name `smtp' is used. Once you set this option, you will need to recompile Exim for this change to take effect. * Restart Exim. Install and Configure MailShield * Install MailShield (if installing on Windows, read below). Working with Mail Servers 66 * You will now need to set the SMTP Server setting in MailShield. If you are installing MailShield on Windows, the setup program will ask you for the TCP/IP and port of your mail server (this is the 4th configuration question). If you are not installing MailShield on Windows, or have already installed on Windows, and now need to reconfigure MailShield to send mail to Exim. You can set this value by editing smtpserv.txt. If you moved Exim to port 26, your SMTP server is now located at: 127.0.0.1 26 So, edit "smtpserv.txt" (which you will find in the MailShield 'config' directory) to have this setting. You are now ready to use MailShield! You can start MailShield in the foreground with the command "shield start". If you are running Unix, you can also run MailShield in the background with "shield -bd". On Windows NT, you can also run MailShield as a service. See Command- Line Options. Initially, we recommend that you run MailShield in the foreground, so that any error messages are immediately displayed. NTmail The way to have NTmail coexist with MailShield is to have NTmail listen to another port besides port 25 (the SMTP mail default port). Let MailShield listen on port 25 then tell MailShield to forward mail on to NTmail. Here are the steps to have NTmail and MailShield coexist: Move NTmail to another port * Use the registry editor (regedt32.exe) to move NTmail port 26. The key you want to change is located at HKEY_LOCAL_MACHINE\Software\InternetShopper\Mail\Para meters\PortSMTPReceive Change this value from "25" to "26". If the PortSMTPReceiv value does not exist under the "Parameters" key, you will need to create it. Choose the "Edit \ Add Value" menu option. For "Value Name", enter "PortSMTPReceive" (remember to capitalize the text exactly as it is shown here) and for "Data Type" choose REG_DWORD. A window will pop up asking for a value. Choose "decimal" as the "Radix" in the window, and type "26" in the "Data" field. The NTmail reference manual documents this option as: This parameter defines which port the SMTP server will listen to when accepting email. The Internet Standard is to use port 25, but you may wish to run Working with Mail Servers 67 another mail server on the same machine and have it direct mail to NTmail at this new port. * Restart NTmail Install and Configure MailShield * Install MailShield (if installing on Windows, read below). * You will now need to set the SMTP Server setting in MailShield. If you are installing MailShield on Windows, the setup program will ask you for the TCP/IP and port of your mail server (this is the 4th configuration question). If you are not installing on Windows, or have already installed on Windows, and now need to reconfigure MailShield, you can set this value by editing smtpserv.txt. If you moved NTmail to port 26, your SMTP server is now located at: 127.0.0.1 26 You are now ready to use MailShield! You can start MailShield in the foreground with the command "shield start". If you are running Unix, you can also run MailShield in the background with "shield -bd". On Windows NT, you can also run MailShield as a service. See Command- Line Options. Initially, we recommend that you run MailShield in the foreground, so that any error messages are immediately displayed. Microsoft IMS / IIS Mail The way to have the mail server that comes with IIS coexist with MailShield is to have IIS Mail listen to another port besides port 25 (the SMTP mail default port). Let MailShield listen on port 25 and then tell MailShield to forward mail on to IIS Mail. Here are the steps to have IIS Mail and MailShield coexist: Move IIS Mail to another port Two different methods for doing this are available. Use whichever you prefer (some earlier versions of IIS do not support the first method). * If using IIS v4, you can use the IIS management console. Run the "IIS Management Console". Click on the left-hand side, to select "Console Root / Internet Information Server / YOUR-SERVER-NAME / Default SMTP Site". Then right click on "Default SMTP site" and choose "properties". On the first tab, labeled "Default SMTP Site" you will find a section labeled "Incoming connections", and a field labeled: "TCP Port" which has a current setting of 25. Change that setting to 26. Finally, go into the Control Panel, Services, then stop and restart the service named "Microsoft SMTP Service". * Or, you can edit the registry setting directly. To do thus, use the registry editor (regedt32.exe) to move IIS Mail port 26. The key you want to change is located at: HKEY_LOCAL_MACHINE\system\currentcontrolset\control\s erviceprovider\servicetypes\smtpsrc\TcpPort Working with Mail Servers 68 Change this value from "25" to "26". If you are looking at hexadecimal values, you are changing this key from "19" to "1A". Restart the IIS mail server (the "Microsoft SMTP Service" control panel service) or reboot your system to have this change take effect. Install and Configure MailShield * Install MailShield (if installing on Windows, read below). * You will now need to set the SMTP Server setting in MailShield. If you are installing MailShield on Windows, the setup program will ask you for the TCP/IP and port of your mail server (this is the 4th configuration question). If you are not installing on Windows, or have already installed on Windows, and now need to reconfigure MailShield, you can set this value by editing smtpserv.txt. If you moved IIS mail to port 26, your SMTP server is now located at: 127.0.0.1 26 You are now ready to use MailShield! You can start MailShield in the foreground with the command "shield start". If you are running Unix, you can also run MailShield in the background with "shield -bd". On Windows NT, you can also run MailShield as a service. See Command- Line Options. Initially, we recommend that you run MailShield in the foreground, so that any error messages are immediately displayed. Lotus Notes r4.61 The way to have Notes coexist with MailShield is to have Notes listen to another port besides port 25 (the SMTP mail default port). Let MailShield listen on port 25 and then tell MailShield to forward mail on to Notes. Here are the steps to have Notes and MailShield coexist: Move Notes to another port You will need to be running Notes 4.61, and not r5. These are the directions from Lotus, available in the release notes for version 4.61: SPR# HAT3KELTE - Added an SMTP MTA NOTES.ini variable to change TCP/IP port SMTP MTA uses so the MTA can run on a partitioned server. This is controlled by an untested .ini variable, SMTPMTA_IPPORT, used to change the TCP/IP port 25 on which SMTP MTA listens. See "untested .ini variables" for more information. Change the SMTPMTA_IPPORT value to be 26. Stop and restart your Notes server. Install and Configure MailShield * Install MailShield. * You will now need to set the SMTP Server setting in MailShield. If you are installing MailShield on Windows, the setup program will ask you for the TCP/IP and port of your mail server (this is the 4th configuration question). If you are not Working with Mail Servers 69 installing on Windows, or have already installed on Windows, and now need to reconfigure MailShield, you can set this value by editing smtpserv.txt. If you moved Notes to port 26, your Notes SMTP server is now located at: 127.0.0.1 26 You are now ready to use MailShield! You can start MailShield in the foreground with the command "shield start". If you are running Unix, you can also run MailShield in the background with "shield -bd". On Windows NT, you can also run MailShield as a service. See Command- Line Options. Initially, we recommend that you run MailShield in the foreground, so that any error messages are immediately displayed. Lotus Domino r5 The way to have Domino coexist with MailShield is to have Domino listen to another port besides port 25 (the SMTP mail default port). Let MailShield listen on port 25 and then tell MailShield to forward mail on to Domino. Here are the steps to have Domino and MailShield coexist: Move Domino to another port To change the SMTP incoming port number, go to "Domino Administrator", "Server/Current Server Document" then click on the "Ports" tab, then the "Internet Ports" tab, then change the number "25" to "26" in the "TCP/IP Port Number" row of the "Mail (SMTP Inbound". Save the document, then stop and restart your Domino server. Install and Configure MailShield * Install MailShield. * You will now need to set the SMTP Server setting in MailShield. If you are installing MailShield on Windows, the setup program will ask you for the TCP/IP and port of your mail server (this is the 4th configuration question). If you are not installing on Windows, or have already installed on Windows, and now need to reconfigure MailShield, you can set this value by editing smtpserv.txt. If you moved Notes to port 26, your Notes SMTP server is now located at: 127.0.0.1 26 You are now ready to use MailShield! You can start MailShield in the foreground with the command "shield start". If you are running Unix, you can also run MailShield in the background with "shield -bd". On Windows NT, you can also run MailShield as a service. See Command- Line Options. Initially, we recommend that you run MailShield in the foreground, so that any error messages are immediately displayed. Working with Mail Servers 70 Microsoft Exchange The way to have Microsoft Exchange coexist with MailShield is to have Microsoft Exchange listen to another port besides port 25 (the SMTP mail default port). Let MailShield listen on port 25 and then tell MailShield to forward mail on to Microsoft Exchange. Here are the steps to have Microsoft Exchange and MailShield coexist: Move Exchange to another port * With a text editor (such as notepad.exe) edit the file: C:\Winnt\system32\drivers\etc\services -- locate the line that says: smtp 25/tcp mail And change it to say: smtp 26/tcp mail Now save this file. * Restart Exchange Install and Configure MailShield * Install MailShield (if installing on Windows, read below). * You will now need to set the SMTP Server setting in MailShield. If you are installing MailShield on Windows, the setup program will ask you for the TCP/IP and port of your mail server (this is the 4th configuration question). If you are not installing on Windows, or have already installed on Windows, and now need to reconfigure MailShield, you can set this value by editing smtpserv.txt. If you moved Exchange to port 26, your SMTP server is now located at: 127.0.0.1 26 You are now ready to use MailShield! You can start MailShield in the foreground with the command "shield start". If you are running Unix, you can also run MailShield in the background with "shield -bd". On Windows NT, you can also run MailShield as a service. See Command- Line Options. Initially, we recommend that you run MailShield in the foreground, so that any error messages are immediately displayed. AltaVista Mail The way to have AltaVista Mail coexist with MailShield is to have AltaVista Mail listen to another port besides port 25 (the SMTP mail default port). Let MailShield listen on port 25 and then tell MailShield to forward mail on to AltaVista Mail. Here are the steps to have AltaVista Mail and MailShield coexist: Move AltaVista Mail to another port Working with Mail Servers 71 * With a text editor (such as notepad.exe) edit the file "_Configuration.dat" which you will find in the "avmail" directory, and locate the line that says "SmtpInboundPort" and change the value to "26" like so: SmtpInboundPort: 26 Now save this file. * Restart AltaVista Mail. Install and Configure MailShield * Install MailShield (if installing on Windows, read below). * You will now need to set the SMTP Server setting in MailShield. If you are installing MailShield on Windows, the setup program will ask you for the TCP/IP and port of your mail server (this is the 4th configuration question). If you are not installing on Windows, or have already installed on Windows, and now need to reconfigure MailShield, you can set this value by editing smtpserv.txt. If you moved AltaVista Mail to port 26, your SMTP server is now located at: 127.0.0.1 26 You are now ready to use MailShield! You can start MailShield in the foreground with the command "shield start". If you are running Unix, you can also run MailShield in the background with "shield -bd". On Windows NT, you can also run MailShield as a service. See Command- Line Options. Initially, we recommend that you run MailShield in the foreground, so that any error messages are immediately displayed. SLMail The way to have SLMail v3 coexist with MailShield is to have SLMail listen to another port besides port 25 (the SMTP mail default port). Let MailShield listen on port 25 and then tell MailShield to forward mail on to SLMail. Here are the steps to have SLMail and MailShield coexist: Move SLMail to another port * Open up the SLMail control panel, and go to the tab labeled "Access". Locate the entry labeled "SMTP Port". This is currently set to 25. Change it to be 26. * Restart SLMail. Install and Configure MailShield * Install MailShield (if installing on Windows, read below). * You will now need to set the SMTP Server setting in MailShield. If you are installing MailShield on Windows, the setup program will ask you for the TCP/IP and port of your mail server (this is the 4th configuration question). If you are not installing on Windows, or have already installed on Windows, and now need to reconfigure MailShield, you can set this value by editing smtpserv.txt. Working with Mail Servers 72 If you moved SLMail to port 26 (as instructed above), your SMTP server is now located at: 127.0.0.1 26 You are now ready to use MailShield! You can start MailShield in the foreground with the command "shield start". On Windows NT, you can also run MailShield as a service. See Command-Line Options. Initially, we recommend that you run MailShield in the foreground, so that any error messages are immediately displayed. LSMTP The way to have LSMTP coexist with MailShield is to have LSMTP listen to another port besides port 25 (the SMTP mail default port). Let MailShield listen on port 25 and then tell MailShield to forward mail on to LSMTP. Here are the steps to have LSMTP and MailShield coexist: Move LSMTP to another port 1. Open LSMTP Control Program. 2. Click Configure menu item. 3. Select "SMTP & Reports" tab. 4. Change "SMTP listener port" from 25 to 26. * Restart LSMTP. Install and Configure MailShield * Install MailShield (if installing on Windows, read below). * You will now need to set the SMTP Server setting in MailShield. If you are installing MailShield on Windows, the setup program will ask you for the TCP/IP and port of your mail server (this is the 4th configuration question). If you are not installing on Windows, or have already installed on Windows, and now need to reconfigure MailShield, you can set this value by editing smtpserv.txt. If you moved LSMTP to port 26 (as instructed above), your SMTP server is now located at: 127.0.0.1 26 You are now ready to use MailShield! You can start MailShield in the foreground with the command "shield start". On Windows NT, you can also run MailShield as a service. See Command-Line Options. Initially, we recommend that you run MailShield in the foreground, so that any error messages are immediately displayed. Working with Mail Servers 73 Imail The way to have Imail coexist with MailShield is to have Imail listen to another port besides port 25 (the SMTP mail default port). Let MailShield listen on port 25 and then tell MailShield to forward mail on to Imail. Here are the steps to have Imail and MailShield coexist: Move Imail to another port * Run the Windows Registry Editor. This is a program with a filename of "regedt32.exe" * Locate the section in the "HKEY_LOCAL_MACHINE" window in the category "SYSTEM \ CurrentControlSet \ Services \ SMTPD32 \ Parameters" Click on this setting, and several fields such as "Version" and "AcceptAny" will appear on the right window in the Windows Registry Editor. * Choose the "Edit \ Add Value" menu option. For "Value Name", enter "Port" (remember to capitalize the P in Port) and for "Data Type" choose REG_DWORD. A window will pop up asking for a value. Choose "decimal" as the "Radix" in the window and type "26" in the "Data" field. * You should now see a new value which says: "Port: REG_DWORD " 0x1a. * Go to the "services" control panel, then stop and start the "Imail SMTP Server" service. * Imail is now configured to listen to port 26 Install and Configure MailShield * Install MailShield * You will now need to set the SMTP Server setting in MailShield. If you are installing MailShield on Windows, the setup program will ask you for the TCP/IP and port of your mail server (this is the 4th configuration question). If you are not installing on Windows, or have already installed on Windows, and now need to reconfigure MailShield, you can set this value by editing smtpserv.txt. If you moved Imail to port 26 (as instructed above), your SMTP server is now located at: 127.0.0.1 26 Set "smtpserv.txt" to this value. You are now ready to use MailShield! You can start MailShield in the foreground with the command "shield start". On Windows NT, you can also run MailShield as a service. See Command-Line Options. Initially, we recommend that you run MailShield in the foreground, so that any error messages are immediately displayed. Frequently Asked Questions 75 Frequently Asked Questions Common Questions What does MailShield Do? Question: What does MailShield do? MailShield is a general-purpose email-filtering tool. With MailShield you get the tools to do just about anything you want with email. The most common use for MailShield is for blocking email that you don't wish to receive and preventing others from abusing your mail server to send mail out against your will. MailShield is a toolkit of techniques and methods that can be applied to any sort of electronic mail. In the current version of MailShield there are about 50 different ways to look at an email message to decide whether you want to accept it or not. For example: whether the recipient list has more people then you think it should, if the email address given in the "To:" header is not valid, or just if the body of the text contains words which you don't think are appropriate for an email message (such as "hot free sex"). The second main function of MailShield, preventing mail relay, is accomplished by having MailShield determine whether a given piece of email is addressed to someone at your organization, or whether it's addressed to someone outside of your organization. If the latter, then it is a mail relay request and you may want to deny it. Oftentimes, people who send bulk mail, such as spam, use mail servers they haven't been granted permission to use to deliver their bulk mail for them, rather than paying for their own services to deliver it. This is an abuse of your bandwidth that you may wish to prevent. How does MailShield work? Question: How does MailShield work? MailShield works by receiving electronic mail for your organization, checking it against its rules and passing the message on to your regular mail server once the message has been processed by the rules. The MailShield rules tell MailShield what to do with each piece of incoming mail. For example, if the message is a mail relay request that you have not allowed, MailShield will refuse the message instead of passing it on. If the message is valid, and does not appear to be junk mail, MailShield can forward it on to your mail server for normal processing. Other uses of MailShield might be to have a backup mail server which receives additional copies of your email (for instance, all refused mail can be backed up or rerouted for Frequently Asked Questions 76 action), to route mail addressed from one address to another address instead, automatically answer some email messages (such as with an autoresponder or DocBot), or most any electronic mail processing you might need. MailShield has four components. 1) A mail server. 2) Configuration files. 3) Rule files. 4) A scripting language. Most MailShield users will only be aware of the first two components. The mail server in MailShield receives electronic mail and sends it. The configuration files tell MailShield about your organization, such as the TCP/IP addresses it uses, its domain names, and the settings for the various filtering rules in MailShield (such as "forbidden phrases"). The rule files in MailShield do the actual processing of each email message. The rule files read the configuration files and they are executed for each email message which MailShield receives. The rule files are easy to read as they are written in a simple scripting language specialized for email filtering (based on a simple version of the Perl syntax) and the rules can be easily customized to specific needs. For example, you can add or remove steps in the rule processing by just adding or removing two or three lines of text. Power users may want to use the MailShield scripting language to write new rules in the rule files or to change the existing rules. For most users, the behavior of MailShield can be affected by a changing the configuration files (which contain things such as a list of "forbidden" phrases), rather then directly editing the rules. However, because all MailShield processing is done using this scripting language, a power user can see exactly what MailShield is doing at each step in each email message and can change MailShield to act exactly in the way they want. Everything is in plain sight and customizable. Does it work with everything? Question: Does it work with cc:Mail? Lotus Notes? MailShield Exchange? POP3? Everything? What doesn't it work with? MailShield can work with any email server that can send and receive email over the Internet. Depending on the mail server software, MailShield can work on the same machine as your mail server, or it may need a separate machine. For most of the popular mail server programs, we have devised ways for MailShield to run on the same machine as your mail server. However, if your mail server cannot coexist with MailShield on the same machine, you can use two machines instead. MailShield works by running in place of your mail server, accepting the mail on behalf of your mail server, and then delivering the mail to your mail server. To the outside world, nothing has changed, they still send email to the server that you list, except that now they talk to MailShield, which then talks to your mail server, rather than having the world talk directly to your mail server. See our web site for a list of mail servers for which MailShield can coexist on the same machine. Why is Relaying a problem? Question: Why has the relay issue suddenly become such a big problem? Frequently Asked Questions 77 Unauthorized mail relaying has recently become a big problem, because spamming has suddenly become very popular, and the best way for spammers to hide their tracks is to relay through other people's mail servers. Also, many spammers do not have the resources to send the mail themselves, so they need to steal those resources from other people, by using other people's mail servers to send the spam out for them. Mail relaying is such a serious problem that if your mail server is not equipped to deal with it, it is likely that within a week or two as much as half the mail your system sends out will be mail relay requests that do not directly benefit you. Worse, if a particularly large bulk mail job gets thrown at your mail server, it may crash or get so bogged down that your legitimate email might not get through. For example, when we set up our own email server, we were using Solaris Unix with the default Sendmail configuration, and within one week we started to get unauthorized mail relay requests. We do not know how these people found our server so quickly, but we think the serious spammers have robots which scan the Internet looking for mail servers that they can abuse. By the time that we put MailShield on our server to block mail relay requests, we found that there were a dozen different email messages being queued per day to be relayed on our server. It also appeared that this was the work of several people, not just the work of a single company. Mail relay is a serious problem that needs to be addressed. Many mail servers default to accepting all relay requests. For example, the version of Sendmail that comes built-in to all Sun Solaris Unix computers is totally vulnerable to mail relay abuse. Other mail servers take an all or nothing approach, allowing the administrator to either completely enable or completely disable all mail relaying. The problem with this approach is that you want certain users (such as your own employees) to be able to relay mail through you. Programs such as Netscape mail and Eudora need a mail relay server in order to send mail out. MailShield lets you keep using your current mail servers, while adding mail relay protection. Can it protect against Relaying? Question: How does MailShield protect against relaying? And what if I do want to relay for certain customers, but deny service to spammers? Protecting a mail server from mail relaying is relatively straightforward, and there are other products that can stop relaying. However, the capabilities in MailShield are more sophisticated than other products, and it offers many more functions that are not available anywhere else: it allows you to specify who you will relay mail for, and exclude everyone else. This is done by defining the domain names that your mail server will accept so that all mail addressed To: those domains is automatically accepted. Then, if people should be using your server for mail relaying (such as your own local users with Netscape or Eudora), then you need to define who those people are. You can define people who are acceptable for relaying by giving MailShield the host names, or hostname patterns, of those approved people by specifying individual TCP/IP addresses, a TCP/IP address range, or a list of specific From: addresses of people who should be allowed to relay mail through you. Allowing specific "From:" addresses is particularly powerful. For example, if someone from your company is traveling and is using a host or TCP/IP address not on your list, you still might want them to be able to relay through you. You would allow this by matching their From: address, even if they are temporarily hosted on an unrecognized server. Frequently Asked Questions 78 Will it slow mail down? Question: Does running MailShield slow down mail handling? MailShield uses the ultra high-performance email engine used in our List Manager email list server program. Because of this, MailShield causes a minimal load on the machine it is running on. In fact, because so much of the email received by a typical mail server is unwanted email, we find that installing MailShield actually increases the speed of mail handling because the mail server has so much less email to deal with once spam is removed. On a typical mail server (a low end Sun workstation) we have timed MailShield receiving messages at 10 messages per second (36,000 messages per hour) while only using 10% of the system. We estimate that MailShield can receive email at 40 times the rates of a typical mail server, so speed is usually not an issue. Will it add to my overhead? Question: You said MailShield could actually cut down on our bandwidth and overhead. How? First, if your mail system administrator has not already secured your server from mail relay abuse, MailShield will take care of that problem. Secondly, on a large system, junk mail is often a large amount of the daily mail volume. By getting rid of most of that junk mail, MailShield lowers the amount of work that the mail servers need to do, thus lowering the number of mail servers needed at a given organization. Also, the mail system administrator is usually the person who is contacted by users when a mail bomb or a lot of junk mail comes in and, until MailShield, the mail system administrator did not have effective tools to help those users. At many ISP's, the mail system administrators devise their own techniques for fixing these problems. Sometimes, they would write Perl scripts, or change the Sendmail source code, or write various "hacked together" tools for helping with the problem. This results in haphazard and nonstandard installations that may not work if another administrator takes over the server, or if system software is upgraded. MailShield gives the mail system administrator a ready to use toolkit, which already blocks most unwanted mail, and can be easily fine tuned to your organization's particular needs. Because MailShield uses a scripting language to define the rules, if MailShield does not already have a technique, which the mail system administrator or the user wants, it is very easy to add new rules to the MailShield Toolkit. How effective is it? Question: What percentage of spam will MailShield filter out? The current version of MailShield filters about 80% of the spam with less than a one in 1000 false positive rate. We expect that these percentages will improve even further as MailShield goes through additional revisions and improvements. What is the false-positive rate? Question: What percentage of legit messages will MailShield filter out accidentally? Frequently Asked Questions 79 The current version of MailShield has a false positive rate of about one in 1000 messages when you use the default settings. As you change the default settings to be more or less strict, your false positive rates will change accordingly. Can Legitimate mail be rejected? Question: What are the chances that legitimate mail would be rejected? Blocking unwanted email without accidentally blocking wanted mail requires sophisticated techniques. Thankfully, most bulk unsolicited email has patterns in it which do not occur in normal electronic mail that makes it easier to be identified and rejected. For example, because unsolicited email provokes such a negative response, the people who send it often try to conceal their identity, often by masquerading as a legitimate user. MailShield utilizes various methods to determine that the concealed identity is not legitimate. As one example, many spam programs use a To: address of "friend@public.com". The "public.com" domain is not valid, so MailShield can check that the email address given in the To: header is in a valid domain. The chances that legitimate mail will be rejected are extremely low. Because MailShield is meant for corporate customers, its focus is on increasing the utility of electronic mail. If a tool such as MailShield rejected valid mail, it would increase the amount of work for the company, rather then decrease it, even if that time were merely your having to apologize and explain to every person who had been mistakenly rejected. The basic way in which MailShield works is by defining a set of commonly accepted rules by which legitimate mail is identified. Almost all legitimate mail has these traits, and most junk mail messages do not have them. Thus, it's far more likely for an unwanted message to get through than a wanted one to be rejected. Most companies, and users, would agree that actually receiving a few percent of the junk mails that are sent is far better than losing even a few legitimate messages. In the rare case where a piece of legitimate mail breaks one of the rules, it will be rejected. For example, if someone sends you email but has misconfigured their email program so that the "From:" address in their email is not valid, then the message will be rejected by MailShield. One such example is a typographical error such as the user entering their email address as "user@mail,com" vs. "user@mail.com" -- that is, mistakenly using a comma in the their email address where a period should have been used. In this case, since their email address is misconfigured, they are also not receiving replies to their email and your rejecting it is only one of their problems. Even in such a case, however, the sender will likely get immediate feedback that there is a problem. Because MailShield refuses the email message before it even is delivered to your system, the error message indicating the problem to the user will usually be delivered immediately so that he can see there is something wrong. You can program MailShield to deliver error messages, which explain why the message is being rejected, if you wish. On top of these basic legitimacy rules, MailShield allows you to specify text to ban from your email messages. These, of course, have the potential to misfire, so MailShield defaults to no filtering on any particular phrase. However, such a capability may be important to you. For example, if you were to ban any messages containing the words "hot free sex" then any message that contains these words would be rejected, even your spouse sending a joke message offering you "hot free sex". All is not lost, however: you can make exceptions in MailShield that allows Frequently Asked Questions 80 specific people to bypass your rules. You can specify exceptions with an email address, a domain name, or with TCP/IP addresses. What if I reject legitimate mail? Question: It is important that I receive all legitimate mail. How do I recover any accidentally rejected legitimate mail? MailShield can be set up to copy rejected mail to a specific user or file so that it can be reviewed. In addition, you can customize the rejection messages with instructions on how to bypass MailShield if the user cannot otherwise get through. For example, by having a specific address which MailShield's rules do not apply to. You can also set up MailShield to include the reason why the mail is not accepted in the bounce message the sender will get, such as "We do not accept mail with the words 'Make Money Fast' in the subject line." The sender can then fix the problem that caused the bounce and try again. Can it be less aggressive? Question: In what ways can MailShield be configured to be more or less aggressive? By default, MailShield comes configured to be not that aggressive about blocking unwanted email -- its default configuration catches about 90 percent of unwanted email. There are about 50 filters built into MailShield, and by default most of these are turned off. When you first install MailShield, filters, which work nearly 100% of the time with extremely rare false positives, are all enabled. You can then enable more filters, such as the requirement that all mail servers connecting to you have an Internet host name, which are effective at blocking the remaining junk mail, but which have a higher risk of false positive rejection. You can also add your own ban texts to the filters, which look at specific parts of the message. For example, you might want to block all email messages that have "make money fast" in their subject line. Another option is to completely disable all built-in MailShield filters and only reject messages which you have specifically targeted with your own ban text specifications. What about Mailing Lists? Question: Will MailShield stop legitimate mass mailers, such as popular mailing lists I subscribe to? Absolutely not. Lyris Technologies Inc., the people who make MailShield, also make List Manager, a popular email listserver program, which is used for many thousands of legitimate mailing lists. Thus we have a very real interest in making sure that MailShield does not block legitimate mailing list mail, because that would interfere with our own product. Mailing list mail is very easily differentiated from illegitimate mail because mailing list mail can be replied to, has a real "To:" address, comes from a mail server with a full Internet hostname, does not use the third party relay hosts, and does not have forged headers. Of course, if you specifically wish to reject mailing list mail, MailShield can be set up to do it. Frequently Asked Questions 81 What about Usenet Spam? Question: Does MailShield do anything for Usenet spam? No, MailShield is only for email and does not have anything to do with Usenet. Does MailShield help ISP's? Question: Small companies are one problem; we're an Internet Service Provider with tens of thousands of customers. How can MailShield help us? If you are an ISP, your own customers might be signing up the for the purpose of abusing your mail servers as relay hosts. They might only want the accounts for one week -- just long enough for them to get a batch of unsolicited email advertising messages out. Even if you disable their account immediately upon learning of their activities, they can simply go to a new ISP and repeat the cycle. Meanwhile, the damage to you is already done. This is an especially difficult situation because you absolutely need to allow your normal customers to use you as a relay mail server (for Netscape mail and Eudora), but somehow you need to determine who the abusers are and stop them. It gets worse. If you are an ISP and your customers use you as a mail relay host to send spam, all mail from your mail servers may get banned or put on black lists as a frequent source of spam. The problem with this is that all the email sent from your domain could be rejected by other systems which recognize these black lists, and your customers will be very upset. Until MailShield, there has not been an effective way to stop an ISP's own customers from abusing them as a mail relay host. MailShield is the perfect tool to help ISP's keep their own customers from using them as spam platforms. MailShield tracks how many messages a person is attempting to relay, and if that number is larger than a threshold you set, MailShield inserts delays in the mail transaction so that it becomes intolerably slow to send mail. At the same time, your normal users experience no delays if they stay under the maximum that you specify (such as 10 recipients). If they do go slightly above the maximum, they experience only a two-second delay for each additional recipient. This two-second delay will probably not even be noticed by legitimate customers sending to a small number of recipients. However, for someone attempting to send 100,000 spam messages, the delay becomes prohibitive (100,000 X 2 seconds = 55 hours), and the person trying to send the bulk mail will give up and go elsewhere, freeing up your bandwidth for your legitimate users. Occasionally, there is also the problem of a mail bomb, when someone sends thousands of email messages to someone in an attempt to crash their server or, at the very least, make it very difficult for them to perform their normal work. MailShield makes its easy to block email to or from specific people, to stop a mail bomb attack, and to establish rules against mail bombing. For instance, MailShield can be set up so that if any user got more than X amount of e-mails in a set time period, it would send an alert message to the mail administrator to instigate further investigation (including, of course, an email to the administrator's pager). Or, you could set MailShield to watch for duplicate copies of the same message being sent to the same user again and again, and stop accepting the duplicates. This is a good way to stop mail loops, as well as multiple copies of spam. Frequently Asked Questions 82 Does MailShield help Users? Question: Ok, so MailShield is great for the administrators. What about everyone else? Obviously, the people who suffer most from junk mail are the people who receive it. It takes time to read and delete junk mail, and it lowers the general usefulness of electronic mail for that person and for the organization as a whole. Many users get very frustrated with electronic mail when they receive so much junk mail and tend to use it less, or not use it as carefully. Also, if you use the routing capabilities in MailShield, MailShield can send incoming email to the appropriate person without a person needing to look at the message; obviously this also saves time. Finally, in an "email bomb" situation, you want it stopped as quickly as possible to minimize the damage and lost time. For your company's clients, there are several benefits. First, if the junk is filtered out, you will be able to be more responsive to email from your clients. You can also use MailShield's filtering rules to route email directly to the appropriate person, which will lower the amount of time your clients will have to wait to get a response. What about Users in the Field? Question: Some of our users are in the field. How do they benefit from MailShield? A remote user will especially benefit from MailShield, because when they are remote, downloading email often takes much more time than when they are local. Thus, by removing junk mail, the remote user can work faster. MailShield can also block large messages, such as binary attachments, which are especially costly for remote users to download. Also, if a key support person is traveling or on vacation, the mail administrator could route general support questions to employees who are not on travel or vacation, enabling faster customer support instead of waiting for a remote user to re-route the mail to someone else. Does MailShield have other uses? Question: Does MailShield have any uses beyond cutting abuse? Are there ways it can enhance legitimate mail, for instance? Because MailShield is a general toolkit for filtering email, it can be used as a powerful messaging platform to enhance many functions of legitimate mail. For example, you can have MailShield look for any email To: or From: your technical support department, and have MailShield automatically send an extra copy of all tech support correspondence to a tech support database for archiving where it can later be searched by your tech support people. Another example of MailShield might be to automatically route email about certain topics to certain individuals inside your company. For example, if your sales team is divided into Europe, Asia, and the United States, it is simple to have MailShield look at the domain name of the email address on the From: line of mail addressed to sales@yourcompany.com and route the email message to the correct person in your company, for example sending the inquiries by people using the .jp domain to your Asia field office without anyone having to look at it first. The same could be done if there is too much email coming to a particular address for one person to handle, so you can have MailShield automatically balance the email load among the people that you specify. Or, if you wish to know when an employee is leaking sensitive information, you can have all Frequently Asked Questions 83 incoming or outgoing email scanned for the words "Project X", and any mail, which matches, can be sent to your security department for review. Is this different from Sendmail? Question: The new version of Sendmail supposedly has anti-spam features. How is MailShield different? MailShield is different in many ways. The most obvious way is that MailShield works with existing mail servers and does not require you to use Sendmail. Beyond this, Sendmail is different from MailShield in that the features in MailShield provide greater flexibility, a higher success rate, and a lower false rejection rate. For example, the tools in Sendmail are not able to reject based on the body contents of an email message, but only on what is called the "envelope". For example, if a piece of spam is relayed through another server, the MAIL FROM may be a valid email address, so Sendmail lets it through, but the author's email address, the one given in the body text of the message, may not be (i.e., friend@public.com), which MailShield would notice and reject even though Sendmail let it pass. MailShield has a very powerful text searching syntax (called regular expressions) as well as full boolean operands and provides contents-based mail routing, backup systems, load balancing and many other features. Sendmail and MailShield implement similar anti-relay techniques. All the anti-relay techniques in Sendmail are also in MailShield, and MailShield adds a few more (such as allowing relaying based on who the message author is). What about Outgoing Mail? Question: Does MailShield affect outgoing mail? MailShield automatically protects your mail server from being used as an unauthorized mail relay host. To do this it must intercept all outgoing mail before it is passed on to your mail server for regular outbound delivery. The administrator sets up MailShield to allow specific users to relay (relaying means using a mail server to send mail to the outside world). Once this is done, MailShield automatically accepts outgoing mail from the people that have been approved and does not make any changes to that mail. Mail relaying requests from people who have not been approved for relaying are automatically denied. What about dialup accounts? Question: I get a lot of spam, but I'm just a lowly ISP customer. How can I get MailShield's benefits? MailShield is only for mail servers and requires setup by the administrator so, unfortunately, you cannot install it yourself. However, if you are getting a lot of spam it is likely that the other customers of your ISP are also receiving a lot of spam. For this reason, your ISP is probably looking for a solution to their spam problem, and they may not yet know that MailShield is available (MailShield is the first complete solution available to address spam at the mail server level, where the ISP most wants to block it). You should call your ISP or email your support contact and tell them about MailShield. Because MailShield will solve the spam problem for all the users on their server, a MailShield-protected ISP has a competitive advantage over ISP's who do not use MailShield. A large portion of the system load on an ISP's mail server is caused by Frequently Asked Questions 84 spam. This means that the ISP is spending a great amount of money buying machines and bandwidth to receive all this junk email -- junk email that their customers do not even want to receive. Also, by receiving spam, the ISP's customers spend more time connected to the ISP to download all the email they don't want, meaning more modems are needed to serve the customers, further increasing the ISP's cost for receiving spam. By installing MailShield the ISP can reject email before it even loads down to their mail server and goes further downstream. Thus, they are reducing the amount of hardware needed to receive email. This translates to direct savings for the ISP -- a savings that can easily pay for MailShield and, of course, allow them to serve more customers with the hardware and bandwidth they already have. You might also want to tell your ISP that spam is a big concern of yours and that if a competing ISP offered Internet accounts with spam protection you would probably be interested in switching. Can it protect my children? Question: Does MailShield help protect children from inappropriate online content? By default, MailShield does not enforce any sort of content based filtering. We do not feel it is our job to decide what you think is appropriate content. However, MailShield offers you a wide variety of filtering capabilities so that you can put your own preferences in as to what is appropriate or not, and have MailShield automatically act on your preferences. Is this the end of spam? Question: If everyone ran MailShield, would spam stop? Or would spammers find another way to get junk mail distributed? If everyone ran MailShield certain kinds of spam would definitely stop. For example, spam that forges the author's email address so that you cannot reply would become a thing of the past. However, the nature of the beast is that spammers continually refine their techniques to make their email look more and more like legitimate email. Some spam will always make it through, no matter what the filter, unless you take the radical step of only accepting email from people or sites that you have approved. We find that most people who send spam are not very sophisticated and leave all sorts of markers in their junk mail, which make it fairly straightforward to identify their mail. The spammers who are extremely sophisticated, and are always changing their methods, will inevitably find ways around whatever MailShield is doing at that moment, and we will constantly be improving MailShield to fight the spammers' latest innovation. But, if MailShield is able to remove 95% of the spam that you receive, we feel that it is worthwhile. Further, if spammers were forced to use legitimate return addresses so that users could effectively complain, spammers would almost certainly reduce the amount of spam they sent in the first place. Another major reason that spam exists today is that spammers can use other peoples' mail servers as unauthorized mail relay hosts to send their mail out. In this way the spammers do not need to invest in the computer equipment and bandwidth needed to deliver vast quantities of email, and can instead piggyback on other people's resources. If every mail server was secured with MailShield, spammers would have to send mail directly from their own mail servers -- a prospect which would Frequently Asked Questions 85 significantly increase the cost of sending spam, making it less attractive for spammers in the first place. If this were the case, we think you would receive much less spam because it would be significantly more costly to send it out. Furthermore, if spammers had to send email directly from their machines, they would have to get a fixed TCP/IP address. After you received one piece of spam from them you could put their TCP/IP address on your ban list and you would never receive spam from them again. It is the mail relaying security hole that makes blocking spam so difficult, because the servers that are sending spam are otherwise used to send legitimate email that you don't want to reject. Thus, you need a sophisticated tool such as MailShield to tell the difference. Can Spammers Bypass MailShield? Question: What keeps spammers from downloading MailShield and, by seeing how it works, bypassing its protections? I see that MailShield takes over the regular mail port; won't spammers just find where the actual mail server is and connect directly to it instead? They can try, but they won't likely succeed. First, the administrators can move the mail server to any port they wish; there's no requirement that it be on any particular port. Second, a higher-security solution is to move the actual mail server to a different TCP/IP address, so the spammer would have to find that address and the right port at that address. On a site that needs the most security, a third solution will permanently fix the problem: you can put your mail server on an internal network, and MailShield outside your network, by using a firewall and allowing only the MailShield machine talk to your mail server. If they're both together on one machine, you can configure your firewall to disallow outside connections directly to your mail server. An additional method is to use a TCP/IP address which is reserved for internal networks for your mail server using any number of addresses that are legal on an internal network, but which do not work over the Internet. What about Legislation? Question: Some say that the government shouldn't try to stop spam, that the solution to it should be technological. Will MailShield make anti-spam legislation unnecessary? Anti-spam legislation will make MailShield's job easier by lowering the quantity of spam that MailShield receives. Also, some of the proposed legislation requires bulk mail companies to tag their email as advertising. If they do this, this will make MailShield's job much easier. However, the Internet is a global community and we expect that the problem of spam will be with us for a long time. Even if the U.S. passes legislation to ban spam, other countries may not, and the spam can originate from there. Frequently Asked Questions 86 How can I buy MailShield? Question: I want to buy MailShield. What do I do next? Go to http://www.lyris.com/products/mailshield/ for information about pricing and ordering. Answers for Power Users About Regular Expressions MailShield allows regular expressions to be used to specify text patterns. Regular expressions are very powerful, but they are also very difficult to learn. By default, they are disabled in MailShield, but can be easily enabled for power users. We recommend that anyone who wants to learn the power of regular expressions purchase the excellent book "Mastering Regular Expressions", published by O'Reilly and Associates (www.ora.com). If you would like to try free documentation, we have made the documentation to GNU regular expressions available on our ftp site, at ftp://ftp.mailshield.com/extra/regex.txt. Most any book on Perl will also discuss regular expressions. By default, all the MailShield rules are set to support simple text matches, such as specifying the word "advertisement" matches in the sentence "this is an advertisement". Regular expressions, thus, are not enabled by default. We did this because most users are confused by regular express syntax, and because regular expression searching is not as fast as simple text matching. To enable regular expressions in your rules, you need to edit the rule files to support regular expressions where you want them. This is not a difficult process, but it needs to be done by hand. For example, in "data.mml", you will find many text-matching rules. The rule for banned header text looks like this: if (index(@banned_header, lc($Header)) > -1) You can change this rule to support regular expressions by changing the line that starts with "if" (the first line of the rule) from using the "index" command (which does a simple text match) to instead use the "=~" regular expression match. For example, to support a case-insensitive regular expression match, you would change this line to instead say: if (lc($Header) =~ @banned_header) Note: The $Header variable is surrounded by the lc() command, which converts the header into lower case. That way, the regular expression matches against all lower case text, so that the regular expression can be case insensitive. If you want your match to be case sensitive, you would not use the lc(), and your "if" statement would look like this: if ($Header =~ @banned_header) You can perform this transformation on any text-matching rule in the MailShield rule files, so that you can use regular expressions wherever you like. Another example: To change the match of banned body text to use regular expressions, you would locate the line that says this: Frequently Asked Questions 87 if (index(@banned_body, lc($Body)) > -1) And change it to say this: if (lc($Body) =~ @banned_body) Or if you wanted a case-sensitive regular expression match, you would replace it with this: if ($Body =~ @banned_body) That's it! Blocking Email Attachments > Can MailShield be used to prevent Executable > attachments from being accepted by our mail server? Yes, you can put filters in place that reject all sorts of different attachments, depending on your need. You would place the rejections into the "bantext.txt" file, which bans text in the message. To refuse program attachments, you would enter: Content-Type: application To get rid of general-purpose attachments, you would enter: X-MS-Attachment: Content-Disposition: attachment; To get rid of binary signature files, you would enter: Content-Type: text/x-vcard; Content-Description: S/MIME Cryptographic Signature If you do not want to receive multi-part MIME messages, you would enter: Content-type: multipart If you do not want to receive HTML formatted email, you would enter: Content-Type: text/html; charset="us-ascii" If you do not want to receive enriched MIME messages, you would enter: Content-Type: text/enriched; Save All Mail in Text Files How do I configure MailShield to make an extra text file copy of all the email it receives? If you want MailShield to save, in a text file, a copy of every email message it receives, you can do this with a simple addition to the "data.mml" rule file. This feature might be useful as a failsafe backup for all your mail. Here are two different ways to go about it. If you want the messages to be archived according to the recipient name, with all email To: that recipient going into the same file, you would add this rule at the very top of data.mml: &AppendFile('/opt/shield/mail/'.$SmtpRcptTo, $SmtpData."\n\n"); Frequently Asked Questions 88 This appends the complete message text ($SmtpData) to a file named after the recipient of the message ($SmtpRcptTo), in a directory named "/opt/shield/mail/". That example was for Unix. For Windows, you would change the direction of the slashes, like so: &AppendFile('c:\shield\mail\'.$SmtpRcptTo, $SmtpData."\n\n"); In both cases, you would have to create a "mail" directory in your MailShield directory. The other method is to save every email message as a separate text file, each with a unique name. You might want to make it easier to find the email messages by recipient, so perhaps you build the filename using the recipient name. Thus, your rule would look like this: $filename = '/opt/shield/mail/'.$SmtpRcptTo."- ".&RandomString(8).".txt"; &CreateFile($filename, $SmtpData); This rule creates a file name that starts with the recipient name, follows it with a dash, and finished with an 8 character random string, to ensure that the filename is unique. The message text is then saved to that file. The above example was for Unix. For Windows, you would change the direction of the slashes, like so: $filename = 'c:\shield\mail\'.$SmtpRcptTo."- ".&RandomString(8).".txt"; &CreateFile($filename, $SmtpData); In both cases, you would have to create a "mail" directory in your MailShield directory. Virtual Domains Question: How does MailShield handle multiple "virtual mail domains" on a single physical server such as MailSite. For example, where each email domain has its own unique IP address, own mail server name in its own domain, and can have multiple instances of the same user name e.g., "sales" etc. across all of the domains? As you know with MailSite (and NTmail and others) you bind a unique IP address to each individual email domain, so each domain is essentially, and appears as a fully autonomous mail server. If MailShield receives the email for ALL of these virtual email domains first before sorting and forwarding the filtered mail to each relevant domain - how does it deal with this situation? How you do this with MailShield depends on how your Mail Server handles virtual domains. Does your mail server support virtual domains on a single TCP/IP address? For example, if I write to: bob@acme.com and bob@widget.com, can your mail server tell the difference, if they both MX to the same mail server, or do they have to go to different TCP/IP addresses? Frequently Asked Questions 89 If your mail server can handle this, i.e., virtual mail domains on one TCP/IP address, then there's no problem. You do not have to do anything special in this case. Just have MailShield listen to the TCP/IP addresses for all the virtual domains, and specify one TCP/IP address/port combination in smtpserv.txt as the place where MailShield should send all mail. This is how Sendmail works. If your mail server cannot handle multiple virtual domains on one tcp/ip address, and requires each virtual domain to be on its own TCP/IP address, then there are three solutions (listed from worst to best): 1) You can run multiple copies of MailShield, one for each domain, each forwarding to a separate MailSite tcp/ip address (not so good, but it works). You do this by setting the "bind.txt" file to one TCP/IP address, and "smtpserv.txt" to the appropriate SMTP server destination. 2) If you want MailShield to implement virtual mail servers, but only use one TCP/IP address, you can add rules to rcptto.mml which tell MailShield where to route mail based on the recipient's domain name. Rules would look like this: if ($SmtpRcptTo =~ /acme.com/) { $smtp_server = "207.90.155.2 26"; }; if ($SmtpRcptTo =~ /widget.com/) { $smtp_server = "207.90.155.3 26"; }; etc.. 3) Finally, you can have MailShield use any number of TCP/IP addresses, and route mail to your mail server based on the TCP/IP address that the mail was sent to. This is probably the most foolproof method. To implement this, you would edit begin.mml, and place rules like this at the top: if ($MyTcpip eq "207.91.155.2") { $smtp_server = "207.91.155.2 26";}; if ($MyTcpip eq "207.91.155.3") { $smtp_server = "207.91.155.3 26";}; etc... Because these final two solutions are a common need, we will be adding a feature to MailShield to implement these as simple configuration files, without needing to add rules. 4) Another way to do the same thing as above (route mail according to TCP/IP address) is possible if your SMTP server is on the same machine as MailShield, but running on a different port. In that case, a single rule will tell MailShield that the correct destination SMTP server is the same TCP/IP address currently being used, but on a different port, and you will not have to add a rule for each TCP/IP address. For example, if your mail server is listening to port 26, you can simply put this one rule in: $smtp_server = $MyTcpip." 26"; MailShield will know that the destination mail server is on port 26, using the same TCP/IP address currently being used for this connection. Frequently Asked Questions 90 User-specific Settings With the current version of MailShield, the settings that you specify apply to every user on your system. However, you can add user-specific settings yourself, in the current version of MailShield, by editing the MailShield rule files to support this. This FAQ item explains how add user-specific rules. You can then create your own interface for users to edit their settings. This example will show how to create a user-specific "banned text" feature. If you look at data.mml, you will find the following rule for banned text: if (index(@banned_body, lc($Body)) > -1) { $smtp_message = "550 Mail refused"; $log_message = "550 Mail refused because banned text appeared in body text: '".$match."'"; &DefaultRejection; }; What we want to do is create a rule just like this, but which takes the text to ban out of a file specifically for each user. To do this, we want to read from a text file, which will be named after the recipient's email address. So, for example, if the recipient is bob@shelby.com, the text file with the banned text will be "c:\banned\bob@shelby.com". So, above the rule just quoted, we make a little space to add our new rule by typing a few carriage returns, and we enter these lines of code: $ban_file = 'c:\banned\'.$SmtpRecip; @ban_text = &FileToArray($banned_text); Now, we simply need to rewrite the existing banned text rule to instead use the user- specific banned text. To do this, we copy the rule that we quoted above (copying, rather than replacing, because we want to leave the existing rule intact), and we change the word @banned_body to be @ban_text, like so: if (index(@ban_text, lc($Body)) > -1) { $smtp_message = "550 Mail refused"; $log_message = "550 Mail refused because banned text appeared in body text: '".$match."'"; &DefaultRejection; }; That's it! Now, if a user wants to ban text from appearing in the messages they receive, they put a file with their email address in the C:\banned directory. You will probably want to write a script which copies their ban lists from your user's directories into this directory, or perhaps have a web interface for editing these files. Troubleshooting Test Messages not being refused I send test messages to MailShield that should be refused; instead they're being accepted. Why? Frequently Asked Questions 91 If you are trying to test MailShield, and find that you cannot get MailShield to refuse any of your messages, it is likely that you have set yourself as a "TCP/IP address approved for relaying". Thus, MailShield is going to approve you for sending, no matter what the text is that you're sending. The reason for this is, MailShield is meant to block unwanted email from outsiders. If your TCP/IP address has been approved as an "insider", then MailShield shouldn't check your mail to see if it is unwanted it knows the mail is fine, because you're the one writing it. MailShield should let you write anything you want. So, if you want to test MailShield, as if you were an outsider, perhaps to see how the MailShield rules work, you have two options: * Do not set yourself up as a host approved for relaying. See the "TCP/IP addresses allowed to relay" or "Hostnames allowed to relay" features. This way, all mail you send will be seen as from an outsider, and thus subject to MailShield testing. Once your testing has concluded, you will probably want to undo this, so that your mail is not subject to these tests. * Or, get a free email account at HotMail or Yahoo, or some other service, and use them to send mail. Usually, these free email services send mail almost instantly, so it is can be easy to use them for MailShield testing. DNS Problems If, when starting MailShield, you receive an error message about invalid host, or that MailShield is unable to connect to your DNS and SMTP server (and you know they are there) then the problem is likely with your TCP/IP machine name configuration. This problem is usually caused by an incomplete DNS configuration. In order for MailShield to work, the TCP/IP hostname on your machine must exist on your DNS server, and the TCP/IP addresses that your machine uses must themselves have names. In technical-lingo, this means that you need both "forward and reverse DNS lookups" installed on your system. Check the hostname/domain name that you have set in your TCP/IP configuration. Make sure that you can ping this full name, both from your machine, and from another machine. You must have a DNS entry for your machine on your DNS server. This hostname/domain-name setup is usually the cause of your problem. If you have multiple TCP/IP addresses, make sure that the first TCP/IP address on your system has a DNS name entry. With the program "nslookup.exe" (nslookup on UNIX), you can check to see if DNS entries are set up correctly. If you do not have "nslookup.exe" on your computer, you can download it from: ftp://ftp.lyris.com/listmanager/scripts/nslookup.exe If your computer is named "fia.shelby.com", you would type: nslookup fia.shelby.com and nslookup will respond with: C:\>nslookup fia.shelby.com <- this is what you type Server: kuno.shelby.com <- this is your DNS server Address: 207.105.6.156 <- this is your DNS server Name: fia.shelby.com <- this is your host name Address: 207.105.6.147 <- your tcp/ip address If your DNS is not set up correctly, this forward lookup will say: Frequently Asked Questions 92 *** kuno.shelby.com can't find fia.shelby.com: Non- existent host/domain If it did work and you did not get an error message, now do a "reverse lookup" by typing the TCP/IP address of your machine. For example, if the TCP/IP address of your machine is "207.105.6.147", you would type: C:\>nslookup 207.105.6.147 <- this is what you type Server: kuno.shelby.com <- this is your DNS server Address: 207.105.6.156 <- this is your DNS server Name: fia.shelby.com <- your host name Address: 207.105.6.147 <- your tcp/ip address If your DNS is not set up correctly, the reverse lookup will say: *** kuno.shelby.com can't find 207.105.6.147: Non- existent host/domain If you do have a DNS problem, you should contact the person responsible for your DNS. In most cases, this is your ISP. Once this is fixed, MailShield will work correctly for you. Error: Unable to listen If, when starting MailShield, you see an error like this: Tcp_Connection_Receiver::DoTcpRecv 2 exception: system_call_failure: ::bind ( 4, // descriptor() 0xef20baf0, // (sockaddr*) address 16 // size ) [socket.cpp:163] Error: unable to listen to TCP/IP address: 127.0.0.1 It means that you have some other program conflicting with MailShield, preventing MailShield from listening to the TCP/IP address it has been told to listen to. If are running a mail server on the same machine as MailShield, you will need to configure MailShield and your mail server to coexist. See . The MailShield Language 93 The MailShield Language What is it? What is the MailShield Language? The MailShield language tells MailShield what to do with email it receives. When MailShield receives a connection request, from someone wanting to send email to you, MailShield runs a script to determine what to do next: whether to continue processing, stop processing and just accept the message, or whether to hang up on the person and abort the message. This script is written in the MailShield language, and this is where rules are set for what constitutes acceptable email and what does not. After each step of the email connection, MailShield can run a script to determine what to do next. When MailShield first starts, it reads the file named "config.mml", and stores the results of that script in memory. Every script, which runs thereafter, inherits the results of that script. This makes the individual scripts run much faster, especially if the bulk of the processing (such as defining a "ban list") happens in "config.mml". The "config.mml" file also defines various operational settings, such as the tcp/ip addresses to use the location of your mail server. It also defines what scripts will be run at what point by MailShield. The scripts are kept in memory, to further increase performance. If a syntax error appears in a script, MailShield immediately aborts the script, displays and error message on the screen (and/or the log) and accepts the email. MailShield does this so a syntax error in your script does not cause you to lose email. Complete documentation about every command in the MailShield Language is available MailShield Language Reference. MailShield Rule Scripts The main configuration, config.mml is located in your MailShield directory, in a subdirectory named "rules". This file defines the basic settings for your MailShield configuration. It is automatically loaded when MailShield starts up. In addition, there are several other files, which that define the rules that MailShield applies to incoming email. These rules are provided "ready to use" for you; you do not need to edit any of these files. However, if you feel comfortable looking at simple scripts and programs, you might want to look at how the MailShield rules work. You can change the rule files to The MailShield Language 94 completely suit your needs. Feel free to remove tests that you do not want, and to add tests that you do not see. If you write a test which you feel is useful, please let us know about it, by joining the MailShield discussion list, http://www.lyris.com/mailinglists.html, and post your ideas there. We'll share your work with other MailShield users, by posting your script on our web site, in a section for user-contributed scripts. Also see The MailShield Language. Note: If you are not familiar with how the SMTP email protocol works, we recommend that you read the Internet standards documents on the topic: RFC821 and RFC822. The script files are: begin.mml Connection begins: run when a connection request comes in from the outside, asking for an SMTP connection. Simple rules, such as refusing certain TCP/IP addresses, and the RBL, can be used at this point. The $PeerHostname, $PeerTcpip, $MyHostname, and $MyTcpip variables are defined at this point. helo.mml After HELO: run after the first command from the other end is performed, which is always a "HELO XXXX" command. The only additional piece of information at this point is the value of the string in the HELO message. The $SmtpHelo variable is defined at this point. mailfrom.mml After MAIL FROM: run after the MAIL FROM command is given, which identifies the SMTP sender of this message. The $SmtpMailFrom is defined at this point. Rules that refuse mail from specific users can be performed at this point. rcptto.mml After RCPT TO: run after every RCPT TO command is given. A RCPT TO command defines the actual recipient of this email message. If multiple RCPT TO commands are given (indicating multiple recipients), this script is run multiple times, immediately after each RCPT TO command. The $SmtpRcptTo variable is defined with the most recent SMTP TO value, and the @SmtpRcptTo variable contains all the recipients. At this point, you can determine if the sender is using you as a relay host, and block if that is not allowed. Also, you can block if the number of recipients is too large, or if "trigger accounts" are mentioned in the mailings. "Trigger accounts" are email accounts that should never receive real mail, but only would receive mail if they had been illicitly collected by bulk-mailers. data.mml After DATA: run after the message text has been given to MailShield. The @Data, $Body and $Header variables are defined, and the various &HeaderXXX operations can now be performed to check and modify the headers. This is where the majority of the checking can take place. Also, the message can be modified or re-written as desired. Some people prefer to do all their checking at this stage, and have no scripts for the other steps. standard.mml Commonly used subroutines: this file contains functions that are used in various other places in MailShield. For example, the default rejection procedure is defined here. So, if you want to change how all the rejections work, you can simply change the code in the DefaultRejection subroutine. user.mml This script is run just before data.mml is run, and is a handy place to put your own rules. By default, this file contains no rules of its own: it is simply a placeholder for The MailShield Language 95 you to put your own rules in. By separating your rules in this file, and not putting your changes directly into the other .mml files, you make it easy to upgrade to newer versions of MailShield. Otherwise, if you do make changes to the other .mml files, when you upgrade MailShield, you will need to decide whether you want to keep using your scripts, and thus not benefit from features in the new version, or whether you want to reapply your changes to the new version. By keeping your changes in user.mml, you make upgrading simple. Common to all scripts: If the &Accept command is given, no further scripts are run, and the message is immediately accepted. MailShield attempts to relay the message to your mail server. If the mail server responds, the final message given by your mail server is displayed to the sender. If the mail server does not respond (for example, if it is down), MailShield will display the message "450 relay attempt failed, message was not delivered; reason: " along with a descriptive reason for the failure (such as "tcp/ip address 202.34.12.1 did not answer") If the &Hangup command is given, the SMTP connection is immediately terminated. If a message has been defined with &Message("xxx"), this message is displayed, otherwise the default message is displayed. Mail Information Variables These variables are set by MailShield, and are automatically available to your MailShield scripts. Note, however, that not all these variables are yet set at every stage of the SMTP session: some require a certain SMTP step to occur in order to be set. $PeerHostname- the Internet hostname of the host connected to us. $PeerTcpip - the TCP/IP address of the host connected to us. $MyHostname- the Internet hostname address of this machine. $MyTcpip - the TCP/IP address of this machine. $SmtpHelo - the value passed to you by the SMTP "HELO" command. $SmtpMailFrom - the value passed to you by the SMTP "MAIL FROM" command. $SmtpRcptTo - the value passed to you by the most recent SMTP "RCPT TO" command. @SmtpRcptTo - all the values so far passed to you by the SMTP "RCPT TO" command. @Data - the value passed to you by the SMTP "DATA" command (this is the message header and body), with each line of the message as an array element. This is what is actually sent. &CommitData must be called after any changes to this variable. $Header - the header text portion of the current message. &CommitHeaderBody must be called after any changes to this variable. $state - the run context of the current script. For example, if this script is being run after the DATA command, the value of $state is "DATA". The possible values for $state are "BEGIN", "HELO", "MAIL FROM", "RCPT TO", and "DATA". $match - after a text search command is given, this variable contains the text which matched the search. This is useful when displaying a refusal message, so you can The MailShield Language 96 tell the user exactly what text was matched. This variable applies to all versions of the index() command, as well as all versions of regular expressions (commands which use =~ ). $smtp_server - contains the TCP/IP address and port number of the SMTP server to deliver this email message to. This value is defined in the configuration, but you can redefine it for any single message, thus causing the message to be routed to that SMTP server. If you change the value of this variable, the change only applies to the current email message. Common Mistakes Here is a list of common mistakes made in editing the MailShield scripts. Forgetting the ending semicolon. Every line must end with a semicolon. This includes sub {}; declarations as well as the if() {}; statements. Using a Perl language feature in a MailShield Script The MailShield language is not as powerful as Perl. Commands such as for () and while () do not exist in MailShield. If you are unsure of what you can do, consult the MailShield language reference. If it isn't specifically allowed, chances are it will not work. Configuration Doesn't Seem to Reload If you reload the MailShield configuration while the server is running (with the auto- reload feature, or with "ctrl-break" on Windows or on Unix: "kill -1 `cat /etc/shield.pid`"), the new settings apply to all SMTP sessions from that point on. SMTP sessions that were connected before the configuration was reloaded will continue to have the old settings. So, if you are debugging your script, and reload the configuration, you will want to quit your SMTP connection, and reconnect to test whatever changes you have made. Tip: use Perl to find your errors Everything that is valid in the MailShield language is also valid in Perl. Thus, a syntactically correct MailShield script should also be a syntactically correct Perl script. Thus, if you are having trouble finding the cause of a syntax error in a MailShield script, you can enlist Perl's help, by using Perl to check your syntax. For example, if you are checking the script named "begin.mml", you can do a basic validity check with the command "perl -c begin.mml", and a more extensive check with "perl -w -c begin.mml". Perl is often very good at giving you hints about common syntax errors. Tip: use debug mode You can start MailShield in the foreground with debug mode on, in order to see exactly what MailShield is doing. In order to run MailShield in this mode, you specify the "debug" option on the command line, as in "shield start debug". You can also dynamically toggle debug mode on or off if MailShield is running in the foreground with the "shield start" command. On Windows, you do this by press ctrl- break. On Unix, you can send SIGUSR1 to the MailShield process, with the command "kill -USR1 `cat /etc/shield.pid`" Limitations This is a list of known limitations in the MailShield language: The MailShield Language 97 * Due to a limitation in the parser, you cannot have a backslash as the final character in a string declaration. For example, $a = "c:\"; will cause a syntax error. Instead, use single quotes for this string, as in $a = 'c:\'; or use concatenation $a = "c:".'\'; * You may nest bracketed statements (such as if()) up to 12 levels deep. If you go deeper than this, you will get a syntax error. * Many alternate syntaxes which are valid in Perl are not valid in the MailShield language, while everything that is valid in the MailShield language is valid in Perl. For example, to call a user-defined subroutine in the MailShield language, you use a command such as &subroutine; -- you cannot include empty parentheses around the call (&subroutine() is not valid). So, if you experience syntax errors that you do not understand, be sure to look up the MailShield language reference for the proper form. Perl is an incredibly flexible language, with many alternative syntaxes, while the MailShield language is a vastly simplified form of Perl, with a very strict syntax. MailShield Language Reference What follows is a reference to every built in command of the MailShield language. Accept The MailShield "&Accept" command tells MailShield to stop processing the current rule script and accept all messages from the current SMTP session. This command tells MailShield that no more scripts should be run on the current SMTP session, thus the current SMTP session is not restricted by MailShield. This command is useful when a host has connected to you, and you are certain that they are a "trustworthy" host, and thus that there is no reason to have MailShield check anything they do. Calling the "accept" command will significantly speed up that SMTP session, since MailShield will have much less work to do. For example: &Accept; Add - + The addition operator, which is the plus sign "+" can be used anywhere a string or number is used. Note: You must have a space between the + sign and the text it is operating on. Thus, "$a = 2+2"; is not valid because there are no spaces around the +, while "$a = 2 + 2"; is valid. For example: $a = 2 + 2; $a = "2" + "2"; And - && The MailShield command "&&" will take two logical values, and perform a logical AND comparison between them. For example: The MailShield Language 98 if (($a == TRUE) && ($b == TRUE)) { print " both $a and $b are true. "; }; AppendFile The MailShield command "&AppendFile" takes a filename and a string as its parameters, and writes the given string out to the filename. If a file already exists with that filename, the text is appended to the existing file. Note: MailShield uses a fast internal locking mechanism to prevent two AppendFile() commands from running at the same instant, because this would result in a corrupted text file. The CreateFile() command is protected by this same mechanism. For example: &CreateFile("test.txt", "this is a line of text "); &AppendFile("test.txt", "this is another line"); Array2String The MailShield "&Array2String" command will convert an array into a string. Each value in the array will be prefixed with a ~~V while the end of the array will be suffixed with a ~~E. For example: $variable = &Array2String(@array); Array assignment To assign a value to an array, you should either use the push command, or use the "FileToArray" command. You can also assign values to specific array elements by specifying the array element number in square brackets. MailShield does not support the Perl method of array assignment, which uses parentheses in a list to assign multiple values to an array. For example: push (@array, "one value"); push (@array, "another value"); @array = &FileToArray('text.txt'); $array[0] = "text"; $array[1] = "more text"; $array[2] = "yet more text"; Array Size Count You can also obtain the count of the number of items in an array by assigning an array to a scalar variable. For example, if the array named "@array" has three items in it, then the command "$variable = @array" will assign the value of three to the variable named $variable. You can also use the keyword "scalar" to the same effect. For example, "$variable = The MailShield Language 99 scalar (@array);" We recommend that you use the keyword "scalar", so as to make your rules easier to read. Array reference You can reference a single string inside an array by specifying the number of the reference that you want to extract in square brackets. For example, to extract the second item from an array, you could use this command: $second_item = $array[1]; Note: The numbering of items inside an array begins at zero. Associative array assignment To assign a value to an associative array, you put the key value in curly brackets and the value field on the right hand side as a string. For example, the command "$variable {"key value"} = "value text";" will create a single key/value pair with the key equal to "key value" and the value equal to "value text". If a key with that value already exists, then the value field for that key is replaced with the given value. For example: $variable {"bob"} = "user 1 "; Associative Array reference You can reference to single string inside an associative array by specifying the key value of the associate array element that you want to extract, in the curly brackets. For example, to extract the value in an associative array, that is associated with the key value "bob"; you would use this command: $bob = $assoc{"bob"}; Assoc2String The MailShield "&Assoc2String" command will convert an associative array into a string. The associative array will be converted into a string with specific delimiters identifying each key and each value in the associative array. Each key will be prefixed with a ~~K, while each value will be prefixed with a ~~V. The end of the array will be identified with a ~~E. For example: $variable = &Assoc2String(%assoc); BodyPrepend The &BodyPrepend("text") command inserts a line at the top of the message body, into the @Data variable. The MailShield Language 100 chdir The chdir command tells MailShield to use the string passed to it to set the current working directory. This is the same command as in Perl. For example: chdir("/usr/local/bin") chdir("\shield"); Chop The MailShield chop command will remove the last character off a string or off all elements of an array. This is the same command as in Perl. For example: $variable = chop ("tests"); chop (@array); Chr The MailShield command "chr" takes a single numeric parameter, and returns a single string character, which is the ASCII character, specified in the number. For example: $return = chr(13); CommitData The MailShield command "&CommitData" must be called in order for any changes that were made to the @Data variable be applied to the email message that will be relayed. If you do not call this command, any changes that you made to the @Data variable will be lost and will not be seen in the relayed email message. The @Data variable holds all the individual lines (including the header and body text) of the current email message. For example: &CommitData; CommitHeaderBody The MailShield command "&CommitHeaderBody" must be called in order for any changes that were made to the $header or $body variables be applied to the email message that will be relayed. If you do not call this command, any changes that you made to the $body or $header variables will be lost and will not be seen in the relayed email message. The $header variable contains, as a single string, the entire contents of the current email message header. The $body variable contains, as a single string, the entire contents of the body text of the current email message. The MailShield Language 101 For example: &CommitHeaderBody CommitHeaders The MailShield command "&CommitHeaders" must be called in order for any changes that were made to the header to be applied to the email message that will be relayed. If you do not call this command, the changes made to the header will not be applied and will not be seen in the relayed email message. This includes commands such as HeaderAppend, HeaderSet, and HeaderDeleteKey. For example: &CommitHeaders; CommitSmtpData The MailShield command "&CommitSmtpData" must be called in order for any changes that were made to the $SmtpData variable be applied to the email message that will be relayed. If you do not call this command, any changes that you made to the $SmtpData variable will be lost and will not be seen in the relayed email message. The $SmtpData variable holds all the individual lines (including the header and body text) of the current email message. For example: &CommitSmtpData; Continue The MailShield "&Continue" command tells MailShield to stop processing the current script, and continue with the SMTP session. This command is equivalent to the "exit" command. This command does not prevent any further are scripts from running it only affects the currently running script. For example: &Continue; CountOccurence The &CountOccurence command returns a number indicating how many times a given substring occurs in a given string. For example: $number = &CountOccurence("Hot SEX SEX SEX for you!", "SEX"); CountRecipients The MailShield "&CountRecipients" command is used to determine how many individual recipients have been specified in the message text itself. The MailShield Language 102 MailShield will count the number of recipients that are defined in the TO, CC: and BCC: headers. This command returns a number. This command is useful because it is often inappropriate to address a single message to too many recipients. Some commercial email messages will contain dozens and sometimes hundreds of recipients in the message text, and this function can be used to determine this and act accordingly. For example: $a = &CountRecipients; CreateFile The MailShield command "&CreateFile" takes a filename and a string as its parameters, and writes the given string out as the contents of the filename. If a file already exists with that filename, the new file overwrites the file. Note: MailShield uses a fast internal locking mechanism to prevent two CreateFile() commands from running at the same instant, because this could result in a corrupted text file. The AppendFile() command is protected by this same mechanism. For example: &CreateFile("test.txt", "this is a line of text"); DisableLogType The MailShield command "&DisableLogType" will disable logging of the specified type. The valid log types are: log_config log_database log_major log_nntp log_program_list log_program_output log_program_parse log_refuse log_script_log log_smtp log_urgent For example: &DisableLogType("log_smtp"); The MailShield Language 103 DisplayAssoc The MailShield "&DisplayAssoc" command will display an associative array to the screen. Each key/value pair will be displayed on a separate line on the screen, with the key separated from the value by a single colon. For example: &DisplayAssoc(%assoc); DisplayArray The MailShield "&DisplayArray" command will display an array to the screen. Each value in the array will be displayed on a separate line on the screen. For example: &DisplayArray(@array); DNSALookup The DNSALookup() function takes a host name, and returns an array of TCP/IP addresses for that host. This is known as an "A Record" lookup. The syntax for this command is: @array = &DNSALookup($string); For example: @ip_addresses = &DNSALookup ("www.lyris.com"); DNSCnameLookup The DNSCnameLookup() function takes a host name, and returns its canonical name, if a Cname exists for that host. This is known as a "CNAME Record" lookup. The syntax for this command is: $string = &DNSCNameLookup($string); For example: $real_name = &DNSCnameLookup ("www.lists.lyris.net"); DNSMXLookup The DNSMXLookup() function takes a host name, and returns an array of all the TCP/IP addresses of all the MX (mail exchange) records for that host name. This function useful in determining whether or not a given host name can accept email or not, and thus can be used in various filters. This function performs the full range of DNS functions needed to determine what hosts to connect to in order to send email: MX lookups, A lookups and CNAME lookups, are all performed automatically as part of this function. The syntax for this command is: @array = &DNSMXLookup($string); For example: @mail_servers = &DNSMXLookup ("lyris.com"); DNSRBLLookup The DNSRBLLookup() function takes a TCP/IP address, and does an RBL-style DNS lookup on it, returning TRUE if the given TCP/IP address is on the RBL. The MailShield Language 104 There are a number of Internet ban lists that use the RBL-compatible technique to disseminate their information (such as ORBS and DUL), and this function is an easy way to support them. The syntax for this command is: $result = &DNSRBLLookup($string, $string); with the first parameter being the RBL host name to append, and the second parameter being the TCP/IP address to check. For example: $is_rbled = &DNSRBLLookup (".rbl.maps.vix.com", "207.90.12.4"); DNSRevLookup The DNSRevLookup() function takes a TCP/IP address, and returns the host name for it, by performing a DNS reverse lookup. The syntax for this command is: $result = &DNSRevLookup($string); with the parameter being the TCP/IP address to look up. For example: $hostname = &DNSRevLookup ("207.90.155.33"); Do The MailShield "do" command is used to run a string value as a MailShield program. For example: $variable = 'print "this is an example";'; do $variable; DomainFromEmail The MailShield command "&DomainFromEmail" is used to extract the domain name from the email address, which is given to it. This command is useful in order to determine if the domain name on a given email address is valid. For example, given a certain email address, you first need to determine what the domain name of that email address is, then you can lookup the TCP/IP address of that domain name to insure that the domain name is a real Internet domain name. It would extract "somewhere.com" from "bob@somewhere.com". For example: $domain = &DomainFromEmail("bob@somewhere.com"); EmailAddressValid The MailShield "&EmailAddressValid" command is used to determine whether a given email address appears to be valid or not. MailShield performs several tests on that email address to see if it appears invalid. For example, it separates the email address into a username and hostname and then looks up the hostname to see if it is a valid Internet hostname or not. The MailShield Language 105 Also, this command performs various syntax checks on the email address to make sure that the syntax is in keeping with Internet standards. This command returns TRUE if the email address is indeed valid. For example: if (&EmailAddressValid("bob@somewhere.com") == TRUE) { print " email address is valid."); EmailDomainValid The MailShield command "&EmailDomainValid" is used to determine whether the domain name in a given email address is a valid Internet host name. MailShield determines this by extracting the domain name from the email address and then using a DNS to lookup on the hostname to find any existing Internet entries for it. This command returns TRUE if the email address is indeed valid. For example: if (&EmailDomainValid("bob@somewhere.com")) { print "email domain is valid."); }; EnableLogType The MailShield command "&EnableLogType" will enable logging of the specified type. The valid log types are: log_config log_database log_major log_nntp log_program_list log_program_output log_program_parse log_refuse log_script_log log_smtp log_urgent For example: &EnableLogType("log_smtp"); eq The MailShield command "eq" will take two strings, and perform a string comparison between them, returning TRUE if the two strings are identical. The MailShield Language 106 Note: It is important to use this command rather than "==" when doing string comparisons, because the "==" operator performs a numeric comparison of two strings, while the "eq" command performs a character-wise comparison of the two strings. This is the same behavior as with Perl. For example: if ($a eq "bob") { print "$a is equal to Bob "; }; Exists The MailShield "exists" command is used to determine if a given key value exists in an associative array. If an item with that key value exists in the associative array that is specified, then the "exists" command returns a TRUE value. For example: $variable {"key value "} = "a string "; if (exists $variable {"key value"}) { print "found! "; }; Exit The MailShield exit command causes MailShield to stop running the current script. This is useful if, for example, your script has determined that the rules that follow do not apply to the current SMTP session. The scripts that are defined to run in later portions of the SMTP session will still be run, but the execution of the current script will stop immediately. For example: exit; Extract The &extract() command takes a regular express indicating some text to find, and extracts all occurrences of that expression from the given text, returning an array of all the matches. The syntax is this: @array = &extract(/regexp/, $string); For example: @array_helo = &extract(/from [^ ]*/, &HeaderGetAll("received")); This is example extracts all the text strings after the "from" text in the "Received:" headers of a message. ExtractEmailAddress The MailShield command "&ExtractEmailAddress" is used to extract the email address from a message From: header. It would extract "bob@somewhere.com" from "bob@somewhere.com (Bob Person)". The MailShield Language 107 For example: $domain = &ExtractEmailAddress('bob@somewhere.com (Bob Somebody)'); $domain = &ExtractEmailAddress('"Bob Somebody" <bob@somewhere.com>'); FileToArray The FileToArray command converts the text inside a given file into a MailShield array. Each line in the file is understood to be a single item in array. The exception is a line that begins with a #, which is understood as a comment line. The FileToArray command is used widely in the config.mml file, as a convenient way to store configuration information and text files. For example, a list of text strings that are not allowed to exist in the message text could be defined in a file and read into an array using this command. For example: @array = &FileToArray('test.txt'); FileToAssoc The FileToAssoc command converts the text inside a given file into a MailShield associative array. An associative array is a variable which uses a string as a key and which also has a string as a value. Key based lookups on an associative array are very fast, because MailShield indexes the contents of the associative array in memory, using the key values, in a fast "binary tree". The FileToAssoc command looks at each line in the text file as a separate key value pair. The key and the value should be separated by a colon, like this "key: value ". If there is no colon on the line, MailShield will assume that there is no value to be associated with this key, and will make a key with a blank value. A key with a blank value is often useful in a situation where you want to quickly test to see if a string exists. For example, if you had a list of email addresses that should never be mailed to, you could store these email addresses in a text file, convert the text file into an associative array with &fileToAssoc, and then use that associative array in your script tests to see if a given email address exists in the associative array. Because the associative array is very quick to perform key lookups, this kind of operation is extremely efficient. For example: %assoc = &FileToAssoc('test.txt'); Greater Than, Less Than The MailShield commands ">", ">=", "<", "<=" will take two strings or numbers, and perform a numeric comparison between them, returning true if the numeric comparison is true. For example: if ($a < 1) { print "$a is less than 1 "; }; The MailShield Language 108 if ($a <= 1) { print "$a is less than or equal to 1 "; }; if ($a > 1) { print "$a is greater than 1 "; }; if ($a >= 1) { print "$a is greater than or equal to 1 "; }; Hangup The MailShield "&Hangup" command immediately disconnects the current SMTP mail session, and displays the currently set rejection message (set with &Message) to the host which is currently connected. The email message that was currently being sent is erased from memory. This command is helpful if a host has connected to you, and you are certain that you do not wish to receive any email from them. For example: &Hangup; HeaderAppend The MailShield command "&HeaderAppend" will append a given key/value pair as a new header, added to the current email message header, even if a header with that key name already exists in the email header. This is similar to &HeaderSet, except that a new header line is always created with this command. The command "&CommitHeaders" must be called in order for changes made by this command to be applied to the current email message. For example: &HeaderAppend("X-FILTERED-BY", "MailShield"); HeaderDeleteKey The MailShield command "&HeaderDeleteKey" will remove any incidence of header lines with a given key from the current email message. For example, if you find the Received: header to be not useful, you could remove them from your email messages, by using the following command: For Example: &HeaderDeleteKey("received"); The command "&CommitHeaders" must be called in order for changes made by this command to be applied to the current email message. HeaderExists The MailShield command "&HeaderExists" returns a TRUE value if the header key that is passed to it exists as a header line in the current email message. For example, The MailShield Language 109 to test whether the current email message has a subject header, you could use the following command: For Example: if (&HeaderExists("subject")) { print "there is a subject"; }; Note: The string that is passed to this command is, by convention, given in lower case. However, this command is case insensitive, so there is no requirement that the key be passed in any particular case. HeaderGet The MailShield command "&HeaderGet" returns a string value for the header key in the current email message. For example, to obtain the subject line from the current email message you could use the following command: For Example: $subject = &HeaderGet("subject"); Some email headers can occur or several times. When this happens, the &HeaderGet command only returns the first incidence of the re-occurring header. To obtain every incidence of a header, you can use the &HeaderGetArray command, which takes an array name as one of its parameters, and puts its results into that array. Or, use the &HeaderGetAll command. For example, the Received: header is often several lines of text, so the following command could be used to extract all the lines: For Example: &HeaderGetArray("received", @received); The command "&CommitHeaders" must be called in order for changes made by this command to be applied to the current email message. HeaderGetAll The &HeaderGetAll command is identical to the &HeaderGet command, except that if there are multiple headers by the given key name, they are all returned. For Example: $subject = &HeaderGetAll("received"); HeaderMimeGetAllArray The HeaderMimeGetAllArray() function returns an array of strings, which are just the MIME headers in a message body. These are extracted by looking for the Content-Type: boundary separator and copying the MIME headers indicated. You can then use the result to perform further testing of just the MIME headers. For Example: @mime_lines = &HeaderMimeGetAllArray; The MailShield Language 110 HeaderSet The MailShield command "&HeaderSet" will set an existing key in the email headers to the value that you specify. If the header with that key does not currently exist in the email headers, a header with that key and value will be created in the email headers, and appended to the end of the header. The command "&CommitHeaders" must be called in order for changes made by this command to be applied to the current email message. For example: &HeaderSet("X-FILTERED-BY", "MailShield"); if The MailShield "if" statement is similar to the Perl "if" statement, with several limitations. In MailShield, The word "if" is followed by a logical statement in parentheses followed by a set of commands in curly brackets that should run if the "if" statement turns out to be true. The command syntax is "if (LOGICAL_VALUE) {COMMANDS};". This is essentially the same as Perl. There is one important syntactical difference between the MailShield "if" statement and the Perl "if" statement. Every MailShield command line must end in a semicolon, so the commands that follow the "if" statement must also be terminated with a semicolon. If you do not end your if statement a semicolon you will receive a syntax error from MailShield. Perl allows you to be "sloppy" and omit the ending semicolon on an if() command -- MailShield does not. The way the MailShield parser works is that the MailShield parser will not even evaluate the string inside the curly brackets unless the "if" statement is true. Furthermore, if there are any syntax errors in the commands inside the curly brackets, the syntax errors will not appear until the if statement is evaluated as true, and the placement of the syntax error that you will receive will be relative to be commands inside the curly brackets. For example, if MailShield says that the syntax error is on "line 2", this means that the second line of this training inside the commands of the if statement has a problem, not that the second line entire inside the entire script was wrong. This technique of if() evaluation is the same as how the Tcl programming language uses deferred evaluation for an "if" statement. The way that MailShield determines whether a test is true or false is by converting it into a number. The number 0 is evaluated as being false while any number beside zero is seen as being true. For example, if a variable named $test is equal to 1, then an "if" statement that read "if ($test)" would be the same thing as the test "if (TRUE)" as well as "if (1)". The built-in MailShield variables TRUE and FALSE evaluate to the numbers one and zero, respectively. The way that MailShield evaluates logical tests, which uses parentheses, is by evaluating from inside the nested parentheses outwards. Thus, you can specify several logical tests inside the logical test and you can use the && or || logical tests to group tests together. See the section on logical operators for more complete treatments of how these tests can be grouped together. But, you can basically rely on these tests operating as they do in C and Perl. The MailShield Language 111 The if then else command There is one another form of the "if then" statement in the MailShield macro language. You can specify a single "else" statement at the end of your "if then" clause. The commands inside the curly brackets after the "else" statement will be executed if the logical test in the "if" statement was false. The syntax for the "if then else" command is: "if (logical tests) {commands} else {commands};" There is no "elsif" command in MailShield. Only if() {}; and and if() {} else {}; are legal commands. Here are several examples: $a = 1; $b = 1; if ($a) { print "ok!"; }; if ($a == 1) { print "ok!"; }; if ($a eq "1") { print "ok!"; }; if ($a == TRUE) { print "ok!"; }; if ($a != 1) { print "ok!"; }; if ($1 ne "1") { print "ok!"; }; if (!$a) { print "ok!"; }; if ($a || $b) { print "ok!"; }; if (($a == 1) && ($b == 1)) { print "ok!"; }; if ($a) { print "ok!"; } else { print "no ok!"; }; Index Command The MailShield command "index" will try to find the specified substring inside another string. This is a very fast command, and is the recommended way to perform searches through email messages. However, if you need more power, you should use regular expressions instead of this command, as complex text searches can be very fast with regular expressions, faster than trying to piece together the code from simpler commands. The regindex command provides this functionality. The "index" command returns the position of the substring inside the string as its return value. If the substring is not found inside the string, the "index" command returns a value of -1. The syntax is: index (string, string); There are several forms to the "index" command. All the different forms take this basic approach: index(THING_TO_SEARCH_THROUGH, THING_TO_SEARCH_FOR); For example: The MailShield Language 112 if (index(" this is a sentence ", "is") > -1) { print "the word 'is' was found '; }; Another form of the index command takes an array of substrings, and returns the numeric position of the first substring, which matches in the string. This is a very fast way to search a single string (such as the body of a message) for a number of different strings. The syntax is: index(string, @array); For example: push ("is", @string); if (index("this is a sentence", @string) > -1) { print "the word 'is' was found '; }; Another form of the index command takes an array of strings to search through, and a single string to search for. The syntax is: index(@array, string); For example: push ("- this -", @string); push ("- is -", @string); push ("- a -", @string); push ("- sentence -", @string); if (index(@string, "is") > -1) { print "the word 'is' was found'; }; Another form of the index command takes both an array of substrings, and an array of strings to search, and returns the numeric position of the first string, which matches, in the first substring. This is a very fast operation. One use for this command is to search all the Received: headers, in a single fast operation. The syntax is: index(@array, @array); For example: push (@substring, "is"); push (@string, " this is a sentence"); if (index(@string, @substring) > -1) { print "the word 'is' was found '; }; IpInRange The MailShield command "&IpInRange" is used to test to see if a given TCP/IP address falls inside the range of two other TCP/IP addresses. The command takes three strings as parameters and returns a TRUE or FALSE value. The first parameter is the beginning of the TCP/IP range, the second parameter is the end of the TCP/IP range, and the last parameter is the TCP/IP The MailShield Language 113 address to test. If the TCP/IP address to test (the third parameter) falls within the given range, then this command returns a TRUE value. For example: if (&IpInRange("207.90.150.1", "207.90.150.255", "207.90.150.15") == TRUE) { print "in range"; }; if (&IpInRange("207.90.150.1", "207.90.150.255", $PeerTcpip)) { print "in range"; }; You can also use a related command, "&IpInArrayRange" to test to see if a given TCP/IP address falls inside a range, except that this command allows you to test multiple ranges in one test. When using this command, you specify IP address ranges as strings in an array, with each range being specified as one TCP/IP address followed by another TCP/IP address, with each TCP/IP address separated with a dash. An example of one such range is 207.90.155.0-207.90.155.20. If a single TCP/IP address is specified instead of a range, then the test is a simple equality test to see if the given TCP/IP address is equal to the TCP/IP address being tested. For example: push(@range, "207.90.155.0-207.90.155.20"); push(@range, "207.90.155.50-207.90.155.70"); push(@range, "207.90.155.99"); if (&IpInArrayRange(@range, "207.90.150.15")) { print "in range"; }; IsIpAddress The "&IsIpAddress" command determines whether the string passed to it appears to be a valid TCP/IP address or not. This is only a syntax check, looking for a string with 4 parts (separated by a period), with each part being a number from 0 to 255. For example: $is_it = &IsIpAddress("207.01.300.500"); IsOnRbl The MailShield command "&IsOnRbl" takes a TCP/IP address as its parameter, and returns a TRUE or FALSE value to indicate whether the given TCP/IP address is on the RBL or not. The RBL, or Real-time Blackhole List, is a black list of TCP/IP addresses, which have been associated with Spam. The RBL is somewhat effective at blocking Spam, but it also will block of fair amount of legitimate email as well. The MailShield Language 114 You should only use this function if you are well aware of what the RBL is about, and how it works. For more information, please see the Web site: http://maps.vix.com/rbl/ For example: if (&IsOnRbl("207.15.2.3")) { print "That TCP/IP address is on the RBL."); }; IpToHostname The MailShield command "&IpToHostname" is used to convert a TCP/IP address into an Internet hostname. This is commonly known as a reverse DNS lookup. If no hostname can be found for the given TCP/IP address, then this command returns an empty string. For example, this command can be used to obtain the hostname of the Internet host that is currently connected via SMTP to MailShield. MailShield uses its own DNS resolver routines, rather than the routines built into the operating system. We have found that these are more efficient, and more reliable. For a single DNS lookup, MailShield will send the DNS request, wait 10 seconds, and then resend it if no answer has returned. MailShield will retry 4 times, for a total of a 40-second wait, before giving up on a DNS lookup. For example: $variable = &IpToHostname("207.90.151.11"); $variable = &IpToHostname($PeerTcpip); Join The MailShield command "join" will take a string separator, and an array name, and return a single string which is composed of all the elements of the array, joined using the joining string which was specified. If there is only one element in the array, then no joining string will be used. For example: $a = join (", ", @array); Keys The MailShield "keys" command returns an array of key values when given the name of an associative array. For example: @array = keys (%assoc); Length The MailShield command "length" will return a number that is the string length of the string, which is passed to it. For example: $length = length ("two words"); The MailShield Language 115 LogMessage The MailShield command "&LogMessage" is used to put a message into the MailShield log. If you are currently running MailShield in the foreground, then the log entry will also be displayed on the screen. Each log entry is prefixed with a single character, which indicates what kind of log entry it was. There are two formats of this command: &LogMessage("log message"); &LogMessage("log message", log_smtp); The first format of the command takes a single string as its parameter and places it into the log. The string is placed into the log as a log entry of type "log_script_log". The second format of the command takes both a string as its parameter as well as a log type. See below for a list of valid log types. The valid log types are: log_config log_database log_major log_nntp log_program_list log_program_output log_program_parse log_refuse log_script_log log_smtp log_urgent The first letter of each log entry is defined as follows: log_config = c log_database = d log_major = m log_nntp = n log_program_list = l log_program_output = o log_program_parse = p log_refuse = r log_script_log = t log_smtp = s log_urgent = u LongestLength The "&LongestLength" command returns a number, which is the size of the longest line passed to it. The "&LongestLength" command takes a string and returns the length of the longest single line in the string. For example: $size = &LongestLength("this is\na test"); The MailShield Language 116 LongestLengthInArray The "&LongestLengthInArray" command takes a given array, it returns the string size of the longest array element. This can be useful to determine the longest line in an email message, such as with &LongestLengthInArray(@Data); For example: push(@text, "this is"); push(@text, "a test"); $size = &LongestLength(@text); Message The MailShield "&Message" command sets the SMTP message that MailShield will give to the connecting host if this connection is terminated with a "&Hangup" command. Each message command replaces whatever the most recent message command had set. If no message command has set the SMTP message when a hangup is given, then MailShield will display the default rejection text as defined by the standard rejection notice variable $smtp_rejection, which is normally set in the config.mml file. In the default scripts that are provided by MailShield, a standard rejection subroutine is used in all cases where the connection is to be terminated. With this setup, the variable $message is used to set the rejection message in the calling subroutine, and the default rejection subroutine uses the "&Message" ($message); command to set the rejection message to whatever the calling subroutine had set it to. For example: &Message ("550 your message was rejected "); MessageAppend The MailShield "&MessageAppend" command sets the text, which should be appended, to the default SMTP message that MailShield will give. For example, MailShield uses this command to modify the beginning SMTP greeting with a "hostname approved for relaying" message, in the case that this is the case. This command is useful for when you want the SMTP session to continue as normal, but want to slightly modify the response messages that MailShield returns. NameFromEmail The MailShield command "&NameFromEmail" is used to extract the name portion of an email address from an email address, which is given to it. It would extract "bob" from "bob@somewhere.com". For example: $name = &NameFromEmail("bob@somewhere.com"); ne The MailShield command "ne" will take two strings, and perform a string comparison between them, returning TRUE if the two strings are not identical. The MailShield Language 117 Note: It is important to use this command rather than "!=" when doing string comparisons, because the "!=" operator performs a numeric comparison of two strings, while the "ne" command performs a character-wise comparison of the two strings. For example: if ($a ne "bob") { print "$a is not equal to Bob "; }; Not - ! The MailShield command "!" will negate a TRUE value so that it becomes FALSE, and vice versa. For example: $true = TRUE; $false = !($true); if ($false == (!($true)) { print " FALSE is not TRUE "; }; Numeric equality The MailShield command "==" will take two strings or numbers, and perform a numeric comparison between them, returning TRUE if the two numeric values are identical. For example: if ($a == 1) { print "$a is numerically equal to 1 "; }; Numeric inequality The MailShield command "!=" will take two strings or numbers, and perform a numeric comparison between them, returning TRUE if the two numeric values are identical. For example: if ($a != 1) { print "$a is not numerically equal to 1 "; }; Or - || The MailShield command "||" will take two logical values, and perform a logical OR comparison between them. For example: if (($a == TRUE) || ($b == TRUE)) { print " either $a or $b is true. "; }; The MailShield Language 118 PickRandom The MailShield command "&PickRandom" will take a random string from a comma- separated string and return it. For example: $random = &PickRandom("one,two,three,four,five"); Pop The MailShield "pop" command is used to remove the last element in an array and return it as a string. The syntax is identical to the syntax in Perl. To remove the first element of an array, you should use the "shift" command. For example: push(@array, "a string"); push(@array, "another string"); $string = pop(@array); Print The MailShield "print" command prints the text given to it onto the screen. If you are running MailShield as a background process, such as a Unix background daemon, or as a Windows service, then you will not see the output of the print command on the screen, unless you also happen to be logging the MailShield output to a text file. On Windows, the installation program automatically sets MailShield up to log output to a file. See the section on the MailShield log for more information about logging. Unlike Perl, MailShield does not do any variable substitution on the text inside the current statement. The only characters which are substituted inside a print statement are the \n and \r characters, but only if the string is enclosed in double quotes. If these strings are enclosed in single quotes, then there is no substitution whatsoever. If you want to print variables, you should make sure that the variables are not inside a quoted string (as Perl supports, but MailShield does not), and use the "." concatenation operator to build the string that you want to display. For example: print "this is a variable value: ".$var; The print statement will accept its parameter inside parentheses or without parentheses, use whichever form you prefer. For example: print("text"); and print "text"; are equivalent. For example: print "hello world!"; print("hello world!"); Push The MailShield "push" command is used to add a string item to an array. The syntax is identical to the syntax in Perl. For example: The MailShield Language 119 push(@range, "207.90.155.99"); You can also push an entire array onto another array by specifying an array name instead of a string as the second parameter. For example: push(@range, "207.90.155.0-207.90.155.20"); push(@range, "207.90.155.50-207.90.155.70"); push(@another_range, @range); RandomString The MailShield command "RandomString" will return a string composed of random a-z characters of the size that you specify. For example, you might use this function to create a random filename, that you could then write to disk, without fear that this file already exists on the disk. For example: $filename = &RandomString(8).".txt"; ReadFile The MailShield command "&ReadFile" is used to read the contents of a text file into a variable. If the file that is specified cannot be found on the disk, then MailShield continues, and no text is assigned to the variable. Note: If no directory is specified, that the file is read from the current working directory, which can be set using the chdir() command. For example: $variable = &ReadFile("test.txt"); Regindex Command The MailShield command "regindex" will try to find the specified regular expression inside another string. Note: to specify that a string be interpreted as a regular expression, you must surround it with forward slashes. In otherwords, whether you are specifying a regular expression inside a string in a rule file or whether you are specifying a regular expression in a config file, it must be surrounded by forward slashes. For example, if you want to keep tabs on what Jim has done, you may specify a regular expression in your bansubj.txt file like so: /jim.*it/ Thus, whenever a message comes through that has a subject like "jim ate it" or "jim threw it away", you can catch it. For more information on regular expression syntax, refer to the GNU regular expression library documentation, available on our ftp site at: ftp://ftp.lyris.com/mailshield/doc/regex.txt The MailShield Language 120 The "regindex" command returns the starting position of the match inside the string as its return value. If the regular expression is not found inside the string, the "regindex" command returns a value of -1. The syntax is: regindex (string, string); There are several forms to the "regindex" command. All the different forms take this basic approach: regindex(THING_TO_SEARCH_THROUGH, THING_TO_SEARCH_FOR); For example: if (regindex("jim found it", "/jim.*it/") > -1) { print "found a match"; }; Another form of the regindex command takes an array of substrings, and returns the numeric position of the first substring, which matches in the string. This is a very fast way to search a single string (such as the body of a message) for a number of different strings. The syntax is: regindex(string, @array); For example: push ("/jim.*it/", @string); if (regindex("jim found it", @string) > -1) { print "found a match"; }; Another form of the regindex command takes an array of strings to search through, and a single string to search for. The syntax is: index(@array, string); For example: push ("jim ", @string); push ("found ", @string); push ("it", @string); if (index(@string, "/jim.*it/") > -1) { print "found a match"; }; Another form of the index command takes both an array of substrings, and an array of strings to search, and returns the numeric position of the first string, which matches, in the first substring. This is a very fast operation. One use for this command is to search all the Received: headers, in a single fast operation. The syntax is: index(@array, @array); For example: push (@substring, "/jim.*it/"); push (@string, "jim ate it"); if (index(@string, @substring) > -1) { print "found a match"; }; The MailShield Language 121 Regular expressions Regular expressions are mathematical representations of search specifications. They are similar to wildcards (such as those found in DOS), only much more powerful. MailShield supports regular expression searching and regular expression replacing. In a regular expression search, MailShield will search the given string for the pattern specified and return TRUE if the search produces a match. Thus, a regular expression search can be used inside an "if" statement. In a regular expression replacement, MailShield searches for the search expression given, and if a match is found, the matched text is replaced. The following types of regular expression searches are supported: STRING =~ /REGEXP/; STRING =~ @array; With regular expressions of the form STRING =~ /REGEXP/; a single regular expression is used against a single string. For example: $variable =~ /harass/; In this example, if the word "harass" is found in the value of $variable, then the regular expression search returns a TRUE value. To put the same example in context, here is another example using an "if " statement: if($variable =~ /harass/) { print "found"; }; Another technique would be to use the "not" operator--"!"--To run an "if" statement that evaluates to TRUE if the given regular expression does not match, for example: if (!($variable =~ /harass/)) { print "not found"; }; You can also specify several regular expressions to test with by using an array as your regular expression. For example, if you wanted to match on the word "harass" or in the word "bother" you could use the following commands: push (@regexps, "bother"); push (@regexps, "harass"); if ($variable =~ @regexps) { print "matched"; }; The syntax for a regular expression replacement is: $variable =~ s/REGEXP/REPLACEMENT/; $variable =~ s/REGEXP/REPLACEMENT/g; The regular expression in the above replacements is placed in the REGEXP position, and the text to replace the match is placed in the REPLACEMENT position. The optional "g" specifies that the replacement should be "global", meaning that MailShield should find all the incidences of the regular expression, and replace them all. Without the "g" option, MailShield will only replace the first incidence of the regular expression that is found. Regular expression replacements can be useful when you want to make changes in the header or body of the message text. The MailShield Language 122 Note: The current version of MailShield uses the GNU Regular Expression library, which may differ, from a regular expression library that you are used to, such as the regular expressions in Perl. For more information, see About Regular Expressions. Refuse The MailShield "&Refuse" command tells MailShield to immediately refuse the currently sending message and display to the connecting host whatever refuse message has been set with the "&Message" command. The refuse command does not hang up the current SMTP connection, thus allowing the connecting to try to send more messages. The email message that was currently being sent is erased from memory. For example: &Refuse; Require The MailShield "require" command is used to tell MailShield to include another script file at that point. For example, this is a handy way to include the some useful subroutines in your scripts, without needing to copy and paste the code into every script it that they are used in. For example: require "standard.mml"; Return The MailShield "return" command causes MailShield to stop running the current script. It is identical to the "exit" command. This is useful if, for example, your script has determined that the rules that follow do not apply to the current SMTP session. The scripts that are defined to run in later portions of the SMTP session will still be run, but the execution of the current script will stop immediately. For example: return; Scalar variable assignment To assign a value to a scalar variable (a $variable), you can use the same syntax as in Perl, namely $variable = VALUE; The VALUE can be either a string or a number. Here are several examples: $variable = "text"; $variable = 1; $variable = "this is another variable value: ".$another_variable; The MailShield Language 123 SendBCCNow The "SendBCCNow" command sends a copy of the current email message to the email address that is given to it. You can also specify a TCP/IP address and port number, if you wish. If you do not specify a TCP/IP address and port number, MailShield will perform a "final delivery' of the email message, using DNS to determine where to send the message to. For example: &SendBCCNow("bob@acpoq.com", "", ""); &SendBCCNow("bob@acpoq.com", "206.4.1.9", "25"); SendEmail The "SendEmail" command will send the text, which is passed to it as an email message to the recipient indicated. The syntax of the command is: &SendEmail(string, string, string, string, string); [from] [to] [body] [ip] [port] The first parameter defines the MAIL FROM value. The second parameter defines the RCPT TO value. The third parameter defines the body of the message, including any header lines. The fourth parameter defines the TCP/IP address of the SMTP server to send this message to. The fifth parameter defines the port number on the SMTP server to send this message to. This setting requires the fourth parameter to also be set. Only the first three parameters are required. If you do not specify the 4th and 5th parameters, MailShield will perform a "final delivery" of the email message, using DNS to determine where to send the message. You must specify all 5 parameters in your call to "&SendEmail". If you do not want to specify the 4th and 5th parameters, pass empty strings ("") instead. For example: $body = "Subject: test\n"; $body .= "From: john@acpoq.com\n"; $body .= "To: bob@acpoq.com\n\n"; $body .= "This is a test message.\n"; $mail_from = "john@acpoq.com"; $rcpt_to = "bob@acpoq.com"; &SendEmail($mail_from, $rcpt_to, $body, "", ""); &SendEmail($mail_from, $rcpt_to, $body, "207.5.2.4", "25"); Shift The MailShield "shift" command is used to remove the first element in an array and return it as a string. The syntax is identical to the syntax in Perl. This command is The MailShield Language 124 similar to the "pop" command except that the first element is removed rather than the last element. For example: push(@array, "a string"); push(@array, "another string"); $string = shift(@array); Sleep The MailShield "sleep" command is used to have a MailShield script do nothing for the specified number of seconds. This command is useful if you want to make the SMTP session pause for some reason. For example, if you suspect that someone you have approved for relaying through your mail server is using you for bulk mail delivery against your wishes, you can have your script sleep for a second or two after each recipient, so that using your mail server for bulk mail delivery becomes very slow for them, but not impossible. With this technique, you can prevent people from abusing your mail server as a relay host, but still remain open for legitimate uses. This feature is currently implemented as a MailShield feature. The "tarpitting" feature also makes use of this command. For example: sleep(2); Split The MailShield command "split" will take a string separator, and a string with multiple values in it, and return an array of the multiple values in that string which were found using the separator. For example: @array = split (/,/, "1,2,3,4,5"); Note: In order to maintain the syntax compatibility with Perl, the string separator appears to be a regular expression. However, at this time, the string separator is not treated as a regular expression, but is treated as a simple string separator. String concatenation To concatenate two strings together, you can use the concatenation operator, which is a period ("."). For example, to concatenate a string and a variable together, you could use the following syntax: $variable = "My name is ".$my_name; The syntax of the string concatenation operator is: STRING.STRING For example: $a = "hello "."world"; The MailShield Language 125 $a = "hello"." "."world"; Substr The "substr()" command is used to extract a portion of a string, and works exactly as it does in the Perl language. You specify the string text, the character number to start and a length. The syntax is $string = substr("string", start, length); For example: $string = substr("this is a test", 5, 2); Subroutine definitions Subroutines are useful for clustering a number of commonly used commands under a single command and then referring to the command in other places. For example, MailShield defines a default rejection subroutine to use whenever a message is being rejected. This way, you need only change the commands inside the default rejection subroutine to affect the way in which MailShield rejects all messages. By default, the default rejection subroutine logs the rejection and then hangs up the SMTP connection. An example of the power of subroutines is that you could change the default rejection subroutine to forward rejected mail to an administrator account, rather than just rejecting it. In fact, one of the options is to do just this: take a look at standard.mml for an example of this. The syntax for defining a subroutine is: sub SUBROUTINE-NAME {COMMANDS}; Be sure to include a semicolon at the end of the close curly brackets, otherwise MailShield will tell you that you have a syntax error in your script. Perl allows you to be sloppy about this requirement: MailShield is strict about needing it. The syntax for calling a subroutine is: &SUBROUTINE-NAME; Note: unlike Perl, MailShield does not let you directly pass parameters to a subroutine. If you want to pass parameters to a subroutine, you should define parameters as gkibak variables that the subroutine can read. Since all variables in MailShield are global in scope, any subroutine can read any variable defined in another part of the script. Be sure that you do not accidentally include the () characters when you call a subroutine, because MailShield does not support that syntax either. For example, &RejectMessage; is valid, while &RejectMessage(); is not. For example: sub RejectMessage { print "rejected."; }; &RejectMessage; Subtract - - The subtraction operator, which is the minus sign "-" can be used anywhere a string or number is used. Note: You must have a space between the - sign and the text it is operating on. Thus, "$a = 4-2"; is not valid because there are no spaces around the +, while "$a = 4 - 2"; is valid. For example: $a = 4 - 2; $a = "4" - "2"; The MailShield Language 126 System The MailShield command "system" will execute the string, which is passed to it as a system command, and will return the return value of the system command as a string. Note: The return value is not the output of the command, but the numeric return code. For example: $retval = system("rm /tmp/test.txt"); $retval = system("del \temp\test.txt"); TRUE and FALSE The MailShield constants "TRUE" and "FALSE" are equal to the values one and zero, respectively. Because it is easier to read MailShield macro commands when they use these constants, we often will write our programs using them. However, if you prefer, you can just as easily use the numbers one and zero instead. For example: $a = TRUE; $b = FALSE; Undef The MailShield "undef" command removes a defined variable from the variable space. In other words, if a variable currently has a value and you "undef" it, then the variable disappears, and no longer has a value. The "undef" command works with all MailShield variable types, such as scalar variables ($variable), arrays (@array), and associative arrays (%associative). For example: $variable = "value"; undef($variable); undef (@array); undef (%associative); undef $associative{"key"}; undef $array[1]; Unshift The MailShield "unshift" command is used to add an element to the beginning of an array. It is similar to the "push" command, except that it adds the string to the beginning of the array, while the "push" command adds the string to the end of the array. The syntax is identical to Perl. For example: unshift(@array, "a string"); The MailShield Language 127 Upper Lower Case The MailShield commands "uc" and "lc" will convert a string or an array into upper or lowercase. For example: $bob = lc("BOB"); $BOB = uc("bob"); push(@bob, "bOb"); lc(@bob); uc(@bob); Values The MailShield "values" command returns an array of values from an associative array, when given the name of an associative array. For example: @array = values (%assoc); Appendix 129 Appendix What is new in this version? New in Version 2.0 New features of interest to all: * New Admin Web GUI: configure MailShield using your web browser. * Mail Merge support: fetch web pages and insert them right into your message. * New spam detection: support for the RSS (Relay Spam Stopper) Service. * New spam detection service: support for the RBL+ service * Updated spam detection: modified DUL rule to use new DUL feed. New features of interest to advanced users: * New function: regindex allows regular expressions in config files. * New rule: rule added to block RCPT TO with :, !, %, and multiple @. * New tarpitting method: tarpit to guard against excessive RCPT TO probing. Bug Fixes: * Banned Filename feature: fixed a bug where some attachments would get through New general-purpose features: New Admin Web GUI: configure MailShield using your web browser MailShield now has a built-in web server which allows you to alter your config files using a web browser. This powerful feature allows for simpler remote administration, and improved navigation so you can quickly adjust related settings. This web server will not interfere with your existing web server. See Admin Interface Port Number, Admin Interface TCP/IP Address, and Admin Interface Password. Mail Merge support: fetch web pages and insert them right into your message You can now use MailShield to fetch web pages and place them into your message. You can additionally insert the recipient's email address into your web page request so you can fetch content specific for that recipient! Mail Merge supports cookies and http services running on alternative ports. See Mail Merge Support. New spam detection service: support for the RBL+service The MAPS organization has a new service which allows you to utilize each of their three services (RBL, RSS, and DUL) with a single lookup. The RBL+ service is a Appendix 130 convenient way to check three MAPS databases with a single DNS lookup. This feature will not work correctly unless you subscribe to MAPS. See RBL+ Service. New spam detection: support for the RSS (Relay Spam Stopper) Service The folks at MAPS have made a new service available for stopping spam: the Relay Spam Stopper. This service provides a listing of hosts on the Internet known to relay (i.e. not generate) spam. By adding support for the RSS, MailShield provides you with another level of spam protection. See Relay Spam Stopper. Updated spam detection: modified DUL rule to use new DUL feed The hostname used to lookup entries in the DUL has changed since the last release of MailShield. This version includes the updated hostname, providing you with accurate DUL service once again. See DUL: Block Dialup Users. New features for Advanced Users: New function: regindex allows regular expressions in config files A modified version of the index function now provides support for regular expressions. The new function, regindex, allows you to use regular expressions in your config files rather than using only exact strings. See Regindex Command. New rule: rule added to block RCPT TO with :, !, %, and multiple @ The rcptto.mml file now has two new rules which help to block new types of spam. Similar to source routed messages, spammers have been successfully relaying mail by using :, !, or % in the RCPT TO value. Similarly, some messsages have multiple '@', and those too are now blocked by default. New tarpitting method: tarpit to guard against excessive RCPT TO probing Some spammers probe your mail server for valid addresses by using the RCPT TO command repeatedly. This tarpit protects your mail server from this kind of abuse by introducing a five second delay after each RCPT TO command. You configure the threshold at which the delay is introduced. See Tarpit Excessive RCPT TO:. Bug Fixes: Banned Filename feature: fixed a bug where some attachments would get through We found a bug in MailShield version 1.5 where some MIME encoded attachments were not accurately detected. This has since been fixed, and we have also modified the data.mml file to look for "name=" rather than "filename=" in order to protect against email programs which use "name=" as an abbreviation. New in Version 1.5 New features of interest to all: * New spam detection: spot sendmail HELO buffer overflow trick. * New spam detection: supports the Dialup User List (DUL) ban list. * New spam detection: multiple RCPT TO with blank MAIL FROM. * New spam detection: check Subject for Prefixes such as AD: or ADV: * Feature to dynamically verify recipient addresses against destination server. * Feature to ban filename types in MIME attachments, e.g., .EXE, .BAT, etc. * Feature to limit length of MIME attachment filenames, blocks well known exploit. * Feature to canonize From: addresses of outgoing mail. * Feature to specify approved To: headers to bypass filters. * Feature to append your message to the SMTP Welcome message. * Support for destination SMTP server load-balancing. Appendix 131 * Support for failure-over destination SMTP servers. * Multiple TCP/IP addresses are now specified with carriage returns. New features of interest to advanced users: * New function: &BodyPrepend to prepend text to the message body. * New function: &MessageAppend to add your own SMTP begin text. * Support for ESMTP EHLO command. * Support for ESMTP SIZE feature. * Support for rewriting of the SMTP RCPT mail recipient. * New function: substr(). * New function: &extract to pull out specific text from messages. * Many New DNS lookup functions. * Unix "nopid" option to not write the process id to file. * New Function: &LongestLengthInArray. * New function: &HeaderMimeGetAllArray. * Added + and operators. * Ability to toggle debug mode on/off in real time. * ORBS support has been disabled. New general-purpose features: New spam detection: spot sendmail HELO buffer overflow trick The original sender in a message is usually shown in one of the Received: headers. However, a bug in many versions of Sendmail allows the sender to overflow the HELO buffer with a very long text string, so that the Received: header does not show the original TCP/IP address. This filter detects this trick, and rejects mail that has exploited Sendmail in this way. New spam detection: supports the Dialup User List (DUL) ban list The DUL is a new black list of dialup user TCP/IP addresses. The DUL is distributed via DNS, using the same mechanism as the ORBS and the RBL. This ban prevents people using dialup accounts from sending email directly to you: they instead need to send mail through their ISP. Since the vast majority of email from dialup accounts is sent through an ISP's mail server, and spam is routinely sent directly from a dialup account, the DUL is effective in blocking spam directly-sent from a dialup account. New spam detection: multiple RCPT TO with blank MAIL FROM The only kinds of email messages that have a blank Return-Path: (i.e.: MAIL FROM) are system error messages, and these should only have one recipient. Spammers sometimes use a blank MAIL FROM to hide their tracks. This filter rejects mail that has multiple recipients but a blank MAIL FROM. New spam detection: check Subject for Prefixes such as AD: or ADV: Some states have laws that require unsolicited email to have AD: or ADV: prefixing the subject line. This filter detects this text, and rejects mail that contains it. Feature to dynamically verify recipient addresses against destination server One of the disadvantages of using a relay server, such as MailShield, is that MailShield does not know if all the recipient accounts are all valid until it actually sends the final message. This new feature dynamically opens up a separate TCP/IP connection to the destination server to verify recipient addresses on the fly. Performance is further improved by an in-memory caching of valid recipients. Appendix 132 Feature to ban filename types in MIME attachments, e.g.: .EXE, .BAT, etc. You may want to block executable attachments, such as .EXE, .COM, or even Microsoft Word .DOC files. This feature allows you to do that. Feature to limit length of MIME attachment filenames, blocks well known exploit Some email clients crash when they receive email with a very long filename in an attachment. This crash can potentially be used to run programs on other people's computers. This filter checks for this and rejects messages with attachment filenames over your specified size. Feature to canonize From: addresses of outgoing mail Companies with many mail servers often have different From: addresses depending on what mail server a message was sent from, i.e.: you@mail.yourserver.com. This feature removes the extra hostname parts to the From: and Reply-To of outgoing mail, so that a "canonical" you@yourserver.com address is used for outgoing mail. Feature to specify approved To: headers to bypass filters Some automated programs have invalid To: headers, which makes the "check for valid To:" filter read a false positive on them. This feature lets you specify text in the To: which indicates that a message should be let through. Feature to append your message to the SMTP Welcome message Some mail servers advertise themselves in the SMTP response as "we do not accept unsolicited email". This allows you to specify your own disclaimer. There are laws being proposed to make this disclaimer legally enforceable. Support for destination SMTP server load-balancing If you receive a great deal of email, and your single mail server cannot handle the load, you can tell MailShield to balance the load among any number of destination mail servers. Use a comma to separate multiple mail servers. Note: You must purchase a separate MailShield license for each email sever you are protecting with MailShield. Support for failure-over destination SMTP servers If one of your mail servers become unavailable, MailShield can try others at your organization. You specify fail-over mail servers with a semicolon between each SMTP server address. Multiple TCP/IP addresses are now specified with carriage returns Previously, multiple TCP/IP addresses that MailShield should listen to were specified with a comma. Now, a carriage return is used, in order to be more in line with the other file standards. New features for advanced users: New function: &BodyPrepend to prepend text to the message body Call the function like so: &BodyPrepend ("This was message was received by MailShield") New function: &MessageAppend to add your own SMTP begin text Call the function like so: &MessageAppend("we do not accept unsolicited email") in the BEGIN.MML script, to have it added to the response that MailShield sends back as part of the SMTP welcome message. Support for ESMTP EHLO command The EHLO command is now supported, and indicates that maximum message size accepted. Appendix 133 Support for ESMTP SIZE feature The MAIL FROM:<xxx> SIZE= parameter is now supported, so that if the sender indicates that a message is over the allowable size, it is refused before the sender starts delivering the body text. Support for rewriting of the SMTP RCPT mail recipient The $SmtpRcptTo can be rewritten to anything you like, while in the RCPTTO.MML script, so as to redirect a message to a different recipient. New function: substr() The perl substr() command has been implemented in the MailShield macro language. The syntax is $string = substr("string", start, length); New function: &extract to pull out specific text from messages The &extract function takes a regular expression, and returns an array of all the text strings that match that regular expression. For example, this function is used to pull out all the MIME filename attachments. The syntax is this: @array = &extract(/regexp/, $string); Many New DNS lookup functions Several new DNS function calls have been added. These are: @array = &DNSMXLookup string; string = &DNSCnameLookup string; string = &DNSRevLookup (string); string = &DNSRBLLookup (string, string); @array = &DNSALookup string. The MX lookup does a full DNS MX lookup on a hostname, and returns the TCP/IP addresses of all the mail servers for that hostname. The Reverse lookup takes a TCP/IP address and returns a hostname. The Cname lookup returns the authoritative name for a hostname. The A lookup returns an array of TCP/IP addresses for a given hostname. The RBL lookup can be used for any arbitrary RBL-style DNS lookup, such as the RBL, the ORBS, or the DUL. For example, this is an RBL lookup: $test = DoRblLookup(".rbl.maps.vix.com", $PeerTcpip); Unix "nopid" option to not write the process id to file When the "nopid" option is given on the command line, the MailShield process id is not written to the /etc/shield.pid file, as it normally is by default. New Function: &LongestLengthInArray This function takes an array, and returns a number representing the longest string length of one string on the array. New function: &HeaderMimeGetAllArray Returns an array of strings, which are just the MIME headers in a message body. These are extracted by looking for the Content-Type: boundary separator and copying the MIME headers indicated. Added +and - operators The plus and minus operators have been added. Note: A space must separate a number and these operators, so that "2+2" is not valid, while "2 + 2" is valid. Ability to toggle debug mode on/off in real time On Windows, you can use the Ctrl-Break key to toggle debug mode on and off, while on Unix, you can send a signal USR1 to the MailShield process to do this, with the command: "kill -SIGUSR1 `cat /etc/shield.pid`" ORBS support has been disabled The support for the Open Relay Blocking System (ORBS) has been disabled as of December 1, 1998, because the ORBS information feed has been shut down. The person running the ORBS is no longer providing the information and has terminated its operation. Appendix 134 New In Version 1.1 * Support for the Open Relay Blocking System (ORBS). * Connection limitation feature. * Much lower memory requirements. * Syslog capability on Unix. * DNS caching. * Ability for large messages to bypass body tests. * New entries to detect spam-sending packages. * Ability to disable reverse MailShield's DNS lookups. * New indexlc commands for case insensitive text searching. * New $DataBytes and $DataLines variables give message size. * Header functions: &HeaderParse, &HeaderBuild, &CommitHeader. * All text matches now display what pattern matched in the log. * Better handling of intermittent DNS problems. Support for the Open Relay Blocking System (ORBS): MailShield now supports the ORBS, a new anti-spam initiative. Connection limitation feature: You can now limit the number of simultaneous incoming connections that MailShield accepts. This can be useful if your destination mail server cannot handle more than a certain number of connections. Much lower memory requirements: MailShield now uses much less memory when processing very large attachments. Previously, very large email messages could cause Windows to run out of memory. Now, the memory needs were reduced about 4X, so this problem should no longer occur. This also means that MailShield runs faster in low-memory situations. Syslog capability on Unix: MailShield can optionally send its system log to the Unix syslog. DNS caching: all DNS lookups are cached in memory. These include MX, A and PTR lookups. This results in a big speed increase, especially if your DNS server is already overloaded. Ability for large messages to bypass body tests: You can now set the threshold at which large messages are not subject to the "banned body" tests. This can be useful if you receive a great deal of large messages, in order to speed their processing. New entries to detect spam-sending packages: We have added defaults to the banned text sections of several options, in order to target specific spam-sending programs. Ability to disable reverse MailShield's DNS lookups: If you do not use any MailShield features which use reverse lookups, you can tell MailShield to no longer perform them, so as to improve performance. New indexlc commands for case insensitive text searching: These are faster, and lower memory, methods for searching through text in a case-insensitive way. New $DataBytes and $DataLines variables give message size: These are faster and easier ways to obtain these two pieces of information. Previously, you needed to use the command scalar(@Data) to obtain the message lines, and length($Data) to obtain the byte size. Header functions: &HeaderParse, &HeaderBuild, &CommitHeader: These allow you to manipulate other headers, as well as easily change the current header and commit the changes. All text matches now display what patern matched in the log: For example, if you ban a domain called "spammers.com", and a mail is blocked from Appendix 135 "mail.spammers.com" then the log will tell you that the matching text string was "spammers.com" Better handling of intermittent DNS problems: MailShield now first performs a non-authoritative DNS lookup, and if the DNS server returns a failure, an authoritative lookup is performed. Previously, MailShield only performed an authoritative lookup. New in Version 1.04 The Windows installation program now gives you the option of rejecting unwanted email, marking the subject of unwanted email, or forwarding unwanted email to another email address. Backup mail options now allow you to use all mail rejection features, and still receive a backup mail copy of the rejected mail. Previously, you were not allowed to use a backup feature if you used use rejection features, which rejected a message before the body text was received. Added X-Rejection-Reason: header to backup copy (or marked subject) of rejected messages, so that the recipient can see the reason why a message was rejected. New feature: option to reject messages with no Subject: line. Added "&CommitData" command, to commit any changes to the message text stored in @Data. New in Version 1.0 beta 3 New Script Features New feature: define MAIL FROM:<> values that are ok to relay. Added option to give refused people helpful errors vs. just plain "message refused". Add "approved for relaying" SMTP message when connecting host is ok. MailShield now automatically reloads the configuration files if any dependent files change. New feature: give tcp/ip and hostname range that should be tarpitted, and ability to specify tarpit delay. Added option to unconditionally pass mail if it is Mail From: defined text or Rcpt To: defined text. Added support for the Real-time Blackhole List (RBL). New feature: reject invalid To: email address. Add switch that simply marks the subject line of rejected mail and lets it through to the recipient. Added an option to have a backup mail server which gets an extra copy of all refused incoming mail, as a failsafe backup for refused mail. Added a check interval feature, which defines how often config files should be checked to see if they have changed. Option to reject HELO value that is a TCP/IP address - require a host name. Appendix 136 Forwarding of individual messages use whatever value is in the $smtp_server variable, which allows selecting routing of individual messages, by changing the value of this variable. New MailShield Language commands: Added "return" command, which is identical to "exit". Add "&MessageAppend" command for appending a response to the normal SMTP response message. Add "&HeaderGetAll" so that it returns all the lines of a multiply existing header, such as Received: Add "&ExtractEmailAddress" command to parse a message From: line into just an email address. Add "&CountOccurence" command, which counts how often a given text string appears. Added support for if (@array =~ /regexp/) changes -- regular expressions on arrays. Add "&IsIpAddress()" function, to determine if a given string looks like a TCP/IP address. Add &LongestLength(@array) and &LongestLength($string) to return the length of the longest line in the text. Add "&SendEmail" feature, to send an email message. Add "&SendBccNow"("email@somewhere.com"); to send a blind-carbon-copy of the current message to another server or recipient. Changes Changed Received header to be: Received: from <IP> by <me> with MailShield (MailShield version); <date> Changed RELAY_SUCCESS message to instead give hostname of mail source. Upon startup, MailShield now checks that mml.* and rules\config.mml files do indeed exist. Variable named "$match" contains the match results of the most recent index() or regexp search. Changed date format of logging to use YYYY-MM-DD format. Removed need for $dir setting. Added built-in variables $dir_program, $dir_config and $dir_rules, which point to the program directory, the config directory, and the rules directory. Made "config" always be the configuration directory. Add command to give first TCP/IP address on the current machine, useful when registering a MailShield serial number: "shield tcpip". Added support for easy MailShield upgrades. Bugs Fixed Appendix 137 Fixed bug where restarting on Unix when loaded as a service does not work. MailShield Language parser can now handle nested bracketed statements (such as nested if() statements) up to 12 levels deep. Mail from:<> checking is now able to handle "Chris Someone <Chris.Someone@someplace.com>" format. There was a problem with running external programs: if the load was high enough to spawn multiple copies of external programs at once, an error message appeared. This has been fixed. X-peer-info was giving localhost name as the peer, not the right name. This has been fixed. New in Version 1.0 beta 2 New Features: New sleep() function pauses script (and SMTP connection) for a given number of seconds. This is useful for ISP's who need to allow their customers to use them as a relay host, but are worried that their customers might use them to deliver bulk email. Adding a small delay (about 2 seconds) after each recipient (above a certain threshold) discourages your customers from using you for bulk email delivery. New "&CreateFile" and "&AppendFile" functions can be used to write custom logging, and also to save rejected messages directly to disk. The command index(@array, "text") sets the variable "$index_match" to the matching text in the @array if there is a match. This is useful for spotting exactly what text match caused a rejection. The "exit" command was added. There are now buttons in the Windows Help File, which open up "notepad" on the named file, to enable easy editing of MailShield configuration files. All "push" statements now refer to text files for their configuration information. This is significantly easier for users. All text matches (such as subject:, domain-matches, etc.) are now performed in lowercase, so that they are case insensitive. Previously, text matches were case sensitive. New feature added: check for banned Received: headers. Added "&RandomString" function, useful for creating random filenames, especially when saving email to disk files. Added "lc" and "uc" functions, to convert text to lower or upper case, and these work both on strings and arrays. New feature added: reject messages with no To: header. New logging function: you can now define the type of log item a single long entry is. Faster script execution: comment lines are now pre-processed out of the MailShield scripts, which increases execution speed. Added command to pick a random item from a comma delimited list of items: "&PickRandom". This will be useful for load balancing relaying between multiple servers. Appendix 138 Changed handling of hosts, which are allowed to relay, so that they still have some basic checks. Such as: MailShield can slow down bulk mail acceptance, to discourage relay server abuse by accepted relay hosts. Reverse DNS lookups now use our own DNS resolver routines, instead of the system routines. Our routines are much more tolerant of DNS failures and timeouts. Log types are now "on" by default: SMTP event logging, script program output and SMTP session refusals. New ability to disable all reverse DNS lookups, if higher speed is desired. A single wildcard symbol, "*" can be used in IP-Address range matches, and in text matches, to always produce a match. Bugs Fixed in 1.0 beta 2 Fixed bugs with the "&FileToArray" function. Text matching on headers which can recur (such as Received) now works properly. Reloading of configuration file (with ctrl-break in Windows, kill -1 in Unix) now works correctly. Unix log file no longer has extra \n character on each line, which is a DOS format text file. Now, log files are in Unix text file format. "VRFY" command now returns "220 not implemented" reply. Previously, this was "200 ok". A semicolon has been added to the MailShield-inserted Received: line, so that it conforms to Internet standards. Better error messages are now given when the destination relay mail server is unavailable. A bug with relaying to multiple recipients is now fixed. Operating System Platforms This release is available for Windows NT/2000/9x, Solaris/Sparc, Solaris/Intel, Linux/Intel, and FreeBSD. 10mb of available RAM and 10mb of disk space or recommended. Software License Agreement Lyris Technologies, Inc. grants you a non-exclusive license to use this copy of the program subject to the following terms and the proprietary notices, labels or marks on the program and the accompanying documentation. You may: 1. Use this program only on any one computer at any one time. 2. Make a copy of the program in machine-readable form for archival purposes as long as all proprietary notices are reproduced on each copy. You may not: Appendix 139 1. Modify, translate, reverse engineer, decompile, disassemble, or create derivative works based upon this program. 2. Rent, transfer or grant any rights in this program or accompanying documentation in any form to anyone else without the prior written consent of Lyris Technologies, Inc. 3. Remove any proprietary notices, labels or marks on the program and accompanying documentation. 4. Use this program, or permit this program to be used, on more than one computer at any one time. This license is not for sale and it may not be assigned or sublicensed to anyone else. Title and copyrights to the program and the accompanying documentation and any copies remain with Lyris Technologies, Inc. If you do not comply with any of the above restrictions, this license will terminate, you will be liable to Lyris Technologies, Inc. for damages or losses caused by your non-compliance and Lyris Technologies, Inc. will be entitled to a court order which will require you to comply. LIMITED WARRANTY AND DISCLAIMER If, within 30 days from your first use of this product, you are not satisfied with it for any reason, you should stop using it and notify Lyris Technologies, Inc. If you return to Lyris Technologies, Inc. any materials which Lyris Technologies, Inc. has sent to you in connection with the product Lyris Technologies, Inc. will, at your option, either refund your purchase price or replace the product and related materials. LYRIS TECHNOLOGIES, INC.'S LIABILITY IS LIMITED TO THE REPLACEMENT OF THE PRODUCT AND RELATED MATERIALS OR THE REFUND OF THE PURCHASE PRICE. THIS IS THE ENTIRE LIABILITY OF LYRIS TECHNOLOGIES, INC. AND IS YOUR EXCLUSIVE REMEDY. LYRIS TECHNOLOGIES, INC. SHALL NOT BE LIABLE FOR ANY OTHER DAMAGES OR LOSSES INCLUDING DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES OR LOSS OF PROFITS TO YOU OR ANY THIRD PARTY INCLUDING, WITHOUT LIMIT, LOSS OF DATA. THE FOREGOING LIMITED WARRANTY IS IN LIEU OF ALL OTHER WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. This agreement is the entire agreement. If any provision of this agreement is held invalid, the remainder of this agreement shall continue in full force and effect. IF YOU DO NOT AGREE TO THE ABOVE TERMS AND CONTINUE TO USE THIS PRODUCT AND/OR DO NOT RETURN THE RELATED MATERIALS WHICH LYRIS TECHNOLOGIES, INC. HAS SENT TO YOU, LYRIS TECHNOLOGIES, INC. WILL HAVE NO OBLIGATION TO YOU WITH RESPECT TO THIS PRODUCT OR THE RELATED MATERIALS. THE USE OF THIS PRODUCT AND RELATED MATERIALS WILL BE AT YOUR SOLE RISK AND YOU WILL BE LIABLE TO LYRIS TECHNOLOGIES, INC. FOR THE PRICE OF THE PRODUCT AND RELATED MATERIALS.