smtpf Command Options

To review the smtpf option summary:

$ smtpf -help

To start smtpf:

# smtpf

To stop smtpf:

# smtpf -quit

To restart smtpf:

# smtpf -restart

To restart smtpf using a different configuration file:

# smtpf -restart \
  file=/path/to/alt/smtpf.cf

The file option when it appears in the smtpf.cf does nothing other than document which smtpf.cf was read. It's possible to specify one or more options on the command line in order to override what appears in smtpf.cf or the hard coded default.

To restart smtpf only if it is currently running:

# smtpf -restart-if

The command options shown above can be prefixed by either a plus (+) or minus (-) sign and both behave the same.

Runtime Configuration

Typically if you change the contents of smtpf.cf, you must restart smtpf in order for those options to take affect.

# smtpf +restart

However many of the smtpf options can be configured during runtime by telneting to localhost port 25 and issuing smtpf commands.

$ telnet 127.0.0.1 25

For security reasons, these commands only work when the connection comes from localhost. They are:

CACHE GETkey

CACHE PUTkey value

CACHE DELETEkey

Cache manipulation commands.

CONN

The CONN command will display a list of all the currently active connections showing the session ID, SMTP state, client name and IP, session age in seconds, input idle time in seconds, and total number of octets sent in messages.

KILL session-id

The KILL command will terminate the SMTP client session matching the given session-ID. Currently not available for Windows.

OPTN

OPTN ±option-name

OPTN option-name=value

The OPTN command without any argument, will display all the current option settings, one per line. If an argument is specified, it is the same as would be specified in the smtpf.cf file. Some options cannot be changed at runtime, if they influence how smtpf starts up.

STAT

The STAT command will display the current runtime statistics since the last restart, current hour, and last 60 rolling window. Each line reflects either a test or checkpoint. The statistics are intentionally not documented as they are intended for diagnostics and subject to change.

VERB

VERB ±verbose-flag ...

The VERB command without any argument, will display the current verbose logging flags. Sometimes it's useful to turn on and off certain verbose logging flags in order to diagnose a problem. For example:

VERB +smtp -uri

The Cache File

The cache file is an SQLite3 database and can be manipulated using the supplied programs sqlite3t (our version build with thread support enabled) and mcc. Manipulating the cache is particular useful when there are records that may be preventing one or more messages to pass. This can occur for example if you suddenly white list a sender in the access-map, but mail from that sender is still being blocked, because of a cache entry that has not yet expired.

# sqlite3t /var/db/smtpf/cache.sq3

Using sqlite3t it is possible to add, remove, or modify cache entries using standard SQL commands. How to use sqlite3t and SQL in general is beyond the scope of this document and not covered here.

The mcc provides a simplified means of manipulating the cache locally and across machines that listen to multicast or unicast cache broadcasts. The short usage summary is displayed with:

# mcc

The mcc command reads commands from standard input and writes informational messages to standard output. The are four commands: GET, PUT, DELETE and QUIT. The GET command reads from the local cache, while the PUT and DELETE will update the local cache and broadcast to the multicast group or unicast host list. The values for mcc options -m, -M, -d, -U, and -s should correspond with those specified in smtpf.cf for: cache-multicast-ip, cache-multicast-port, cache-unicast-domain, cache-unicast-port, and cache-secret.

# mcc -m 232.1.2.3:6920 -s your-secret-here /var/db/smtpf/cache.sq3

The cache's SQL data was designed to fit within the 512 octets of a UDP datagram and is defined in SQL as follows (note this is different from the UDP datagram structure which is not specified here):

CREATE TABLE mcc (
    k VARCHAR(383) PRIMARY KEY,	-- the tagged key
    d VARCHAR(92),		-- data value
    h INTEGER DEFAULT 1,	-- hit counter
    c INTEGER,			-- create timestamp
    t INTEGER,			-- last touched timestamp
    e INTEGER			-- expires timestamp, indexed
);

Note that the above structure may change without notice. When using the sqlite3t command, all columns are accessible, while with the mcc PUT command only the k and d can be altered since the client/server portions of the mcc protocol manage the others columns.

The format of the cache k and d columns varies depending on the test. The following is a brief summary of the possible formats used for both k and d columns in the event they need to be modified manually. Note that this information may change without notice.

click:ip,ptr,mail	ASCII 2 = accept. Either ip or ptr is present, never both; similar to the definition of the ptr element used in grey-key.
dumb:host	ASCII 2 = accept, 5 = reject
grey:ip,ptr,helo,mail,rcpt	ASCII 0 = continue, 4 = temp. fail; optionally followed by a space and two hexdecimal MD5 hashes when using +grey-content. The key field order remains constant, fields present according to grey-key; be sure to review how the ip and ptr fields are used.
msg-limit:client-ip	ASCII integer counter of messages sent
msg-limit:sender	ASCII integer counter of messages sent
msg-limit:recipient	ASCII integer counter of messages sent
rcpt:recipient	ASCII 2 = accept, 5 = reject
sav:sender-domain	ASCII 2 = accept, 5 = reject
sav:sender	ASCII 2 = accept, 4 = temp.fail, 5 = reject
siq:client-ip,sender-domain	mixed binary & ASCII content

The Stats File

The stats file is an SQLite3 database and can be manipulated using the supplied programs sqlite3t (our version build with thread support enabled). Generally it is not a good idea to manipulating the statistics file, but we describe it here for completeness.

# sqlite3t /var/db/smtpf/stats.sq3

Using sqlite3t it is possible to add, remove, or modify records using standard SQL commands. How to use sqlite3t and SQL in general is beyond the scope of this document and not covered here.

The statistics file uses a generalised key-value-map (KVM) API, which does not take advantage of SQL to the fullest. This may change in future releases of smtpf.

CREATE TABLE kvm (
    k TEXT PRIMARY KEY, 	-- the key
    v TEXT 			-- data value
);

The format of the k and v columns varies. The following is a brief summary of the possible formats used for both k and v columns in the event they need to be modified manually or consulted by third-party tools. Note that this information may change without notice.

YYYYMMDDHH	ASCII space separated list of values corresponding to the field order given by fields:; start-time and touch-time values are given in hexdecimal, while all other values are decimal.
fields:version	ASCII space separate list of field names in store order.
route:recipient	ASCII space separated fields; first field in decimal is the day-of-year followed by the last 31 days of hexadecimal triples accept:reject:volume giving message counts and volume in kilobytes. The route: key used corresponds to those found in the route-map.

- TOP -

Copyright 2006, 2016 by SnertSoft. All rights reserved.
BarricadeMX trademark & patents pending.