Sie sind auf Seite 1von 54

Flow Control Filter

Administration Guide

Version 2.0
Sendmail Flow Control Filter, Anti-Virus Filter, and Message Appender Filter Administration Guide Copyright © 2000-2007 Sendmail,
Inc. All rights reserved. Sendmail is a registered trademark, and the Sendmail logo is a trademark of Sendmail, Inc. Other product and
company names mentioned herein may be the trademarks of their respective owners. Reproduction or distribution of this publication is
prohibited without the prior written consent of Sendmail, Inc.
Use of Sendmail Switch and the Sendmail Filters are subject to the terms and conditions of the Sendmail, Inc. License Agreement included
with this package. Refer to the License Agreement for further details. To view the Sendmail Switch copyright statement, click on the
Sendmail Switch graphic in the login screen.
THIS PUBLICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, OR NON-INFRINGEMENT.
THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE
PERIODICALLY ADDED TO THE INFORMATION HEREIN, THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS
OF THE PUBLICATION. SENDMAIL, INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR
THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME.
Printed in the United States of America
4/24/07
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Who Should Use this Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
What’s New in Flow Control Filter 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Before You Read this Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
What Typographic Conventions Mean. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
How to Obtain Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1. Filter Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Configuration Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Enabling a Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
When to Start and Stop a Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Starting and Stopping a Filter on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Starting and Stopping a Filter on UNIX Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Adjusting the Filter Failure Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Configuring a Filter to Run on a Remote Computer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Configuring a Remote Filter on UNIX Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Configuring a Remote Filter on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Configuring sendmail to Work with a Remote Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Filter Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Notes About Filter Options for UNIX and Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Notes About Filter Options for UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Overview of Changing Filter Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Changing the Filter Options on UNIX Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Changing the Filter Options on Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Using Directory Servers in Flow Control Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Sendmail Messaging Directory Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
IPlanet Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Active Directory Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

2. Working with the Flow Control Filter Configuration File. . 15


Creating the Flow Control Filter Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Global Flow Control Filter Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Working with LDAP Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Sendmail® Flow Control Filter Administration Guide 3


Editing and Changing the Order of Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Reputation Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Reputation Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Configuring Reputation Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Reputation Server Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Firewall Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
About the SnortSam Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Sentrion Changes Affect Firewall Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Recipient Harvesting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Rejecting Connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Remote Notifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Milter Short-Circuits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
fc-query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Examples:. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Flow Control Filter Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

3. Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Using Switch Testing Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Problems with All Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Cannot Receive Mail or Filter Is Ignored on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Obtain Offending Message With Switch 3.0 or Later. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Reputation Server Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Flow Control Server Out of Sync with SnortSam Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
IPTABLES Error in SnortSam Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
IPF Error in SnortSam Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

4 Sendmail® Flow Control Filter Administration Guide


Preface
The Sendmail Flow Control Filter helps you manage the flow of messages through the
Sendmail Switch MTA. The filter allows you to manage email volume as a whole, or to
regulate the email based on certain specifications.
Flow Control Filter can be used to set limits on the following:
• Rate of different senders
• Rate of different recipients
• Rate of bounces
• Number or rate of connections
• Rate of envelopes
• Aggregate volume of email over time
Such restrictions can help smooth the peaks and valleys of email traffic, making system
throughput and performance more predictable.
The Sendmail Flow Control Filter can limit spam and enforce company policies regarding
email. For example, the filter can prevent Denial-of- Service (DoS) and “mailbomb” attacks by
limiting the amount of processing power on the MTA that one connection can consume. The
filter can help prevent spam by limiting the delivery of large volumes of email from a single
source.
Flow Control Filter makes use of Sendmail's milter mail filtering API to enact user-defined
flow controls on a particular MTA.

Who Should Use this Book


This guide is intended for system administrators responsible for setting up and maintaining
mail filters.

What’s New in Flow Control Filter 2.0


Flow Control Filter 2.0 contains the following new features and enhancements:
• Action Settings – Section within a Class or UserLimit setting defining actions to be
taken when limits are exceeded. The Message, Response and DisableTime
settings have been moved into the new Action section from the Class and
UserLimit sections.
• Reputations – Flow Control Filter can query a Commtouch IP reputation server to
determine the risk associated with accepting traffic from a particular IP address.

Sendmail® Flow Control Filter Administration Guide 1


Before You Read this Book

• Firewall control – Flow Control Filter can issue requests to firewalls to block traffic
from an IP address causing a limit to be exceeded.
• Notification between Flow Control applications – Separate instances of Flow
Control Filter can notify each other when a class has reached its limit

Before You Read this Book


Refer to the RELEASE=NOTES.TXT file for any last-minute caveats, problems, or
workarounds. This file is located at:
base_install_dir/sendmail/smflow-version/docs/RELEASE-NOTES.txt (UNIX)
base_install_dir\sendmail\FlowControl Filter\docs\RELEASE-NOTES.txt (Windows)

Related Documentation
Please refer to the following additional guides as needed:
• Sendmail® Switch Installation Guide
• Sendmail® Switch Administration Guide
Flow Control Filter can employ the SnortSam firewall agent. SnortSam documentation can be
found at the following URL:
http://www.snortsam.net/documentation.html

What Typographic Conventions Mean


The following table describes the typographic conventions used in this book.

Typeface or Character Meaning Example


Arial Bold Interface elements such as Click the Add button.
menus, fields, links, menu
options and buttons. Select Replace from the Edit menu.
monospace The names of commands, files, /etc/mail/
and directories; on-screen
Generate your sendmail.cf file
computer output; email
addresses. >>> EHLO
support@pogonip.net
monospace bold What you type, as opposed to % cat /etc/hosts
computer output.
italic Placeholder for the true value. Substitute hostname with the name of your host.
Emphasized words or book You must assign a password.
titles.
See Chapter 23 in sendmail.
(Windows) Indicates a Windows path. base_install_dir\etc\mail\ (Windows)
(UNIX) Indicates a UNIX path. /etc/mail/ (UNIX)

2 Sendmail® Flow Control Filter Administration Guide


Chapter : Preface

How to Obtain Technical Support


Technical Support is available to the assigned contacts of all customers holding a current, valid
support contract. The assigned contacts have received passwords and IDs for their Sendmail
support program.
• To log cases:
http://www.sendmail.com/support/
• Phone numbers for customers with phone support:
http://www.sendmail.com/support/contact/
• Support hours and entitlements:
http://www.sendmail.com/support/pp/

Sendmail® Flow Control Filter Administration Guide 3


How to Obtain Technical Support

4 Sendmail® Flow Control Filter Administration Guide


Filter Configuration 1
This chapter describes how to enable and run Flow Control Filter.

Configuration Overview
Follow these steps to configure and run a filter:
1. Enable the filter in the Administration Console.
2. Deploy the configuration.
3. Start the filter. (After the first time, be sure to start the filter before you start the
sendmail MTA; see “When to Start and Stop a Filter” on page 6.)
4. Adjust the failure setting, startup options, or socket setting and redeploy (optional).

Enabling a Filter
To enable a filter:
1. From the main menu, select the Edit Existing Configuration option.
If your configurations are on more than one cluster or host, the Select Host or
Cluster page opens (follow instructions in Step 2). If you have only one host or
cluster, the Administration Console opens the Load Configuration page (skip
Step 2).
2. If necessary, select the host or cluster to configure and then click the Select button.
3. Highlight an existing configuration or type a configuration in the text field and select
the Load button.
The Advanced Configuration page opens.
4. From the options menu, select Mail Filters.
Select the filter you are currently configuring.
5. On the next page, change the default No setting to Yes, then apply and save your
changes.
If you want to administer a filter on another computer, refer to “Configuring a Filter
to Run on a Remote Computer” on page 8.
6. Apply, save, and deploy your new configuration as usual.
7. Start the filter as described in “When to Start and Stop a Filter” on page 6.

Sendmail® Flow Control Filter Administration Guide 5


When to Start and Stop a Filter

When to Start and Stop a Filter


Be sure to start or restart a filter:
• After initially configuring a filter
• At system boot
• After changing the startup options
• After changing the socket location
You do not have to restart a filter:
• When the sendmail MTA is stopped and restarted
• After changing a filter’s failure setting
Always start all filters before you start the sendmail MTA. For example, if you configure a
filter to start automatically upon system boot on UNIX or Windows, set the filter to start before
the sendmail MTA. If you do not, mail could be rejected by the local sendmail MTA,
depending on the settings in “Adjusting the Filter Failure Setting” on page 7.
One or more filters can be started as part of Sendmail Switch deployment. The Deploy
Configuration / Set Deployment Options page within the Administration Console
includes a Start/Restart Filters checkbox as part of its Filter Settings options. See the next
two sections for information on starting and stopping filters directly from Windows and UNIX.

Starting and Stopping a Filter on Windows


On Windows, you can start and stop a filter using the Windows Services dialog box. You may
want to set each filter you administer to Automatic in the Windows Services dialog box, but it
must start before the MTA, as described in the Sendmail® Switch Installation Guide. It is set to
Manual startup by default. You can also use net start filter_name and net stop
filter_name. When using the net start command, either the service display name (which
must be quoted if it contains spaces) or the internal service name must be used.
See “How Sendmail Switch Works” in the Sendmail® Switch User Guide for more information
on these starting and stopping methods.
Starting a filter executable (filter.exe) as a console application in a Command Prompt
window is not recommended, as the filter will stop when you close the Command Prompt
window. If you run the executable as a console application, add -console as the first option,
because otherwise it will run as a service.

Starting and Stopping a Filter on UNIX Systems


On UNIX systems, use the supplied script to start and stop the filters. Type the path to the
startup script followed by start or stop.
For example, the following commands start and stop the Attachment Filter and Message
Appender on UNIX systems:
base_install_dir/sendmail/flow-control-version/etc/init.d/flow-control.sh start
base_install_dir/sendmail/flow-control-version/etc/init.d/flow-control.sh stop
See Table 1-4 for the UNIX startup parameters for your filter.

6 Sendmail® Flow Control Filter Administration Guide


Chapter 1: Filter Configuration

Adjusting the Filter Failure Setting


By default, the filters are set to allow email to pass through unprocessed if the filter is not
running. You can change this to a more restrictive setting.
Setting F=T as described below causes incoming email that cannot be immediately processed
to be queued on the sending computer. This setting is useful if the filter is temporarily
unavailable because it is busy. The available settings are described in Table 1-1.

