.\"	$NetBSD: smtp-sink.1,v 1.2.14.1 2023/12/25 12:54:40 martin Exp $
.\"
.TH SMTP-SINK 1 
.ad
.fi
.SH NAME
smtp-sink
\-
parallelized SMTP/LMTP test server
.SH "SYNOPSIS"
.na
.nf
.fi
\fBsmtp\-sink\fR [\fIoptions\fR] [\fBinet:\fR][\fIhost\fR]:\fIport\fR
\fIbacklog\fR

\fBsmtp\-sink\fR [\fIoptions\fR] \fBunix:\fR\fIpathname\fR \fIbacklog\fR
.SH DESCRIPTION
.ad
.fi
\fBsmtp\-sink\fR listens on the named host (or address) and port.
It takes SMTP messages from the network and throws them away.
The purpose is to measure client performance, not protocol
compliance.

\fBsmtp\-sink\fR may also be configured to capture each mail
delivery transaction to file. Since disk latencies are large
compared to network delays, this mode of operation can
reduce the maximal performance by several orders of magnitude.

Connections can be accepted on IPv4 or IPv6 endpoints, or on
UNIX\-domain sockets.
IPv4 and IPv6 are the default.
This program is the complement of the \fBsmtp\-source\fR(1) program.

Note: this is an unsupported test program. No attempt is made
to maintain compatibility between successive versions.

