popbsmtpd Reference Manual

This document describes how to use and configure popbsmtpd.

Table of Contents

• Purpose
• Features
• Command Line Arguments
  • Command Line Summary
  • Common Options
  • Monitor Options
  • Utility Functions
  • Information
• Configuration File Directives
  • General
  • Per-Service
  • Sample Configuration

Purpose

popbsmtpd is a daemon that listens for successful POP and IMAP logins, and writes IP address entries to a database shared with an SMTP server to permit relaying mail. When an administrator-configurable timeout elapses, relay access by that IP address is disabled.

It does this by reading selected syslog entries that have been directed to a named pipe, and maintaining a private database of successful logins and their time of occurrence.

It also offers a number of utility functions that permit inspecting and rebuilding the databases, displaying configuration information, and performing trial passes over sample log data to assist in testing new configurations.

It was originally written to overcome the problem of login entries spread over multiple syslog lines, which occurs when a secure wrapper (such as stunnel) is used to wrap a non-ssl-aware POP or IMAP server.

Features

Basic Features

• Is Free Software
• Is written in C for effective use of system resources
• Runs on Linux and OpenBSD; will run on other Unix variants as contributions permit
• Has tailorable authorization durations from one minute to many days, in one-minute increments
• Has flexible logging, with six levels ranging from logging only serious errors to detailed logging of what it is doing at every stage.
• Does not utilize any CPU cycles while waiting for entries to time out

Distinguishing Features

• Can process logins where the IP address and the authentication success are recorded on separate log entries
• Has a fully user-configurable scheme for recognizing and extracting values from log entries, making it possible to use with many POP and IMAP daemons without requiring program changes

Command Line Arguments

Command Line Summary

Usage: popbsmtpd [OPTIONS]

Options are:

        -ln,    --loglevel=n        Set logging level (0..6)
                                    (default: 1)
        -pFILE, --pidfile=FILE      PID file name
                                    (/var/run/popbsmtpd.pid)
        -cFILE, --configfile=FILE   Configuration file name
                                    (/etc/popbsmtpd.conf)
    and either
        -D,     --daemon            Run as daemon
    or one of
        -r,  --rebuild              Rebuild auth DB
        -tFILE, --testparse=FILE    Test config on sample log data
    or any combination of
        -dc, --dump=config          Dump configuration
        -da, --dump=auth            Dump auth DB
        -dl, --dump=login           Dump login DB
    or
        -v,  --version              Show version information
        -h,  --help                 Show this help

Common Options

--loglevel, -l

Controls the amount of output generated during startup, shutdown, and normal operations.

There is also a log_level directive for the configuration file, but it is ignored during program startup. The purpose of the configuration directive is to permit changing the logging level of a running daemon.

The logging levels and their meanings are as follows:

• 0. No logging. Nothing is written to the log unless a serious or fatal error occurs.
• 1. Default. Startup and shutdown events are logged, as well as relay enabling and disabling events.
• 2. Same as 1, with the addition of logging significant configuration information. Useful to determine if the right configuration is being used.
• 3. Arrival of input log entries is logged, showing raw input data. Expiry test parameters and the time until next wake-up are also logged. This is useful to determine whether input log entries are arriving in the right place.
• 4. Actions taken with input log entries are shown. This is useful to determine whether the proper entries are being inspected in detail, and whether the correct information is being extracted from them.
• 5. Levels higher than 4 are primarily used for debugging by developers.

The default value compiled into the program is 1.

--pidfile, -p

Determines the location and name of the file where the program's process ID is written.
The default value compiled into the program is /var/run/popbsmtpd.pid.

--configfile, -c

Indicates where configuration information should be read from.
The default value compiled into the program is /etc/popbsmtpd.conf.

Monitor Options

Utility Functions

--rebuild, -r

During operation, the program maintains two databases; one for recording logins and the time they occur, and the other to enable SMTP relaying by the mail server. The login database is considered authoritative, because it can be tested for expiry of authorizations.

If for any reason you suspect that the authorization database is corrupt, this rebuild function can ensure that the two databases are in synchronization. The command line to do this is:

[root@host /root]# popbsmtpd --rebuild

--testparse, -t

Different pop and imap servers produce log entries in varying formats, and each different format requires a different configuration to parse correctly. This option facilitates performing this testing, and is run as follows:

[root@host /root]# popbsmtpd --testparse /var/log/messages

The output shows every line that was inspected, and also shows all logins that were recognized. To additionally show each sample log entry that was read, run it specifying a logging level of 2:

[root@host /root]# popbsmtpd --loglevel=2 --testparse /var/log/messages

--dump, -d

This option gives you the ability to see the contents of the login and authorization databases. It can also be used to show the complete configuration in a format useful for piping to a new configuration file, like this:

[root@host /root]# popbsmtpd --dump=config
source_log = /var/log/pop-imap-login.log
auth_db = /etc/postfix/pop-before-smtp.db
login_db = /etc/postfix/pop-before-smtp-logins.db
auth_duration = 30
sleep_duration = 3600
log_facility = LOG_MAIL
log_level = 1
secure-pop { enabled
        multiline = 1
        daemon = "stunnel"
        string = "spop3 connected from"
        ip_daemon = "stunnel"
        ip_string = "spop3 connected from"
        ip_scan = "spop3 connected from %[^:]:%*d"
        user_daemon = "spop3"
        user_string = "Login user="
        user_scan = "Login user=%s host=%*s [%*[^]]]"
        fail_daemon = "spop3"
        fail_string = "spop3"
}

Any combination or all of these dump choices may be used at the same time:

[root@host /root]# popbsmtpd --dump=auth --dump=login
123.456.789.101 OK
123.456.789.102 OK
123.456.789.103 OK
[123.456.789.103]       Mon 2002/08/19 15:13:32 (1029795212)
[123.456.789.101]       Mon 2002/08/19 15:13:44 (1029795224)
[123.456.789.102]       Mon 2002/08/19 15:13:50 (1029795230)

Information

--version, -v

Displays the program version and exits.

--help, -h

Displays a short usage message like the summary above and exits.

Configuration File Directives

General

source_log

Identifies the source where syslog entries for pop and imap logins will be retrieved from. This must be a named pipe, which you create with mkfifo:

[root@host /root]# mkfifo /var/log/pop-imap-login.log

The default value compiled into the program is /var/log/pop-imap-login.log.

auth_db

The authorization database; this identifies the Berkeley DB hash that the SMTP server consults before accepting mail for relaying. This hash is updated whenever a successful POP or IMAP login is detected, and whenever the authorization duration for an entry expires (see auth_duration below). Entries are keyed by IP address, and have the value "OK".

To see the contents of the authorization database, you can use:

[root@host /root]# popbsmtpd --dump=auth

The default value compiled into the program is /etc/postfix/pop-before-smtp.db.

login_db

The login database; identifies the Berkeley DB btree that is used for recording successful POP or IMAP logins, along with the time they occurred. It is read in time order to identify expired entries, which are deleted from both this database and the authorization database. There are two types of entries; one keyed by Unix time, and the other keyed by IP address, prefixed with the characters "IP:" to distinguish them.

To see the contents of the login database, you can use:

[root@host /root]# popbsmtpd --dump=login

The default value compiled into the program is /etc/postfix/pop-before-smtp-logins.db.

mynetworks

Identifies the IP address ranges that are authorized to relay by the mail server without any special intervention. These are compared lexically, so they are specified as the characters that form the common prefix for local IP addresses. Up to four are accepted.

auth_duration

The number of minutes that an authorization entry is kept, thus enabling relaying from that IP address.

From a client perspective, this number should be as long as possible; from the server administrator's perspective, it should be short. It is up to the administrator to determine the risk of abuse from an IP address that is open for an extended period of time.

The default value compiled into the program is 30 minutes.

sleep_duration

The maximum number of seconds to sleep between checking for expired entries. The actual sleep time is determined by taking the lesser of this value, and the time until the next login entry expires. If sleep_duration is set to a high value, the daemon will only wake up when a log entry arrives or when an authorization duration expires.

The default value compiled into the program is 86400 seconds (one day).

log_facility

The facility to use when logging to the system log. This is a matter of administrator preference, as the facility code can be used to route log entries to various destinations. The choices available are:

LOG_KERN LOG_USER LOG_MAIL LOG_DAEMON LOG_AUTH
LOG_SYSLOG LOG_LPR LOG_NEWS LOG_UUCP LOG_CRON
LOG_AUTHPRIV LOG_FTP
LOG_LOCAL0 LOG_LOCAL1 LOG_LOCAL2 LOG_LOCAL3
LOG_LOCAL4 LOG_LOCAL5 LOG_LOCAL6 LOG_LOCAL7

The default value compiled into the program is LOG_MAIL.

log_level

Ignored at program startup; honoured when program receives SIGHUP.

The logging level can be specified in the configuration file to permit changing the logging level of a running daemon. To cause this value to be read and put into effect, issue the command:

[root@host /root]# killall -HUP popbsmtpd

See the description of the command line argument --loglevel for a description of the various log levels.

Per-Service

The program can be configured to monitor logins from up to four types of clients. Each one will have its own unique signature(s) in the source log, so each has its own section for signature definitions and value extraction formats.

The sections are introduced by the keywords pop, imap, secure-pop, and secure-imap, and are enclosed by braces {}. To permit commenting out these sections wholesale, the first keyword in the section must be ENABLE in order to cause the section to be processed.

Note: The current version has only a rudimentary configuration parser, so the section start and end markers must each be all on their own separate line, like this:

pop { enable
...
}

There are four groups of keywords within each service definition. They define how to recognize the start of a login, how to extract the IP address, how to extract the user, and how to recognize a failed login. The *daemon and *string pair in each group specify how to identify appropriate syslog entries to process; daemon specifying which program issued the log entry, and string specifying a string that must be present. Both tests must pass for a syslog entry to be considered for further processing.

Each enabled section is given an opportunity to look at every source log entry, in the order they occur in the configuration file.

The actual extraction of the IP address and user is specified with a sscanf() format string. Warning; this gives you plenty of opportunity to crash the program. If you are not familiar with sscanf(), get help with this from a programmer. You can test the results of your experiments with the --testparse command line option.

Login Recognition

Three keywords instruct the program how to detect the start of a login in progress.

multiline

Set this to 0 if all the login information is on the same line in the source log. This is typically the case for plain POP and IMAP, where the POP/IMAP server accepts connections from the outside world.

Set this to 1 if the login information is spread across multiple lines in the source log. This is typically the case when a secure wrapper like stunnel accepts the inbound IP connection, and connects to the POP/IMAP service on the loopback interface.

daemon

This identifies the program that issues the syslog entry indicating the start of a POP/IMAP login. The program inspects each log entry that arrives in the source log, and takes further action if it is issued by the program identified here.

string

Once a syslog entry from the appropriate daemon is identified, it is further inspected to see if it contains the constant string specified here. If it does, further processing takes place.

Extracting the IP Address

ip_daemon

This identifies the program that issues the syslog entry containing the IP address of the client.

ip_string

This specifies a string that must be present for further consideration of this entry.

ip_scan

This specifies a sscanf()-style format string used to extract the IP address from the line successfully identified by the above two entries.

Extracting the User ID

user_daemon

This identifies the program that issues the syslog entry containing the user id of the client.

user_string

This specifies a string that must be present for further consideration of this entry.

user_scan

This specifies a sscanf()-style format string used to extract the user id from the line successfully identified by the above two entries.

Detecting Failed Logins

It is important to be able to detect failed logins; any rogue with an IP stack can connect to stunnel and get their IP address logged, but if they do not have an account, the POP/IMAP server will emit a log entry indicating that the login did not succeed. By testing for this, we avoid giving out relay access on the basis of a bogus user id.

fail_daemon

This identifies the program that issues the syslog entry indicating a failed login.

fail_string

This specifies a string that is present on failed login entries.

A Sample Configuration

---Begin---
source_log = /var/log/pop-imap-login.log
auth_db = /etc/postfix/pop-before-smtp.db
login_db = /etc/postfix/pop-before-smtp-logins.db
mynetworks = 192.168.1. 192.168.2. 10.
auth_duration = 30
sleep_duration = 86400
log_facility = LOG_MAIL
log_level = 1
secure-pop { enable
   multiline = 1
   daemon = "stunnel"
   string = "spop3 connected from"
   ip_daemon = "stunnel"
   ip_string = "spop3 connected from"
   ip_scan = "spop3 connected from %[^:]%*d"
   user_daemon = "spop3"
   user_string = "Login user="
   user_scan = "Login user=%s host=%*s [%*[^]]]"
   fail_daemon = "spop3"
   fail_string = "Login failure user="
}
pop { disable
   multiline = 0
   daemon = "spop3"
   string = "spop3 service init from"
   ip_daemon = "spop3"
   ip_string = "Login user="
   ip_scan = "Login user=%*s host=%*s [%[^]]]"
   user_daemon = "spop3"
   user_string = "Login user="
   user_scan = "Login user=%s host=%*s [%*[^]]]"
   fail_daemon = "spop3"
   fail_string = "Login failure user="
}

----End----

Researched and written by Marcus Redivo.
Permission to use this document for any purpose is hereby granted, providing this copyright information and disclaimer is retained. Author accepts no responsibility for any consequences arising from the use of this information.