Table 1-1 Filter Connection Behavior

Flag Description
(No flag set) If the filter is unavailable for any reason, sendmail
will receive incoming SMTP messages as if the filter
was nonexistent
R Reject connection if filter is unavailable
T Temporarily fail connection if filter is unavailable (this
is the default)

Follow these steps to configure the failure setting behavior.


1. From the Main menu, select the Edit Existing Configuration option.
If your configurations are on more than one cluster or host, the Select Host or
Cluster page opens (follow instructions in Step 2). If you have only one host or
cluster, the Administration Console opens the Load Configuration page (skip
Step 2).
2. If necessary, select the host or cluster to configure and then click the Select button.
3. Highlight an existing configuration or type a configuration in the text field and click
the Load button.
The Advanced Configuration page opens.
4. Select Mail Filters from the Options menu.
The Mail Filters page opens.
5. Under the Filter Equates field for the filter, add or change the desired setting after
the socket setting.
When adding a new socket setting, you need to precede the setting with a comma
followed by a space. For example, if you are changing the Attachment Filter
configuration to F=T:
S=local:/var/sendmail/flow-control/flow-control.sock, F=T (UNIX)
S=inet:8895@localhost, F=T (Windows)

Note – If you do not see an entry for the filter, you need to enable the filter first. See
“Enabling a Filter” on page 5.

6. Apply, save, and deploy your new configuration as usual.


You do not need to manually restart the filter after making these changes.
Redeploying the configuration is sufficient.

Sendmail® Flow Control Filter Administration Guide 7


Configuring a Filter to Run on a Remote Computer

Configuring a Filter to Run on a Remote Computer


You may want to configure a filter to run on a different computer than the computer where a
sendmail MTA runs. Doing so requires changing the socket setting used for filter
communication with the sendmail MTA. Multiple MTAs can communicate with one filter in
this fashion. This technique also can be used to set up a DNS round-robin to spread the load
(not described here).

Overview
Follow these steps to run the filter and MTA on different computers. These steps are explained
in greater detail in the next sections. Each computer must have the sendmail MTA or filter
installed.
1. On the computer where the filter runs, change the socket path in the filter’s startup
script.
• UNIX – Edit the startup parameter listed in Table 1-4
• Windows – Enter new Startup Parameters in the Service Manager
2. On the computer where the sendmail MTA runs, change the socket path in the
Administration Console (see Table 1-2).
3. Deploy the configuration.
4. Stop and start the filter.

Note – If you are not running a filter on a computer separate from the MTA, you do not have
to perform any of the steps in this section.

Table 1-2 Filter Socket Types

Administration
Console Syntax Description and Script Syntax
local:path Create a UNIX domain socket using the specified filename. This is the default
configuration for UNIX systems and is not available on Windows systems. This
only works if the filter and sendmail MTA are on the same computer.
To specify in startup parameter (see Table 1-4) on UNIX:
SPATH=/path/to/filename
SOCKETSPEC=local:$SPATH
inet:port@host Create a TCP domain socket to listen at the specified port, which can be a
symbolic name translated by the getservbyname() call, or an integer port
number. The host variable specifies the hostname or IP address to which to bind.
You can use this format to run a filter and a sendmail MTA on different
computers (do not use localhost for host in that case, as that address cannot
be reached by other computers). A TCP domain socket is the only configuration
available on Windows systems.
To specify in startup parameter (see Table 1-4) on UNIX:
SPATH=
SOCKETSPEC=inet:port@host
On Windows, specify the socket in the Service Manager.

8 Sendmail® Flow Control Filter Administration Guide


Chapter 1: Filter Configuration

Configuring a Remote Filter on UNIX Systems


Follow these steps on the computer where the filter runs.
1. Edit the startup script with an editor such as vi or Emacs.
Table 1-4 lists the names of the startup parameters.
2. Change SPATH and SOCKETSPEC in the startup script. For example:
SPATH=
SOCKETSPEC=inet:8790@filterhost.pogonip.net
3. Save and exit the file.
See the section below, “Configuring sendmail to Work with a Remote Filter.”

Configuring a Remote Filter on Windows


Follow these steps on the computer where the filter runs.
1. From the Start menu:
Windows NT – select Settings > Control Panel > Services
Windows 2000 – select Settings > Control Panel > Administrative Tools >
Services
2. Select the filter from the list of services.
Additionally, on Windows 2000, right-click on the filter and select Properties.
3. If the service is running, select Stop.
The service must be stopped to set new command-line options.
4. In the Startup Parameters field, add the new socket setting using the format -p
inet:port@host.
For example:
-h -l -p inet:8790@filterhost.pogonip.net
If you previously set custom command-line options (see Table 1-4), remember to add
them in the Startup Parameters text box. The -h and -l options shown in the
example are recommended.
5. Do not start the service again until after you change the socket setting in the
Administration Console.
See the next section, “Configuring sendmail to Work with a Remote Filter.”

Configuring sendmail to Work with a Remote Filter


This process applies to both Windows and UNIX.
1. From the Main menu, select the Edit Existing Configuration option.
2. If necessary, select the host or cluster to configure and then click the Select button.
Select the host or cluster with the sendmail MTA that should communicate with the
filter on a different computer.
3. Highlight an existing configuration or type a configuration in the text field and select
the Load button.

Sendmail® Flow Control Filter Administration Guide 9


Filter Options

The Advanced Configuration page opens.


4. Select Mail Filters from the Options menu.
The Mail Filters page opens.
5. In the Filter Equates field, change the existing S= setting to match the change you
made to the filter startup setting. For example:
S=inet:8790@filterhost.pogonip.net

Note – If you do not see an entry for the filter, you need to enable the filter first. See
“Enabling a Filter” on page 5.

6. Apply, save, and deploy your new configuration as usual.


You do not need to manually restart the filter after making these changes.
Redeploying the configuration is sufficient.
7. On the computer where the filter is installed, stop and then start the filter.
See “When to Start and Stop a Filter” on page 6.

Filter Options
Each filter has options that can be used to modify its behavior. In most cases, you will not need
to modify these options. However, advanced system administrators needing to change these
options may find this section useful.

Notes About Filter Options for UNIX and Windows


• On both UNIX and Windows, there is one mandatory command-line option, -p
socket. “Configuring a Filter to Run on a Remote Computer” on page 8 describes this
option in more detail. The -p socket must be provided, even if the filter and MTA run
on the same computer.
• The -l command-line option is enabled in the startup scripts by default.
• The filter will check for a valid license at startup time. If no valid license is present,
an error is reported and the program exits immediately. If a timed license is present
and -l is specified, the amount of time left on the license is logged.

Notes About Filter Options for UNIX


• To temporarily run a filter with custom options on UNIX, start the filter from a shell
prompt in the usual manner. However, you may wish to add your custom command-
line options in the startup script to make them permanent.
• You can shut down a filter with a SIGHUP, SIGINT, or SIGTERM signal. There is no
need to write to the disk, so no data corruption occurs.

10 Sendmail® Flow Control Filter Administration Guide


Chapter 1: Filter Configuration

Changing Filter Options


Follow these steps to add or change any of the options listed in Table 1-4. These steps describe
how to make the changes take effect each time the filter is started by changing the startup
scripts.

Overview of Changing Filter Options


Changing the options requires the following steps.
1. Change the startup script.
• UNIX – Edit the startup script listed in Table 1-4.
• Windows – Change Startup Parameters in the Service Manager.
2. Stop and start the filter.

Changing the Filter Options on UNIX Systems


1. Edit the startup script with an editor such as vi or Emacs.
Table 1-4 lists the names of the startup parameters.
2. Find the line in the startup script that sets the options.
The line will begin with:
if $INSTALLDIR/filter_name -p $SOCKETSPEC
3. Add new options at the end of the line, or change the existing options.
4. Save and exit the file.
5. Stop and restart the filter.
See “Starting and Stopping a Filter on UNIX Systems” on page 6.

Changing the Filter Options on Windows


1. Open the Service Manager window.
This is the applet in the control panel called Services.
2. Select the filter from the list of services.
On Windows 2000, right-click on the filter and select Properties.
3. If the service is running, select Stop.
The service must be stopped to set new command-line options.
4. In the Startup Parameters field, type the new option.
For example:
-h -l -p inet:8895@stickeen.johnmuir.net -r
If you previously set options, remember to add them in the Startup Parameters
field. The -h and -l options shown in the example are recommended.
When you type options in the Startup Parameters field in the Windows Service
Manager and select Start, the filter stores the options in a dedicated startup file as
listed in Table 1-4. When you select Start without typing anything in the Startup

Sendmail® Flow Control Filter Administration Guide 11


Changing Filter Options

Parameters field, the options previously supplied are read from the startup file. In
other words, when you type options into the Startup Parameters field, you
override the previously set options and store the new options.
5. Start the service.
The following table describes the options (also known as startup parameters) for this
Sendmail filter.

Table 1-4 Filter Options

Option Restrictions Description


-C configfile specifies the config file location; the default is
/etc/mail/flow-control.conf
-f UNIX only Normally the filter will start and then call fork() so that
the processing is done in the background and the command
exits immediately. This option prevents that behavior, and the
program runs in the foreground.
-h — Causes the filter to add a header to the message, indicating its
presence and successful passage of the message through it;
the header is X-Flow-Control, and the value of the header
will be the official product name of the filter followed by its
version number, the hostname and the envelope ID for the
message (provided by the MTA).
-l — Log filter activity to the usual Sendmail Switch log location.
The volume of data written by the filter is controlled by the
log level selected by your syslog configuration file
(UNIX) or by the log level setting in the Administration
Console (Windows). More information can be acquired by
recording in debug level, but info level is sufficient for
general operation.
-n Causes the filter to parse its log file for correctness and then
exit. If the file is readable and parses correctly, then the filter
exits with status EX_OK (0). Otherwise, it prints an error
message and exits with status EX_CONFIG (78).
-P pidfile — Specifies the file to which the filter should write its process
ID on startup; there is no default, meaning the process ID is
not written anywhere in the absence of this option.
-S Shuts down the filter when it is being managed by an
automatic restart service (see the AutoRestart
configuration file setting) or a pid file is defined (see the
PidFile configuration setting or the -P command line
flag)
-u userid UNIX only Create the child process as the specified userid rather than the
executing user. By default, this is set to smadmin in the
startup script.
-V — Print the filter version number — do not run the filter.