Arguments:
.IP \fB\-4\fR
Support IPv4 only. This option has no effect when
Postfix is built without IPv6 support.
.IP \fB\-6\fR
Support IPv6 only. This option is not available when
Postfix is built without IPv6 support.
.IP \fB\-8\fR
Do not announce 8BITMIME support.
.IP \fB\-a\fR
Do not announce SASL authentication support.
.IP "\fB\-A \fIdelay\fR"
Wait \fIdelay\fR seconds after responding to DATA, then
abort prematurely with a 550 reply status.  Do not read
further input from the client; this is an attempt to block
the client before it sends ".".  Specify a zero delay value
to abort immediately.
.IP "\fB\-b \fIsoft\-bounce\-reply\fR"
Use \fIsoft\-bounce\-reply\fR for soft reject responses.  The
default reply is "450 4.3.0 Error: command failed".
.IP "\fB\-B \fIhard\-bounce\-reply\fR"
Use \fIhard\-bounce\-reply\fR for hard reject responses.  The
default reply is "500 5.3.0 Error: command failed".
.IP \fB\-c\fR
Display running counters that are updated whenever an SMTP
session ends, a QUIT command is executed, or when "." is
received.
.IP \fB\-C\fR
Disable XCLIENT support.
.IP "\fB\-d \fIdump\-template\fR"
Dump each mail transaction to a single\-message file whose
name is created by expanding the \fIdump\-template\fR via
strftime(3) and appending a pseudo\-random hexadecimal number
(example: "%Y%m%d%H/%M." expands into "2006081203/05.809a62e3").
If the template contains "/" characters, missing directories
are created automatically.  The message dump format is
described below.
.sp
Note: this option keeps one capture file open for every
mail transaction in progress.
.IP "\fB\-D \fIdump\-template\fR"
Append mail transactions to a multi\-message dump file whose
name is created by expanding the \fIdump\-template\fR via
strftime(3).
If the template contains "/" characters, missing directories
are created automatically.  The message dump format is
described below.
.sp
Note: this option keeps one capture file open for every
mail transaction in progress.
.IP \fB\-e\fR
Do not announce ESMTP support.
.IP \fB\-E\fR
Do not announce ENHANCEDSTATUSCODES support.
.IP "\fB\-f \fIcommand,command,...\fR"
Reject the specified commands with a hard (5xx) error code.
This option implies \fB\-p\fR.
.sp
Examples of commands are CONNECT, HELO, EHLO, LHLO, MAIL, RCPT, VRFY,
DATA, ., RSET, NOOP, and QUIT. Separate command names by
white space or commas, and use quotes to protect white space
from the shell. Command names are case\-insensitive.
.IP \fB\-F\fR
Disable XFORWARD support.
.IP "\fB\-h\fI hostname\fR"
Use \fIhostname\fR in the SMTP greeting, in the HELO response,
and in the EHLO response. The default hostname is "smtp\-sink".
.IP "\fB\-H\fI delay\fR"
Delay the first read operation after receiving DATA (time
in seconds). Combine with a large test message and a small
TCP window size (see the \fB\-T\fR option) to test the Postfix
client write_wait() implementation.
.IP \fB\-L\fR
Enable LMTP instead of SMTP.
.IP "\fB\-m \fIcount\fR (default: 256)"
An upper bound on the maximal number of simultaneous
connections that \fBsmtp\-sink\fR will handle. This prevents
the process from running out of file descriptors. Excess
connections will stay queued in the TCP/IP stack.
.IP "\fB\-M \fIcount\fR"
Terminate after receiving \fIcount\fR messages.
.IP "\fB\-n \fIcount\fR"
Terminate after \fIcount\fR sessions.
.IP \fB\-N\fR
Do not announce support for DSN.
.IP \fB\-p\fR
Do not announce support for ESMTP command pipelining.
.IP \fB\-P\fR
Change the server greeting so that it appears to come through
a CISCO PIX system. Implies \fB\-e\fR.
.IP "\fB\-q \fIcommand,command,...\fR"
Disconnect (without replying) after receiving one of the
specified commands.
.sp
Examples of commands are CONNECT, HELO, EHLO, LHLO, MAIL, RCPT, VRFY,
DATA, ., RSET, NOOP, and QUIT. Separate command names by
white space or commas, and use quotes to protect white space
from the shell. Command names are case\-insensitive.
.IP "\fB\-Q \fIcommand,command,...\fR"
Send a 421 reply and disconnect after receiving one
of the specified commands.
.sp
Examples of commands are CONNECT, HELO, EHLO, LHLO, MAIL, RCPT, VRFY,
DATA, ., RSET, NOOP, and QUIT. Separate command names by
white space or commas, and use quotes to protect white space
from the shell. Command names are case\-insensitive.
.IP "\fB\-r \fIcommand,command,...\fR"
Reject the specified commands with a soft (4xx) error code.
This option implies \fB\-p\fR.
.sp
Examples of commands are CONNECT, HELO, EHLO, LHLO, MAIL, RCPT, VRFY,
DATA, ., RSET, NOOP, and QUIT. Separate command names by
white space or commas, and use quotes to protect white space
from the shell. Command names are case\-insensitive.
.IP "\fB\-R \fIroot\-directory\fR"
Change the process root directory to the specified location.
This option requires super\-user privileges. See also the
\fB\-u\fR option.
.IP "\fB\-s \fIcommand,command,...\fR"
Log the named commands to syslogd.
.sp
Examples of commands are CONNECT, HELO, EHLO, LHLO, MAIL, RCPT, VRFY,
DATA, ., RSET, NOOP, and QUIT. Separate command names by
white space or commas, and use quotes to protect white space
from the shell. Command names are case\-insensitive.
.IP "\fB\-S start\-string\fR"
An optional string that is prepended to each message that is
written to a dump file (see the dump file format description
below). The following C escape sequences are supported: \ea
(bell), \eb (backspace), \ef (formfeed), \en (newline), \er
(carriage return), \et (horizontal tab), \ev (vertical tab),
\e\fIddd\fR (up to three octal digits) and \e\e (the backslash
character).
.IP "\fB\-t \fItimeout\fR (default: 100)"
Limit the time for receiving a command or sending a response.
The time limit is specified in seconds.
.IP "\fB\-T \fIwindowsize\fR"
Override the default TCP window size. To work around
broken TCP window scaling implementations, specify a
value > 0 and < 65536.
.IP "\fB\-u \fIusername\fR"
Switch to the specified user privileges after opening the
network socket and optionally changing the process root
directory. This option is required when the process runs
with super\-user privileges. See also the \fB\-R\fR option.
.IP \fB\-v\fR
Show the SMTP conversations.
.IP "\fB\-w \fIdelay\fR"
Wait \fIdelay\fR seconds before responding to a DATA command.
.IP "\fB\-W \fIcommand:delay[:odds]\fR"
Wait \fIdelay\fR seconds before responding to \fIcommand\fR.
If \fIodds\fR is also specified (a number between 1\-99
inclusive), wait for a random multiple of \fIdelay\fR. The
random multiplier is equal to the number of times the program
needs to roll a dice with a range of 0..99 inclusive, before
the dice produces a result greater than or equal to \fIodds\fR.
.IP [\fBinet:\fR][\fIhost\fR]:\fIport\fR
Listen on network interface \fIhost\fR (default: any interface)
TCP port \fIport\fR. Both \fIhost\fR and \fIport\fR may be
specified in numeric or symbolic form.
.IP \fBunix:\fR\fIpathname\fR
Listen on the UNIX\-domain socket at \fIpathname\fR.
.IP \fIbacklog\fR
The maximum length of the queue of pending connections,
as defined by the \fBlisten\fR(2) system call.
.SH "DUMP FILE FORMAT"
.na
.nf
.ad
.fi
Each dumped message contains a sequence of text lines,
terminated with the newline character. The sequence of
information is as follows:
.IP \(bu
The optional string specified with the \fB\-S\fR option.
.IP \(bu
The \fBsmtp\-sink\fR generated headers as documented below.
.IP \(bu
The message header and body as received from the SMTP client.
.IP \(bu
An empty line.
.PP
The format of the \fBsmtp\-sink\fR generated headers is as
follows:
.IP "\fBX\-Client\-Addr: \fItext\fR"
The client IP address without enclosing []. An IPv6 address
is prefixed with "ipv6:". This record is always present.
.IP "\fBX\-Client\-Proto: \fItext\fR"
The client protocol: SMTP, ESMTP or LMTP. This record is
always present.
.IP "\fBX\-Helo\-Args: \fItext\fR"
The arguments of the last HELO or EHLO command before this
mail delivery transaction. This record is present only if
the client sent a recognizable HELO or EHLO command before
the DATA command.
.IP "\fBX\-Mail\-Args: \fItext\fR"
The arguments of the MAIL command that started this mail
delivery transaction. This record is present exactly once.
.IP "\fBX\-Rcpt\-Args: \fItext\fR"
The arguments of an RCPT command within this mail delivery
transaction. There is one record for each RCPT command, and
they are in the order as sent by the client.
.IP "\fBReceived: \fItext\fR"
A message header for compatibility with mail processing
software. This three\-line header marks the end of the headers
provided by \fBsmtp\-sink\fR, and is formatted as follows:
.RS
.IP "\fBfrom \fIhelo\fR ([\fIaddr\fR])"
The HELO or EHLO command argument and client IP address.
If the client did not send HELO or EHLO, the client IP
address is used instead.
.IP "\fBby \fIhost\fB (smtp\-sink) with \fIproto\fB id \fIrandom\fB;\fR"
The hostname specified with the \fB\-h\fR option, the client
protocol (see \fBX\-Client\-Proto\fR above), and the pseudo\-random
portion of the per\-message capture file name.
.IP \fItime\-stamp\fR
A time stamp as defined in RFC 2822.
.RE
.SH "SEE ALSO"
.na
.nf
smtp\-source(1), SMTP/LMTP message generator
.SH "LICENSE"
.na
.nf
.ad
.fi
The Secure Mailer license must be distributed with this software.
.SH "AUTHOR(S)"
.na
.nf
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA

Wietse Venema
Google, Inc.
111 8th Avenue
New York, NY 10011, USA