12 Sendmail® Flow Control Filter Administration Guide


Chapter 1: Filter Configuration

Filter File Names


The following table lists the files used by the filters.

File/Operating System Description


Executable The daemon or service that does the work.
PID storage file The filter process ID is written to this file.
UNIX startup script Contains options to use when starting a filter.
Configuration file Contains filter configuration information.
State file Defines the location to which Flow Control’s internal state should be
periodically written during normal operation, and from which state should
be read on initial startup.

Using Directory Servers in Flow Control Filter


As part of your Flow Control Filter configuration, you may use a directory server as a search
filter to check message recipients in a specific domain. The following sections include
examples for creating such search filters in Sendmail Messaging Directory, IPlanet, and Active
Directory.

Sendmail Messaging Directory Settings


Use the following default search filter for SMD 4.0 to check for all recipients in the domain
pogonip.net. A similar entry is listed in the default Flow Control Filter configuration file.
For more information, see the table entry “BadRecipient” on page 21.
A minimum configuration file would use:
LDAP-Query-Address *@pogonip.net
LDAP-URI ldapi:// ldap://localhost ldap://other-replica-server
<Class CheckAddress>
Host *
BadRecipient Reject
</Class>

Using Global LDAP Parameters


The following global LDAP parameters should be used:
LDAP-Query-Address *@pogonip.net
LDAP-URI ldapi:// ldap://localhost ldap://other-replica-server
The following global LDAP parameters can be used:
LDAP-Search-Template (&(objectClass=inetMailRecipient)(mailLocalAddress=%a))
LDAP-Unvailable TEMPFAIL

Checking Multiple Domains


LDAP-Query-Address can be used by a file containing a list of domains in the following
format:
*@pogonip.net

Sendmail® Flow Control Filter Administration Guide 13


Using Directory Servers in Flow Control Filter

IPlanet Settings
A single domain in Iplanet can use this minimum configuration file with BadRecipient for
the domain pogonip.net:
AutoRestart /var/sendmail/flow-control/restart.pid
ControlSocket inet:8898

LDAP-BaseDN-Template dc=pogonip,dc=net
LDAP-Query-Address *@pogonip.net
LDAP-Search-Template (mail=%a)
LDAP-Unavailable TEMPFAIL
LDAP-URI ldap://ldap.pogonip.net:389

<Class BadGuys>
Host *
BadRecipient REJECT
</Class>

Active Directory Settings


The following minimum settings apply in Active Directory for the domain pogonip.net:
ControlSocket inet:8898
LDAP-BaseDN-Template ou=qa,dc=pogonip,dc=nip
LDAP-Search-Bind-DN cn=admin test,ou=pogonip,dc=pogonip,dc=net
LDAP-Search-Bind-Password adminpw
LDAP-Query-Address *@example.com
LDAP-Search-Template proxyAddresses=SMTP:%a
LDAP-Unavailable TEMPFAIL
LDAP-URI ldap://activedirectory.example.com:389

<Class BadGuys>
Host *
BadRecipient REJECT
</Class>

14 Sendmail® Flow Control Filter Administration Guide


Working with the Flow Control Filter
Configuration File 2
The Flow Control Filter works with a configuration file (flow-control.conf). A default
version of this file is created during installation. See the Appendix in the Sendmail® Flow
Control Filter Getting Started Guide for more information about this default configuration file.
You also can create new versions of this file using the Sendmail Switch Administration
Console. You can create different classes and user limit specifications, and define parameters
within each class to better manage the flow of email in and out of your system.
Use a text editor to add a class or user limit to the configuration file. Then add the desired
parameters using the following formats for a class and a user limit.
A Class specifies limits to assert against remote MTAs on a per-connection basis. They use the
following syntax:
<Class name>
Class parameters
</Class>
A UserLimit specifies limits to assert against remote MTAs on a per-recipient basis. They use
the following syntax:
<UserLimit name>
UserLimit parameters
</UserLimit>
Global parameters, which are used to specify filter parameters that are used outside classes and
user limits, are listed one-per-line with no surrounding class tags.
See the Appendix in the Sendmail® Flow Control Filter Getting Started Guide for an example
of a flow-control.conf file.

Note – See Chapter 1, “Filter Configuration” for information on how to configure filters.

Creating the Flow Control Filter Configuration File


You need to set up a Flow Control Filter configuration file that defines how the incoming and
outgoing traffic flow will be handled. Examples follow these steps.
To create a configuration file:
1. After enabling the Flow Control Filter, click the Configure button.
2. Enter a class name and click the Add New Class button to create this class
definition.

Sendmail® Flow Control Filter Administration Guide 15


Creating the Flow Control Filter Configuration File

Each class name must be unique among the class definitions, and can consist of any
combination of ASCII letters, numbers, digits, and punctuation marks up to 256
characters in length. No spaces are permitted in class names. You can define any
number of classes.

Note – Class selection only happens on connection, and is not re-evaluated during
the connection, whether or not limits are reached.

3. Define the parameters needed for this class. See Table 2-1 Action Parameters on
page 17 for a list of Action definitions. See Table 2-2 Class Parameters on page 20
for class parameter definitions.
After each parameter is defined, click the Enter button. The Administration Console
updates the display for the class settings as each parameter is added.
4. If needed, use the Edit and Delete tools (located to the right of each parameter
shown on the Administration Console page) to change or remove parameter data.
5. Click OK to save these definitions.
To exit without saving the parameter definitions for a class, select Cancel.
6. Select Save to save this new class.
7. You must start the Flow Control Filter after you have enabled it.
Follow the steps for Flow Control Filter When to Start and Stop a Filter on page 6.

16 Sendmail® Flow Control Filter Administration Guide


Chapter 2: Working with the Flow Control Filter Configuration File

Flow Control Action Configuration Parameters


An Action configuration block specifies an action to be taken when a limit is exceeded by a
client. This is defined with the following syntax:
<Action actionname>
...
</Action>
Any number of actions can be defined. An actionname is unique among Action definitions
and consists of any combination of ASCII letters, numbers, digits or punctuation.
Within an Action definition are parameters and values which specify the action thus defined.
The supported settings and their permitted values are as follows:

Table 2-1 Action Parameters

Parameter Value Format Description


Block { False | True } Directs the filter to issue a block request to all firewalls
configured using global Firewall lines (see the Global
Settings and Firewall Control sections).

Note – Flow Control Filter checks only the first byte of the
Block value. If Flow Control finds T/t/Y/y/1, it accepts
the value as True. If Flow Control finds F/f/N/n/0, it
accepts the value as False.

BlockDuration seconds For actions in which Block is true, specifies the duration
of the TCP block request to be issued. The default duration is
300. See Global Flow Control Filter Parameters on page 26
and Firewall Control on page 40 for more information. Only
values between 1 and 31557600 (one year) are allowed.
BlockPort { name | number } For actions in which Block is true, specifies the TCP
ports for which inbound traffic should be blocked. The name
of the port or its number can be used; names will be looked
up in /etc/services. If no ports are listed, all ports will
be blocked. This line may appear multiple times if multiple
ports should be blocked. See Global Flow Control Filter
Parameters on page 26 and Firewall Control on page 40 for
more information.
DisableTime time Indicates that a class or userlimit which has triggered this
action is considered to be at its limit for the specified time
regardless of the time limit specified in the parameter which
was exceeded. For example, if Connections is set to
10/1h and this parameter is set to 6h, then more than 10
connections in one hour within the class will cause the class
to be limited for six hours. If time is lower than the time of
the rate that was hit (for example, if a rate limit of 10/1h is
reached and this parameter is set to 30m), this parameter has
no effect.

Sendmail® Flow Control Filter Administration Guide 17


Creating the Flow Control Filter Configuration File

Table 2-1 Action Parameters

Parameter Value Format Description


Message [ SMTP error [ ESC ]] Defines the error message to be returned whenever this
message Action is invoked. The message is required. It is also
possible to specify a standard SMTP error code as per
RFC821, and an Enhanced Status Code (ESC) as defined by
RFC1893. If no message is specified, the MTA default
response text message is will be used.

Note – If a new connection is made into an exceeded class,


although the message must be provided as required, it is not
reflected in the SMTP reply code returned to the client.

A new connection can be dropped by the MTA before


accepting any commands if the following conditions are met:
• The class to which the new connection belongs has
exceeded one of its limits.
• Response for that class is set to TEMPFAIL
• Message for that class is set to return an SMTP error code
of 421
Notify { False | True } Directs the filter to notify other filters that the client
triggering this limit should be blocked remotely as well. The
servers to receive this notification are selected using the
global Notify parameter. This parameter requires that a
DisableTime also be set to have any effect. For more
information, see Global Flow Control Filter Parameters on
page 26 and Remote Notifications on page 43 for more
information.
Response { ACCEPT | Selects the message disposition to be requested when this
DISCARD | action is selected.
QUARANTINE |
• ACCEPT accepts the message, but a log entry is still
REJECT |
generated indicating the limit was exceeded.
TEMPFAIL }
• DISCARD causes the server MTA to return a success
message to the client MTA and silently drop the message.
• QUARANTINE causes the server MTA to accept but
quarantine the message using the string specified by the
Message parameter if set, or an internally-provided
default otherwise.
• REJECT causes the server MTA to return a permanent
(SMTP 5xx) error message to the client MTA.
• TEMPFAIL causes the server MTA to return a temporary
(SMTP 4xx) error message to the client MTA.
The default is TEMPFAIL. See the Message setting above
for more information.

Default actions are built into the filter, named after each of the possible Response settings
listed above. You can reference, for example, an action called TEMPFAIL even if one is not
explicitly defined in the configuration file. The Message in each of the built-in definitions is
blank, meaning the MTA should apply its default string.

18 Sendmail® Flow Control Filter Administration Guide


Chapter 2: Working with the Flow Control Filter Configuration File

Flow Control Class Parameters


A Class configuration block defines a set of limits for clients that fit in that class. Within each
block, the limits are defined, as well as patterns which are matched against incoming
connections. Each client connection is associated with the first class whose definition matches
it. That client's inbound SMTP traffic is then subject to the limitations defined by that class.
Note that the choice of class for a given connect is not re-evaluated between envelopes. The
choice is made at connect time only.
A Class is defined with the following syntax:
<Class classname>
...
</Class>
Any number of classes can be defined. A classname is a name unique among Class
definitions and consists of any combination of ASCII letters, numbers, digits or punctuation.

Sendmail® Flow Control Filter Administration Guide 19


Creating the Flow Control Filter Configuration File

Within a Class definition are the matching specifications and the limit specifications
for that class. The supported settings and their permitted values are as follows.

Table 2-2 Class Parameters

Parameter Value Description


Action actionname Selects which action should be applied when a limit in this
class is exceeded. The default is TEMPFAIL. The
actionname specified must match either an action defined in
the configuration file or one of the internally-defined default
actions.
Aggregate True/False If True, the running totals for this class apply across all
hosts that fall within the class. If False each host within the
(Default: True)
class has individual totals and limits as defined within this
class.
For example, if the class applies to all hosts in domain
pogonip.net and connections arrive from hosts
a.pogonip.net and b.pogonip.net, then if this
feature is set to False, each host is counted as having made
one connection and the limits defined apply to each host
individually.
If this feature is set to True, the entire class is counted as
having made two connections and the limits defined apply to
the class-wide totals.
Applies timespec Specifies what time(s) of day(s) the limits of the class are in
effect. During other times, connections assigned to this class
are not subjected to any limitations. The timespec consists of
a comma-separated list of time specifications, which consist
of zero or more day specifications followed by a start time
and an optional hyphen and end time. The day specifications
are the first two characters of any day, or An for "any", or Wd
for "weekday". The times are of the form hhmm. If no day
specifications are provided, all days apply. If no time is
provided, all times apply on the given day(s). Specifying
time ranges that span day boundaries is permitted.
Examples:
Wd0900-1700 – Weekdays, 9 a.m.to 5 p.m.
SaSu,Wd0000-0859,Wd1701-2359 – The opposite;
weekdays before 9 a.m.and after 5 p.m., or any time on
Saturday and Sunday
Mo1700-0400 – Mondays after 5 p.m. and Tuesdays
before 4 a.m.
0000-1200 – All days until noon
The entire string can start with an exclamation mark ("!") to
indicate that the current time must not fall into the specified
time(s) in order for the class limits to apply.

20 Sendmail® Flow Control Filter Administration Guide


Chapter 2: Working with the Flow Control Filter Configuration File

Table 2-2 Class Parameters

Parameter Value Description


BadSender { DISCARD | Determines the action to be taken when a bad sender is
REJECT | detected. DISCARD accepts the sender at the SMTP level
TEMPFAIL} but discards the message rather than delivering it; REJECT
returns a "user unknown" error; TEMPFAIL returns a
temporary error code at the SMTP level. This requires the
LDAP settings (see below) to be present in the configuration
file. At a minimum, the LDAP-URI setting must be
defined. The default is to skip sender validation altogether.
BadRecipient {DISCARD | Determines the action to be taken when a bad recipient is
REJECT | detected. The action applies to that particular recipient, not
TEMPFAIL} to the entire message. DISCARD accepts the recipient at the
SMTP level but deletes that recipient before delivery;
(Default: REJECT)
REJECT returns a "user unknown" error; TEMPFAIL
returns a temporary error code at the SMTP level. This
requires the LDAP settings (see below) to be present in the
configuration file. At a minimum, the LDAP-URI setting
must be defined.
BadRecipients Limit/Time Specifies that no more than limit bad recipients can be tried
within the specified time. The time is assumed to be in
[action]
seconds unless terminated by a letter such as d (days), h
(No Default) (hours), or m (minutes). These can also be combined (such as
1d6h for one day and six hours).
This requires the LDAP settings (see below) to be present in
the configuration file. At a minimum, the LDAP-URI setting
must be defined.
Bounces Limit/Time Specifies that no more than limit bounce messages can be
received within the specified time. The time is as defined
[action]
above. A bounce message is one with an empty envelope
(No Default) sender address. If the additional action is specified, it names
the action to be taken when this limit is reached, overriding
whatever is specified on the Action line for the class being
defined.
Connections Limit/Time Specifies that no more than Limit connections can arrive
within the specified Time. Time is assumed to be in seconds
[action]
unless terminated by a letter such as d (days), h (hours), or m
(No Default) (minutes). These can also be combined (such as, 1d6h for
one day and six hours). This overrides whatever is specified
on the Action line for the class being defined.
Envelopes Limit/Time Specifies that no more than Limit distinct messages can
arrive within the specified Time. (Time is defined as shown
[action]
in the Connections description.) This overrides whatever
(No Default) is specified on the Action line for the class being defined.

Sendmail® Flow Control Filter Administration Guide 21


Creating the Flow Control Filter Configuration File

Table 2-2 Class Parameters

Parameter Value Description


Host hostname Defines a host which belongs in this class, in one of the
following forms:
.domain
hostname – matching a hostname exactly
ip-address
domain – matching a domain name
ip-block/mask
IP-address – matching a specific IP address
*
IP-block/mask – matching the specified CIDR block
(No Default)
* – all hosts
Multiple entries are allowed within a class definition to
accommodate multiple domains or addresses.
LimitAuth {True | False} If True, connections that authenticate to the MTA using the
(Default: True) SMTP AUTH command are subjected to the limits defined
for the class in which they fall. They are no different than
any other connection.
If False, authenticated connections are ignored by the
filter.
Classes for which LimitAuth is False are unable to
enforce any connection-time limits, which means:
• any Connections limit will be ignored.
• any MaxConnections limit will be ignored.
• any other exceeded limit will not cause connections to be
rejected, but will still block transactions on
unauthenticated connections.
The default is True.
MaxConnections Number Defines the maximum number of concurrent connections
allowed. A value of zero (or the absence of this parameter)
(No Default)
implies no connections will be allowed. If not defined, no
limit is imposed (in essence, the UNIX constant
ULONG_MAX will be used).
Recipients Limit/Time Specifies that no more than Limit distinct recipients can be
addressed within the specified Time. (Time is defined as
[action]
shown in the Connections description.)
(No Default)

22 Sendmail® Flow Control Filter Administration Guide


Chapter 2: Working with the Flow Control Filter Configuration File

Table 2-2 Class Parameters

Parameter Value Description


Reputation name Match only connections which have the reputation name.
The reputation of a connecting client is determined by
querying a reputation server and evaluating the result
contained in the reply to that query based on criteria
provided elsewhere. This line can appear more than once if
multiple reputations should be matched. See the IP
Reputation section for more information.
Senders Limit/Time Specifies that no more than Limit distinct senders are
allowed from hosts in this class within the specified Time.
[action]
(Time is defined as shown in the Connections
(No Default) description.)
Volume Limit/Time Specifies that no more than Limit bytes of message body can
be sent within the specified Time. (The Time is defined as
[action]
shown in the Connections description.) The Limit can be
(No Default) specified in larger units by ending the limit value with a k
(KB), m (MB), or g (GB).

Sendmail® Flow Control Filter Administration Guide 23


Creating the Flow Control Filter Configuration File

Flow Control Filter User Limit Parameters


Flow Control filter can be used to specify per-user rate limits. This is done in a similar fashion,
using a configuration block called UserLimit. These are specified in the same configuration
file.
A UserLimit is defined with the following syntax:
<UserLimit name>
parameters
</UserLimit>
The parameters and values allowed for UserLimit definitions are as follows:

Table 2-3 UserLimit Parameters

Parameter Value Format Description


Action actionname Selects which action, as defined in the Action section,
should be applied when the Rate specified is exceeded. The
default is TEMPFAIL. If the actionname specified does not
refer to a defined action, a warning will be logged and the
default will be used.
Aggregate { True | False } As with Class records, this indicates whether or not this
UserLimit definition covers all addresses which match the
(Default: True)
Sender and Recipient specifications.
If True, then one set of UserLimit counts is maintained
for all addresses or address pairs that match. If False, then
individual counts are maintained for all matches.
DisableRoll { True | False } If False, then once the rate limit has been reached, the
address is disabled for either the time portion of the Rate
(Default: False)
setting or the DisableTime setting, whichever is greater,
and no further tracking is done regarding that address match
until that time expires. If True, tracking continues even
though the limit has been reached.
For example, if these values are being used:
Rate 10/10m
DisableTime 60m
If False, once the rate limit is reached, the address will be
disabled for 60 minutes from the time of the eleventh hit on
this record within the initial 10 minutes (at time "T11"). Any
additional hits during that hour are not recorded. When time
T11+60m is reached, the counters and timers are all cleared
and start over.
If True, then additional hits during that hour are recorded. At
T11+60m the sliding window of hits is re-evaluated and
another 60m of DisableTime could begin almost
immediately if the flood which originally triggered the limit
has continued throughout the DisableTime interval.

24 Sendmail® Flow Control Filter Administration Guide


Chapter 2: Working with the Flow Control Filter Configuration File

Table 2-3 UserLimit Parameters

Parameter Value Format Description


LimitAuth { True | False } If True, messages whose clients have authenticated to the
MTA using the SMTP AUTH command (see RFC2554) are
Default: True
subjected to the limits defined for this UserLimit section; that
is, they are no different than any other clients' messages.
If False, messages authenticated connections are ignored by
the filter.
The default is True.
Rate lim / time Establishes a maximum hit rate for this record. When
exceeded, the filter will limit the flow of messages which hit
(No Default)
this record based on the time and other parameters.
Recipient pattern Match only messages for which a recipient matches the
(No Default) specification given here. Since there can be multiple
recipients on a message, multiple UserLimit records can
be hit by a single message.
If a Sender pattern is also present, the message's sender
must also match for the record to be hit. This line can appear
more than once in a definition to allow multiple recipient
patterns to count as a hit.
The wildcard character "*" is allowed, to represent zero or
more other characters (such as *@pogonip.net).
Sender pattern Match only messages for which the sender matches the
(No Default) specification given here. If a Recipient pattern is also
present, at least one of the message's recipients must also
match for the record to be hit. This line can appear more than
once in a definition to allow multiple sender patterns to count
as a hit.

Sendmail® Flow Control Filter Administration Guide 25


Creating the Flow Control Filter Configuration File

Global Flow Control Filter Parameters


The following settings can be made outside of a Class or UserLimit definition to enable
global settings for the filter. Among other things, this is where you would configure the LDAP
query features of the filter, for use when trying to detect recipient harvesting (see
BadRecipients above).

Table 2-4 Global Flow Control Filter Parameters

Parameter Value Format Description


AutoRestart Path Indicates that automatic filter restarting service
is desired, and gives a location for a temporary
(No Default)
file to be written where the master monitor
process ID will be stored. This must not be the
same as the PidFile setting.
AutoRestartRate Rate Specifies a limit on the rate of restarting when
AutoRestart is in use. The rate can either
be a number indicating a number of restarts
allowed before giving up and terminating
altogether, or a string of the form n/tu, where n
is a number of restarts, t is a number and u is a
corresponding unit of time ("s" for seconds,
"m" for minutes, "h" for hours, "d" for days)
and these together specify a maximum restart
rate which, if exceeded, causes the filter to give
up and terminate.
AddXHeader { True | False } Specifies whether or not an X-header should be
added to mail that passes through the filter. This
(Default: False)
is equivalent to specifying the -h command-
line flag.
ControlSocket Socketspec Defines the socket where the filter will listen
for connections for status queries, etc. using the
(No Default)
fc-query tool. The socketspec follows the
same format used for the -p command-line
option.
LDAP-Attributes String Defines the attributes to query for existence of
user records. There is no default.
Being able to query for an LDAP attribute
saves time and resources compared to a query
for all LDAP data, particularly when working
with non-sendmail directory servers which
return far more data than SMD replicas.
In addition, the proxy cache functions of
Sendmail Directory Server work only when an
explicit list of LDAP attributes is requested.
LDAP-AttributesOnly { True | False } Arranges that LDAP queries request only the
attribute names, not the values they contain.
This tuning parameter is included because some
caching LDAP proxies are impacted by the
nature of the query and the reply.

26 Sendmail® Flow Control Filter Administration Guide


Chapter 2: Working with the Flow Control Filter Configuration File

Table 2-4 Global Flow Control Filter Parameters

Parameter Value Format Description


LDAP-BaseDN-Template String Defines the base DN template for LDAP
queries.
(Default: [empty
string])
LDAP-Query-Address { path | user@host } Specifies that an LDAP query should only be
issued for recipient addresses that match the
(No Default)
user@host specification given here.
Standard wildcards are available, so
*@pogonip.net would be valid. If
unspecified, an LDAP query is issued for all
recipients. This line may appear in the
configuration file more than once to specify
multiple recipient patterns that should be
queried. You may also specify a negation by
preceding an entry with "!". For example:
LDAP-Query-Address *.net
LDAP-Query-Address
!*.pogonip.net
This queries all addresses ending in .net,
except those ending in .pogonip.net.
If the value of this parameter appears instead to
be a path to a file (for example, starting with a
"/" character), that file will be opened and its
contents read in as a list of patterns to be
queried in the same format as described above.
For example, if the file contains:
*.pogonip.net
*.sendmail.com
this would be the same as saying:
LDAP-Query-Address
*.pogonip.net
LDAP-Query-Address
*.sendmail.com
In that file, the hash ("#") character denotes the
beginning of a comment. This character and
any after it on a given line of the file is ignored.
Also, any line in the file which does not contain
the "@" character is assumed to be a domain
name only, and will have the "*@" added as a
prefix to match all users in that domain.
Changes to such files are not automatically
picked up by the filter until its configuration
file is re-read.

Sendmail® Flow Control Filter Administration Guide 27


Creating the Flow Control Filter Configuration File

Table 2-4 Global Flow Control Filter Parameters

Parameter Value Format Description


LDAP-Rebind-Period Seconds Specifies that an LDAP connection to a
secondary choice LDAP server should try to re-
(Default: 120)
bind to the primary (or a higher-preference)
server at the specified interval.
LDAP-Search-Bind-DN String Specifies the LDAP DN to which new
connections should try to bind when first
(No Default)
connecting to the LDAP server.
LDAP-Search-Bind-Password String Specifies the LDAP password with which new
connections should try to bind when first
(No Default)
connecting to the LDAP server.
LDAP-Search-Template String Specifies a template for the LDAP queries to be
used to validate recipients when trying to apply
(Default:
a BadRecipients restriction to a class.
mailLocalAddress
Three special tokens are replaced in the
=%a)
template as follows when the LDAP query is
actually issued:
%a – The full recipient address as specified in
the envelope.
%e – The "exploded" envelope recipient
hostname in an LDAP query format; if the
value of %h is example.com, this token
would produce
dc=example,dc=com.
%h – The envelope recipient's hostname, or the
empty string if there was no hostname.
%u – The userid portion of the envelope
recipient.
LDAP-Timeout String Specifies the LDAP timeout for queries to the
LDAP server. LDAP queries which are not
(Default: 10)
served within this period of time will be aborted
and the message arriving will be temp-failed.
LDAP-TLS String Specifies whether or not LDAP connections
should use TLS to secure the connection. The
(Default: no)
string should be one of the following:
• no – do not try to secure the connection with
TLS (default).
• yes – try to secure the connection with TLS,
but continue if this is not possible.
• required – try to secure the connection,
and return an error if TLS could not be
negotiated.
LDAP-TLS-Randfile String Specifies the path to use to get random data for
cryptographic operations.
(No Default)
On Linux, this defaults to /dev/urandom;
elsewhere, there is no default so this is a
mandatory setting if TLS service is desired.

28 Sendmail® Flow Control Filter Administration Guide


Chapter 2: Working with the Flow Control Filter Configuration File

Table 2-4 Global Flow Control Filter Parameters

Parameter Value Format Description


LDAP-TLS-Require-Cert String Specifies how strong certificate requirements
are for TLS support in LDAP operations. Valid
values are:
• allow – The server certificate is requested.
If no certificate is provided, the session
proceeds normally. If a bad certificate is
provided, it will be ignored and the session
proceeds normally.
• demand – The server certificate is
requested. If no certificate is provided, or a
bad certificate is provided, the session is
immediately terminated.
• hard – (See demand.)
• never –The client will not request or check
any server certificate.
• try – The server certificate is requested. If
no certificate is provided, the session
proceeds normally. If a bad certificate is
provided, the session is immediately
terminated.
If an unrecognized value or no value is given,
allow is assumed. See Managing Memory
Footprint on page 35 for more information.
LDAP-Unavailable String Specifies the action to take if LDAP service
was not available at the time of the attempted
(Default: TEMPFAIL)
query. This must be one of the following:
ACCEPT – accept the message.
DISCARD – accept but silently discard the
message.
REJECT – reject the message with a permanent
(5xx) error code.
TEMPFAIL – reject the message with a
temporary (4xx) error code, inviting the
sending MTA to try again later.

Sendmail® Flow Control Filter Administration Guide 29


Creating the Flow Control Filter Configuration File

Table 2-4 Global Flow Control Filter Parameters

Parameter Value Format Description


LDAP-URI URL Specifies the URL of an LDAP connection that
should be attempted to resolve LDAP queries.
(No Default)
This can be specified multiple times to define a
primary server and backup servers. Order
matters, so the first connection is the primary
one, and others are listed in decreasing order of
preference. If the primary is not available, the
connections will be attempted down the list
until a connection can be made or the list is
exhausted. Subject to the LDAP-Rebind-
Period setting, the filter will try to connect
to higher-preference LDAP servers from time
to time. At least one server must be defined for
LDAP queries to take place and for
BadRecipient, BadRecipients and
BadSender to be enforced.
ListenQueue n Requests from the kernel a listen queue on the
socket specified by the -p command-line flag
(No Default)
of size n. If not defined, the kernel default will
be used. See the man page for listen(2) for
details.
Log { True | False } Specifies whether or not logging should be
done. This is equivalent to specifying the -l
(Default: False)
command-line flag.
MaxTracking Number Defines the maximum number of hosts that will
be tracked across all classes for which
(Default: 0)
Aggregate is set to False. A value of 0 (or
the absence of this parameter) implies no limit.
MaxUser Number Defines the maximum number of user limits
Tracking that will be tracked across all user limits for
(Default: 0)
which Aggregate is set to False. A value
of 0 (or the absence of this parameter) implies
no limit.

30 Sendmail® Flow Control Filter Administration Guide


Chapter 2: Working with the Flow Control Filter Configuration File

Table 2-4 Global Flow Control Filter Parameters

Parameter Value Format Description


Notify host[/aliases]: Specifies another host on which the filter is
port:flags:password running and to which "at-limit" notification
messages should be sent when a class reaches a
limit.
The host may be either a hostname or an IP
address. If specified, the alias is a comma-
separated list of machine names used as
alternate names for the host being defined, but
only to determine if the line refers to the local
machine.
The port specifies the port to which the
message should be sent. The flags parameter is
a string, a concatenation of characters
representing options:
s send - this server should send notifications
to the host being defined
r receive - this server should accept
notifications from the host being defined
l - This line defines the listening port for the
local host. The password is used as part of the
encryption of messages between hosts.
If host or aliases contains the name of the local
host as returned by the gethostname()
function, the line is used only to determine on
which port the filter will listen for notifications
from other hosts. Multiple instances of this line
may be present to add multiple servers. For
more information, see Remote Notifications on
page 43.
PidFile Path Defines the location to which the filter should
write its process ID on startup. This is
(No Default)
equivalent to specifying the -P command-line
flag.
PlusDetail { True | False } Indicates whether or not, on LDAP-related or
other per-user actions, the filter should strip any
(Default: False)
"plus detail" before processing. This meta-data
is used for mail sorting and tagging in a way
supported by the sendmail MTA. If true,
user and user+something are
functionally identical for all per-user totals and
other actions, for any value of something.

Sendmail® Flow Control Filter Administration Guide 31


Creating the Flow Control Filter Configuration File

Table 2-4 Global Flow Control Filter Parameters

Parameter Value Format Description


Reputation host:port Specifies the location of a reputation server. In
Server Flow Control Filter 2.0, only Commtouch
reputation services are supported. The host can
be either a hostname or an IP address.
The available reputation servers are the servers
where ctIPd has been installed.
The port must also be provided as there is no
default. This line can appear more than once in
the configuration if multiple servers should be
queried; in that case, they are queried in a
round-robin pattern.
Reputation Seconds Specifies the time the filter will wait for a reply
Timeout from a reputation server before giving up and
(Default: 5)
returning an error.
Reputation String Specifies the action to be taken when a timeout
Unavailable or other error occurs when attempting to query
Default:
a reputation service. The format and semantics
TEMPFAIL
for the string is the same as those for the
LDAP-Unavailable setting above, except
that DISCARD is not a valid setting.
RunAsUser Userid (UNIX only) Defines the userid to which the
filter will attempt to switch when started. For
(No Default)
this to work, the filter must be started as the
superuser. Changes to this setting are ignored
when the file is reloaded automatically;
activating a change to this setting requires a
restart of the filter. This is equivalent to the
command-line -u flag.

32 Sendmail® Flow Control Filter Administration Guide


Chapter 2: Working with the Flow Control Filter Configuration File

Table 2-4 Global Flow Control Filter Parameters

Parameter Value Format Description


StateFile Filename Defines the location to which internal state
should be periodically written during normal
operation, and from which state should be read
on initial startup.
Failures of state read/write are never fatal; that
is, a failure to write state results in an error
being logged but no interruption in operation,
and a failure to read state will cause an error to
be logged but the filter will contain no or partial
state from the previous execution.
There is no default. If no state file is specified,
then no state will be read during startup or
written during normal operation.
The current connection count, such as, the data
supporting MaxConnections, is not retained
during state file reloads since there is no way to
verify that the count is accurate.
StateInterval Seconds Specifies the minimum interval between writes
of internal state to the file specified in the
Default: 0
StateFile parameter above. Dumps of state
information are not made when the filter is
inactive. A value of 0 causes no state saving
except when the filter is performing a
controlled shutdown.

Note – Take care when selecting this interval.


Since the thread which saves state must be able
to generate a consistent snapshot of the
accumulated data, all other threads are locked
out during the state save operation. If the filter
has accumulated a particularly large amount of
data, and/or the disk to which the data is being
saved is especially busy, a state save could take
a period of time large enough to interfere with
the flow of mail through the system. This will
be exhibited by timeouts reported in the MTA
and possibly bounced or rejected messages
(depending on MTA configuration).

See Managing Memory Footprint on page 35


for more information.

Sendmail® Flow Control Filter Administration Guide 33


Creating the Flow Control Filter Configuration File

Table 2-4 Global Flow Control Filter Parameters

Parameter Value Format Description


WarnAt Percentage Defines the percentage to which any rate limit
must be met before a warning will be logged.
(No Default)
For example, a setting of 80 will cause a
warning to be logged whenever any defined
rate count for a given class has reached 80% of
its limit. The default is 0, meaning no warning
is ever logged. The warning is logged only once
per class, until the time on the exceeded limit is
reached. Therefore, if a rate of 10/1h is
defined, then the warning will not be reported
more than once per hour since it will take that
long for the limit to be reset once it has been
reached. The value percentage must be between
0 and 100.

34 Sendmail® Flow Control Filter Administration Guide


Chapter 2: Working with the Flow Control Filter Configuration File

Managing Memory Footprint


During configuration file construction, it is important to consider the volume of data that will
accumulate inside the filter process over time.
For each separate host to be tracked (especially with a Class for which Aggregate is set to
false, in which case separate tracking is done for each host in the class), a small block of
memory is allocated to contain the running totals and event timestamps for that host. The
memory must grow to contain enough data to evaluate each limit being tracked for that host.
For example, if a setting of Envelopes 1000/1h is used, the filter must remember the most
recent 1000 timestamps (four bytes each) for envelopes from each host being tracked.
If many hosts are being tracked or many limits are being evaluated on a per-host basis, the
volume of data the filter has to maintain in order to evaluate limits can become very large. This
can impact system performance overall as the process becomes very large, and can also cause a
StateFile save to take enough time to cause mail flow interruption or enough space to fill a
disk or quota.
When working with time-based limits, the count is of interest rather than the time range. For
example, the same amount of memory is consumed to monitor Envelopes 1000/1h as to
monitor Envelopes 1000/24h because 1000 timestamps have to be tracked in either case.
One way to conserve memory is to perform some common-factoring. For example, a limit of
6000/10h is essentially (but not exactly) the same as 600/1h or 100/10m or 10/1m; clearly
each of these is less space-expensive than the previous.
In addition, judicious use of the MaxTracking and MaxUserTracking settings is highly
advisable. These establish a "least-recently used" data structure which will purge older data to
make room for newer data and establish a partial cap on memory used. One should choose
values which are not too small to hamper useful host tracking, but also not too large to allow
excessive growth of the memory used by the filter.

Working with LDAP Certificates


If LDAP-TLS-Require-Cert is set to require or attempt to use certificates when querying the
LDAP server, some configuration is required on the client side.
The /etc/mail/flow-control/openldap/ldap.conf file is created during installation
with some default values. If certificates are to be used on the connection between Flow Control
Filter and the LDAP server, the value of TLS_CACERTFILE should be set to the path of the file
containing the client-side copy of the LDAP server certificate.

Sendmail® Flow Control Filter Administration Guide 35


Updating the Configuration File

Updating the Configuration File


The configuration file is read when the filter is started, or upon a new connection if the
configuration file has been updated since it was last read. When a new configuration file is
detected, all current Class and Userlimit definitions are updated from the new file. The
host-specific totals remain for both Classes and UserLimits.
The following example displays a sample configuration file with a MaxConnections setting
of 10:
<Class foo>
Host *
MaxConnections 10
Aggregate False
</Class>
If 10 connections arrive from the host pancakes.pogonip.net, this causes a child record to
be created specifically for that host. The child record is at its MaxConnections limit of 10.
If the following new configuration file is loaded:
<Class foo>
Host *
MaxConnections 15
Aggregate False
</Class>
then the host pancakes.pogonip.net can make only five more connections once the new
configuration takes effect.
In this case, the relationship is also controlled by class name (foo) and not by the Host
definition of the class. If the class name changes or is removed, the data stored for the host
pancakes.pogonip.net would be orphaned and discarded. The next connection from this
host might fall into a newly-defined classes, but current data is not moved to another class.
This same rules apply to UserLimit definitions. In addition, LDAP settings are reloaded.
Some settings which are not reloaded when the configuration file changes:
• AutoRestart
• AutoRestartRate
• Log
• AddXHeader
• ControlSocket
• PidFile
• ListenQueue
• ReputationServer
• Notify
The AutoRestart and AutoRestartRate settings are not updated unless the filter is
terminated and restarted as only the parent process (which actually performs the auto-restart),
ever reads them.

36 Sendmail® Flow Control Filter Administration Guide


Chapter 2: Working with the Flow Control Filter Configuration File

Editing and Changing the Order of Classes


After class name and parameter information have been set, the Administration Console
provides Edit, Up, Down, and Delete buttons for each defined class. Use these buttons to
edit settings and change the order of the classes. Class order within a configuration is
important (see Flow Control Filter Usage Notes on page 46).
To edit class information, perform the following steps.
1. Find the class that you need to change and click its associated Edit button.
For this example, we will edit the <Class Other> class. The Administration
Console displays the parameters for the class (in this case, Aggregate, Host, and
Connections are displayed).
2. Select Connections from the drop-down list.
3. Press Enter.
4. Raise the limit of connections to 300 per day (d) and press Enter.
5. Click OK.
6. Review the changes you made to <Class Other> and if they are acceptable, click
the Save button.
To change the order of classes, perform the following step.
• Click the Up or Down button associated with a particular class as many times as
needed to put the class in the desired order within multiple classes.
To delete a class, perform the following step.
• Click the Delete button associated with a particular class.
The class is deleted.

Sendmail® Flow Control Filter Administration Guide 37


IP Reputation

IP Reputation
Flow Control Filter can query a Commtouch IP reputation server to determine the risk
associated with accepting traffic from a particular IP address. To use this feature, you must
define a list of servers to be queried and a set of reputations that map reputation names onto
properties reported by the service.

Reputation Servers
To define a UDP-based reputation server, add a global ReputationServer line to the
configuration file. Its format is described in Table 2-8 on page 26. At least one server must be
defined for this service to be usable. If you installed ctIPd only on the local machine, a list of
reputation servers would include only the localhost entry
The available reputation servers are the servers where ctIPd has been installed.
These lines should define the location of one or more ctIPd daemons that can be queried by
the filter. These local daemons relay requests to the Commtouch data center, not a Commtouch
machine address.

Reputation Definitions
To define a reputation, add a Reputation subsection. At least one reputation must be defined
for this service to be active. This subsection defines a set of properties to test and a name which
will be the reputation assigned to connections that meet the list of tests.
The Commtouch IP reputation response contains a list of 12 properties, each of which can be
evaluated when selecting a reputation. See the Commtouch API documentation for more
information. The Reputation subsection specifies a list of tests to be performed on those
properties, and the results indicate which reputation matches the response from the server.
In general, the subsection uses the following format:
<Reputation name>
If parameter test value [& ...]
[...]
</Reputation>
The If line defines a list of logical tests, separated by ampersands (&), to apply to the result of
the reputation query. This means the reputation name will be applied to a new IP address if all
of the logical tests defined on any given If line match.
Any subsection can contain any number (not zero) of If lines, and any If line can contain any
number of logical tests to perform.
The value is an integer to be compared to the parameter for integers, or a string to be compared
(case-insensitive) for strings. The possible test values are:

= equal
! not equal
< less than (same as "!" for strings)
> greater than (same as "!" for strings)

38 Sendmail® Flow Control Filter Administration Guide


Chapter 2: Working with the Flow Control Filter Configuration File

The possible parameter values are in the following table. See the Commtouch reputation API
for a more detailed description:

Table 2-5 Reputation Parameters

Parameter Value Description


bulk [0, 100] integer Calculated daily average of the bulk mail in the last 30 days, with 0
being a source having no monitored traffic
ip-class string Commtouch-defined class:
R1-R9: Sources with substantial volume history. For example, R1
is a source that was monitored over time with high volume and low
risk and R9 would be a source with high volume and high risk.
T1-T5: Sources with transient volume or no volume history. For
example, T1 is a source with low transient volume and low risk
and T5 would be low transient volume and high risk.
G1-G3: Sources for which there are fixed decisions regardless of
their monitored volume; G1 is a whitelisted source, G2 is a
blacklisted source, and G3 is a private IP source.
risk [0, 100] integer Risk level; 0 indicates a fully trusted (for example, whitelisted)
host, and 100 indicates the maximum level of distrust (for
example, blacklisted).
spam1 [0, 100] integer Recent peak; indicates the deviation of the "recent spam" ratio
from the approximated hourly peak calculated from the daily
average over the last 30 days, expressed as a percentage.
spam2 [0, 100] integer Calculated daily average of the last 30 days, with 0 being a source
having no monitored traffic.
vol1 [-100, ...] Recent peak; indicates the deviation of the recent volume ratio
integer from the approximated hourly peak calculated from the daily
average over the last 30 days, expressed as a percentage.
vol2 [0, 100] integer Calculated daily average of the last 30 days, with 0 being a source
having no monitored traffic.
vol3 [0, 100] Standard deviation of the last 24 hours from the daily average.

For example:
<Reputation spammer>
If spam1 > 10 & spam2 > 30
If risk > 35
</Reputation>
This declares a reputation called spammer which will match a new connection if either of these
are true:
• spam1 is greater than 10 and spam2 is greater than 30
• risk is greater than 35
Then declaring the following would limit connections classified as spammers to have
constrained resources while other connections have more liberal access:
<Class spammer>
Host *

Sendmail® Flow Control Filter Administration Guide 39


Firewall Control

Reputation spammer
MaxConnections 1
Envelopes 2/30m
</Class>

<Class normal>
Host *
MaxConnections 100
</Class>
Reputation definitions are evaluated in the order in which they are found in the configuration
file.

Configuring Reputation Services


Some care must be taken when working with reputation services.
A properly configured reputation service includes one or more defined ReputationServers,
Reputation definitions, and defined Classes that use these components.
A Reputation definition without a ReputationServer causes all connections to fire the
ReputationUnavailable setting. This error is triggered because Flow Control Filter has
been directed to obtain the reputation of all connecting traffic in order to do perform proper
class assignments, but this has been made impossible by not defining any servers to query.
If a Class contains a Reputation line without a Reputation definition, the class matches
nothing. While this configuration is not rejected by Flow Control Filter, it can lead to
unintentional misclassifications of connections.

Reputation Server Errors


If a reply to a reputation query returns an error of some kind from either the Commtouch data
center or from ctIPd itself, this is reported by the filter in the log and the
ReputationUnavailable action will be applied to the connection using the following
format:
reputation query failed for x.x.x.x
reply from reputation server for query `x.x.x.x': Center is not operational
The text of this message is not generated locally, but is instead logged exactly as it was
delivered to the filter. If these errors persist, contact Sendmail Technical Support.

Firewall Control
Flow Control Filter can issue requests to firewalls to block traffic from an IP address whose
traffic causes a limit to be exceeded.
To define an IP block, use either of the following formats (the 10. net is an example).
• 10.0.0.0/8 (full IP address followed by number of network bits)
• 10.0.0.0/255.0.0.0 (full IP address followed by full netmask)
Follow these steps to use this feature:

40 Sendmail® Flow Control Filter Administration Guide


Chapter 2: Working with the Flow Control Filter Configuration File

1. Add one or more Firewall lines identifying the locations of SnortSam agents set up
to control firewalls.
2. Install and configure SnortSam agents (see the next section, About the SnortSam
Agent) positioned to control the firewalls of interest. If the firewall is a UNIX-based
machine such as a Sendmail Sentrion using iptables, the agent must be on the
machine providing firewall service. Otherwise, the agent must be installed and run on
any machine from which the firewall will accept commands.
3. Set Block to true in an Action definition, then request that action inside a Class
or UserLimit definition.
When such an action is triggered, the filter contacts each configured SnortSam agent and
issues a block request. The duration of the block is based on the action's BlockDuration
setting, and the block is cleared automatically by the SnortSam agent after the requested time.
Use of the BlockPort feature is currently limited to Sentrion servers. There is no way to
check what firewall is in use from within the filter, so there is no error if BlockPort is used
with CheckPoint or Cisco products. Those products will either ignore such requests altogether
(CheckPoint), or discard the port information and block all ports (Cisco).

About the SnortSam Agent


The SnortSam agent must be installed and configured for this service to be available.
SnortSam is a plugin for Snort, an open-source light-weight Intrusion Detection System. The
plugin allows for automated blocking of IP addresses on firewalls. The SnortSam agent is an
open-source component, installed in the following directory:
<install_dir>/smflow-2.0/sbin/snortsam
The filter cannot start or accept a new configuration if a Firewall line refers to a nonexistent
host, or one where the SnortSam agent cannot be reached.
SnortSam agent documentation contains additional information on running the agent. The
most current set is maintained at www.snortsam.net.

Sentrion Changes Affect Firewall Rules


Applying changes to the Firewall page in the Sentrion v2.0 user interface will erase Flow-
Control firewall blocks rules, as well as the blocks for its associated hosts.

Recipient Harvesting
Flow Control Filter can be used as an anti-spam measure to moderate recipient harvesting. In
this attack, an SMTP client connects to an SMTP servers, offers false information for the
HELO/EHLO and MAIL commands, and begins a dictionary or brute-force attack of RCPT
commands in an attempt to determine which addresses are valid on the server. SMTP servers
generally respond to these queries with accuracy to reduce the amount of queueing of bad
recipients, thereby revealing which addresses on the server are valid.
Flow Control Filter can be set to query a specified LDAP server to check the validity of
recipients as they are provided by the SMTP client. If a large number of bad recipients are
attempted and the BadRecipients setting is active, further RCPT commands issued within
that connection class will fail even if they refer to valid users. The client connection will not be
dropped, but no further LDAP queries will be performed. This continues for all connections in

Sendmail® Flow Control Filter Administration Guide 41


Rejecting Connections

the class until the time limit specified by BadRecipients (or the extended timeout specified
by DisableTime) is reached. New connections in the same connection class will still be
accepted, but all SMTP commands other than HELP, QUIT, RSET and NOOP will be rejected.

Rejecting Connections
An obvious optimization to filtering of unwanted flow is to reject the connection rather than
waiting to reject specific transactions. This prevents the MTA from creating a useless
subprocess that only rejects commands from the client until the client disconnects. However,
the creation of the subprocess still consumes resources. If possible, the connection should not
be allowed.
If a class is defined such that its Response is set to TEMPFAIL and the Message is set with an
SMTP reply code of 421, then a new connection arriving in a class already at its limit will be
dropped by the MTA with the selected reply code and no subprocess will persist. In any other
instance, the connection will still be allowed and a subprocess will be created, but no mail-
related commands will be permitted by the MTA and the subprocess will persist until the client
disconnects or times out.

Note – In some open-source MTA versions (for example, v. 8.10.x through 8.12.x), this
requires an active FFR (_FFR_MILTER_421).

The following class definition example accomplishes this task:


<Action DROP>
Message 421 too many connections
Response TEMPFAIL
</Action>
<Class Sendmail>
Host .sendmail.com
</Class>

<Class AOL>
Host *.aol.com
Recipients 10/1d
</Class>

<Class Others>
Aggregate True
Host *
Connections 250/1d
Action DROP
</Class>

42 Sendmail® Flow Control Filter Administration Guide


Chapter 2: Working with the Flow Control Filter Configuration File

Remote Notifications
Separate instances of Flow Control Filter can notify each other when a class has reached its
limit.
Add the Notify global lines to the configuration file to do so, listing each host exchanging
notifications with the local host on its own Notify line. The line must contain:
• Hostname of the remote server.
• Flags indicating whether the local server sends to the remote server or vice-versa (or
both).
• Password for that relationship. The passwords must be the same for both the sender
and the receiver, but they can differ between different senders and receivers.
Add Action definitions with a Notify setting of True. Activating these actions enables
notifications to be sent. You must also specify a DisableTime.
Notification for UserLimits are not supported.
For simple and lightweight operation, the notifications are sent using UDP (User Datagram
Protocol). This is not as reliable as TCP, but is more of a lightweight operation on busy
systems. However, requests can get lost during times of network congestion. UDP is delivered
on a best-effort basis only and is discarded by kernels and routers when insufficient capacity
exists to process it. Should this occur, notifications may not be received. If a log message
indicating a problem with sequence numbers is discovered, the likely cause is a previous
request that was discarded.
Example 1
Notify bsd.xyz-lab.pogonip.net:1234:rs:bl1ngbl1ng
Notify linux.xyz-lab.pogonip.net:1234:rs:bl1ngbl1ng
This establishes a data exchange between the machines bsd.xyz-lab.pogonip.net and
linux.xyz-lab.pogonip.net. Both have an r flag and are configured to receive, so they
will establish listening sockets on port 1234 to accept requests. Since both have an s flag, both
know they must send notifications to each other. The passwords must be the same in this case.
Example 2
Notify server.pogonip.net:1234:r:bl1ngbl1ng
Notify mirror1.pogonip.net:1234:s:bl1ngbl1ng
Notify mirror2.pogonip.net:1234:s:bl1ngbl1ng
This establishes a data distribution hierarchy. Since the mirrors have s flags,
server.pogonip.net knows it must send to the mirror servers. However, since
server.pogonip.net does not have an s flag, the mirrors will not send to the server. Since
server.pogonip.net has an r flag, the mirrors know they must accept messages from the
server. The mirrors see each other with s flags (send to), but not r flags (receive from), so they
will not accept messages from each other.

Note – Transmission of UserLimit rate-exceeded events is not supported in this feature.

Sendmail® Flow Control Filter Administration Guide 43


Milter Short-Circuits

Milter Short-Circuits
In certain configurations, some event counters can seem inaccurate. The most common
instance displays counters lower than where they should be when a Response of ACCEPT is
applied and an accepted message is not counted against the host delivering it. When the
Response is set to REJECT or TEMPFAIL, it makes sense not to update the counters since the
message is ultimately rejected.
The milter interface optimizes its traffic whenever possible. When a new message begins to
arrive (for example, when the MAIL FROM SMTP command is received), the filter checks to
see if the connection issuing that command has exceeded any of its limits. If so, the selected
Response value is sent back to the MTA. This causes the MTA to immediately act on that
message. The remainder of the envelope, along with the message's headers and body, are not
passed to the filter. Since it is at the end of the message body that the host is charged for its
message activity (one envelope, the unique sender and recipients, the volume, etc.) but that
information will not be communicated, it will appear internally as if the message was never
sent even though it was received and accepted by the MTA.

fc-query
A command-line client is provided to enable easy querying of the statistics stored by Flow
Control Filter.
The provided query client, fc-query, by default will query the filter and return all stored
classes, their configured limits, and current consumption. You may optionally specify on the
command line a comma-separated list of classes which are of interest. Matching on names of
classes is case-insensitive. The following command-line switches are also supported.

Table 2-6 Command-line switches

Class Description
-A Displays all classes and user limits.
-a Report all classes; this is the default.
-C socket Selects the location of the control socket to be queried; the default is
local:/var/sendmail/flow-control/fc-query.sock
-c Report only cloned classes and user limits; these are classes which were
made by a hit on a class that is not aggregating, which therefore caused a
copy of a class definition to be made.
-l Report only limited classes and user limits, such as classes and user limits
that have hit at least one limit.
-N num Report only the first num results returned by the server; the default is 10.
-n Return only classes or user limits named on the command line.
-r Request a raw output format allowing the output to be formatted or collated
as desired by other tools.
-u Limit report to user limits only.
-w Report only classes and user limits that have reached the warning threshold
for one of its limits, as defined by the global WarnAt setting.

Examples:
To report on all classes:

44 Sendmail® Flow Control Filter Administration Guide


Chapter 2: Working with the Flow Control Filter Configuration File

# ./fc-query
3 replies received, 3 available
Class "SecondClass":
Current connections: 0 (max 4294967295)
Envelope rate: 0 (max 2, time 5m)
Class "test5.test-domain.com":
IP addr = 10.211.4.115
Parent class "SecondClass"
Current connections: 0 (max 4294967295)
Envelope rate: 0 (max 2, time 5m)
Class "test6.test-domain.com":
IP addr = 10.211.4.89
Parent class "SecondClass"
Current connections: 0 (max 4294967295)
Envelope rate: 0 (max 2, time 5m)
The following examples use the -u flag to report on various user limits. To report on classes
instead, leave off the -u flag.
To report on all User Limits:
# ./fc-query -u
3 replies received, 3 available
UserLimit "MAILSERVER":
Rate: 0 (max 1, time 60s)
UserLimit "Spostmaster@pogonip.net:Rtest@mailserver":
Rate: 0 (max 1, time 60s)
UserLimit "Sfoo@bar.com:Ruser@testserver":
Rate: 0 (max 1, time 60s)
To report on all cloned user limits:
# ./fc-query -c -u
2 replies received, 2 available
UserLimit "Stest@pogonip.net:Rmail@server":
Rate: 0 (max 1, time 60s)
UserLimit "Smail@pogonip.net:Rpostmaster@mailserver":
Rate: 0 (max 1, time 60s)
To report on only the user limits named on the command line.
# ./fc-query -n -u "Smail@pogonip.net:Rmail@mailserver"
1 reply received, 1 available
UserLimit "Smail@pogonip.net:Rmail@mailserver":
Rate: 0 (max 1, time 60s)
To report on user limits that have reached at least one limit:
# ./fc-query -l -u
1 reply received, 1 available

Sendmail® Flow Control Filter Administration Guide 45


Flow Control Filter Usage Notes

UserLimit "Smail@pogonip.net:Rmail@mailserver":
Rate: 0 (max 1, time 60s)
To report user limits that have reached the warning threshold:
# ./fc-query -u -w
1 reply received, 1 available
UserLimit "mailserver":
Aggregate
Disable time 60s
Rate: 1 (max 2, time 60s)

Flow Control Filter Usage Notes


• The order within a configuration is significant. For example, if an incoming
connection matches more than one class definition, the matching class definition that
displays first will be the one selected.
• The absence of any limit in a class suggests that criteria will not be used to limit the
flow for that class. The absence of all of the limits in a class suggests that hosts in that
class may send mail to the server MTA without bound.
• If an incoming connection applies to no classes defined in the file, arriving messages
are delivered normally.
• The filter does not distinguish between the multiple MTAs when recording its totals.
So when defining a class or classes in systems with multiple MTAs, set the limits
accordingly. Likewise, when reading reports from such systems, be mindful that Flow
Control Filter information will not be broken down by individual MTAs.

46 Sendmail® Flow Control Filter Administration Guide


Troubleshooting 3
This chapter helps you diagnose and solve some common filter problems.

Using Switch Testing Feature


If some email messages are not being correctly routed, relayed, or masqueraded, or they are
being rejected, you can use the Sendmail Switch Testing feature to ensure that the problem is
not with your rule set definition.
You can simulate sending messages using real addresses and real hosts, thereby making sure
that there is no problem with your settings.
See the Sendmail® Switch User Guide for details about using the Testing feature.

Problems with All Filters


Cannot Receive Mail or Filter Is Ignored on UNIX
If you used the Internet Gateway Configuration Wizard to configure sendmail, or set Run As
User to a value other than root, and are using any Sendmail filter, you may not be able to
receive email, or the filter could be ignored. This applies to UNIX systems only. Your log file
will contain an error message similar to the following:
Feb 26 09:33:46 pogonip sendmail[11119]: NOQUEUE:
SYSERR(smadmin):
/etc/mail/sendmail.cf: Xflow-control: local socket name
/var/sendmail/flow-control/flow-control.sock unsafe: Permission
denied
Follow these steps to fix the problem.
1. Log in as root.
2. Change the permissions on the filter directory. Type:
chmod 0750 /var/sendmail/filter-directory
For example:
chmod 0750 /var/sendmail/flow-control
3. Change the group of the filter directory to the group associated with user RunAsUser.
Type:
chgrp RunAsUser /var/sendmail/filter-directory
For example:

Sendmail® Flow Control Filter Administration Guide 47


Obtain Offending Message With Switch 3.0 or Later

chgrp smadmin /var/sendmail/flow-control


4. In that directory, delete the socket file. Type:
rm /var/sendmail/filter-directory/filter_name.sock
For example:
rm /var/sendmail/flow-control/flow-control.sock
5. Change the line umask 027 to umask 007 in the appropriate file, for example:
base_install_dir/sendmail/smflow-version/etc/init.d/filter_name.sh
Use a text editor to change the file and then save it.
6. Stop both the Sendmail service (daemon) and the filter and then start them again.
See the Sendmail® Switch User Guide for more information.

Obtain Offending Message With Switch 3.0 or Later


If a message causes a filter to exit or terminate, you can configure Sendmail Switch to run in
debug mode to capture the offending message. This assumes that you have already configured
the filter to "tempfail" the message when the filter abnormally terminates. This rejects the
message, but the sending server will try to deliver it again later.
Follow these steps to capture the offending message:
1. Create a keep-alive script to monitor the state of the filter. If the filter is terminated,
the script will take appropriate action and restart the filter. Contact Technical Support
if you have questions on creating a keep-alive script. You also can use the
AutoRestart feature.
2. Start the filter using the keep-alive script.
3. Start sendmail in debug mode:
sendmail -d71.101 -bd
In this mode, if sendmail fails to communicate with the filter for any reasons,
sendmail will quarantine any pending and subsequent messages in the queue
(ignoring the F equate option) until sendmail is able to reconnect to the filter.
4. Capture the offending message. If the filter terminates due to a particular message, the
offending message would be quarantined in the queue.
Issue the following command to list all quarantined messages in the queue:
sendmail -bp -qQfilter

Note – The filter must be restarted immediately to avoid large amounts of


(subsequent) messages accumulated in the queue. It is strongly recommended that the
filter is monitored by a keep-alive script, which restarts the filter immediately
whenever the filter terminates.

Note that once the messages are quarantined in the queue, there is no easy way to pass
those messages to the filter for scanning. Therefore, it is important to keep the number
of messages quarantined to a minimum by immediately restarting the filter.
5. Submit a problem report along with the captured message to Sendmail Technical
Support. Please provide files starting with hf, and df.

48 Sendmail® Flow Control Filter Administration Guide


Chapter 3: Troubleshooting

6. After manually examining the quarantined messages, delivery or display of


quarantined items can be requested using the -qQ flag to sendmail or mailq.
Additionally, messages already in the queue can be quarantined or removed from
quarantine using the new -Q flag to sendmail. For example,
sendmail -Qreason -q[!]{I|R|S}[matchstring]
Quarantines the normal queue items matching the criteria specified by the -
q[!]{I|R|S}[matchstring] using the reason given on the -Q flag. Likewise,
sendmail -qQ -Q[reason] -q[!]{I|R|S|Q}[matchstring]
Change the quarantine reason for the quarantined items matching the criteria
specified by the -q[!]{I|R|S|Q{[matchstring] using the reason given on the -
Q flag. If there is no reason, remove the matching items from quarantine and make
them normal queue items. Note that the -qQ flag tells sendmail to operate on
quarantined items instead of normal items.
Refer to the Switch documentation for details.
7. Stop sendmail running in debug mode, and start it again in the normal way.
sendmail -bd
or use the Sendmail Switch interface to stop and start sendmail.

Reputation Server Errors


If a reply to a reputation query causes an error of some kind from either the Commtouch data
center or from ctIPd itself, this is reported by the filter in the log and the
ReputationUnavailable action is applied to the connection. An example of this message:
reputation query failed for x.x.x.x
reply from reputation server for query `x.x.x.x': Center is not operational
The text of this message is not generated locally, but logged exactly as it was delivered to the
filter. If these errors persist, contact Sendmail Technical Support.

Flow Control Server Out of Sync with SnortSam Agent


When the Flow Control server or the SnortSam agent are restarted having been in operation for
a while, some synchronization information between them can be lost. When they re-establish
contact, this will be detected and Flow Control Filter may log an error such as:
SAM error reply from (hostname); reinitializing
This is normal, and simply logs that Flow Control needs to re-initialize the state information
shared between it and SnortSam so that messages can continue being exchanged.

IPTABLES Error in SnortSam Log


The SnortSam agent looks for the iptables binary in the default installation directory
/sbin. If you have installed the iptables binary elsewhere, an error is generated in the
SnortSam log. Rather than copy the binary, you should create a symlink to the new location in
/sbin.

Sendmail® Flow Control Filter Administration Guide 49


IPF Error in SnortSam Log

IPF Error in SnortSam Log


On Solaris machines, the SnortSam agent looks for the ipf binary in the default installation
directory /sbin. If you have installed the ipf binary elsewhere, an error is generated in the
SnortSam log. Rather than copy the binary, you should create a symlink to the new location in
/sbin.

50 Sendmail® Flow Control Filter Administration Guide