Packages and Binaries:
swaks
SMTP command-line test tool
swaks (Swiss Army Knife SMTP) is a command-line tool written in Perl
for testing SMTP setups; it supports STARTTLS and SMTP AUTH (PLAIN,
LOGIN, CRAM-MD5, SPA, and DIGEST-MD5). swaks allows one to stop the
SMTP dialog at any stage, e.g to check RCPT TO: without actually
sending a mail.
If you are spending too much time iterating “telnet foo.example 25” swaks is for you.
Installed size: 312 KB
How to install: sudo apt install swaks
Dependencies:
- perl
swaks
Swiss Army Knife SMTP, the all-purpose SMTP transaction tester
root@kali:~# swaks --help
SWAKS(1) SWAKS SWAKS(1)
NAME
Swaks - Swiss Army Knife SMTP, the all-purpose SMTP transaction tester
DESCRIPTION
Swaks' primary design goal is to be a flexible, scriptable, transaction-
oriented SMTP test tool. It handles SMTP features and extensions such as
TLS, authentication, and pipelining; multiple version of the SMTP protocol
including SMTP, ESMTP, and LMTP; and multiple transport methods including
UNIX-domain sockets, internet-domain sockets, and pipes to spawned
processes. Options can be specified in environment variables, configura-
tion files, and the command line allowing maximum configurability and ease
of use for operators and scripters.
QUICK START
Deliver a standard test email to [email protected] on port 25 of
test-server.example.net:
swaks --to [email protected] --server test-server.example.net
Deliver a standard test email, requiring CRAM-MD5 authentication as user
[email protected]. An "X-Test" header will be added to the email body. The
authentication password will be prompted for if it cannot be obtained from
your .netrc file.
swaks --to [email protected] --from [email protected] --auth CRAM-MD5 --auth-user [email protected] --header-X-Test "test email"
Test a virus scanner using EICAR in an attachment. Don't show the message
DATA part.:
swaks -t [email protected] --attach - --server test-server.example.com --suppress-data </path/to/eicar.txt
Test a spam scanner using GTUBE in the body of an email, routed via the MX
records for example.com:
swaks --to [email protected] --body @/path/to/gtube/file
Deliver a standard test email to [email protected] using the LMTP protocol
via a UNIX domain socket file
swaks --to [email protected] --socket /var/lda.sock --protocol LMTP
Report all the recipients in a text file that are non-verifiable on a test
server:
for E in `cat /path/to/email/file`
do
swaks --to $E --server test-server.example.com --quit-after RCPT --hide-all
[ $? -ne 0 ] && echo $E
done
TERMS AND CONVENTIONS
This document tries to be consistent and specific in its use of the fol-
lowing terms to reduce confusion.
Target
The target of a transaction is the thing that Swaks connects to. This
generic term is used throughout the documentation because most other
terms improperly imply something about the transport being used.
Transport
The transport is the underlying method used to connect to the target.
Transaction
A transaction is the opening of a connection over a transport to a
target and using a messaging protocol to attempt to deliver a message.
Protocol
The protocol is the application language used to communicate with the
target. This document uses SMTP to speak generically of all three
supported protocols unless it states that it is speaking of the spe-
cific 'SMTP' protocol and excluding the others.
Message
SMTP protocols exist to transfer messages, a set of bytes in an
agreed-upon format that has a sender and a recipient.
Envelope
A message's envelope contains the "true" sender and receiver of a mes-
sage. It can also be referred to as its components, envelope-sender
and envelope-recipients. It is important to note that a messages en-
velope does not have to match its "To:" and "From:" headers.
DATAThe DATA portion of an SMTP transaction is the actual message that is
being transported. It consists of both the message's headers and its
body. DATA and body are sometimes used synonymously, but they are al-
ways two distinct things in this document.
Headers
A message's headers are defined as all the lines in the message's DATA
section before the first blank line. They contain information about
the email that will be displayed to the recipient such as "To:",
"From:", "Subject:", etc. In this document headers will always be
written with a capitalized first letter and a trailing colon.
BodyA message's body is the portion of its DATA section following the
first blank line.
Option
An option is a flag which changes Swaks' behavior. Always called an
option regardless of how it is provided. For instance,
"--no-data-fixup" is an option.
Argument
When an option takes addition data beside the option itself, that ad-
ditional data is called an argument. In "--quit-after <stop-point>'",
"<stop-point>" is the argument to the "--quit-after" option.
<literal-string>
When used in the definition of an option, text that is inside of angle
brackets ("<>") indicates a descriptive label for a value that the
user should provide. For instance, "--quit-after <stop-point>" indi-
cates that "<stop-point>" should be replaced with a valid stop-point
value.
[<optional-value>]
When used in the definition of an option, text inside of square brack-
ets ([]) indicates that the value is optional and can be omitted. For
instance, "--to [<recipient>]" indicates that the "--to" option can be
used with or without a specified "<recipient>".
OPTION PROCESSING
To prevent potential confusion in this document a flag to Swaks is always
referred to as an "option". If the option takes additional data, that ad-
ditional data is referred to as an argument to the option. For example,
"--from [email protected]" might be provided to Swaks on the command line,
with "--from" being the option and "[email protected]" being "--from"'s ar-
gument.
Options and arguments are the only way to provide information to Swaks.
If Swaks finds data during option processing that is neither an option nor
an option's argument, it will error and exit. For instance, if
"--no-data-fixup 1" were found on the command line, this would result in
an error because "--no-data-fixup" does not take an argument and therefore
Swaks would not know what to do with 1.
Options can be given to Swaks in three ways. They can be specified in a
configuration file, in environment variables, and on the command line.
Depending on the specific option and whether an argument is given to it,
Swaks may prompt the user for the argument.
When Swaks evaluates its options, it first looks for a configuration file
(either in a default location or specified with "--config"). Then it
evaluates any options in environment variables. Finally, it evaluates
command line options. At each round of processing, any options set ear-
lier will be overridden. Additionally, any option can be prefixed with
"no-" to cause Swaks to forget that the variable had previously been set
(either in an earlier round, or earlier in the same round). This capabil-
ity is necessary because many options treat defined-but-no-argument dif-
ferently than not-defined.
As a general rule, if the same option is given multiple time, the last
time it is given is the one that will be used. This applies to both in-
tra-method (if "--from [email protected] --from [email protected]" is
given, "[email protected]" will be used) and inter-method (if "from
[email protected]" is given in a config file and "--from user2@exam-
ple.com" is given on the command line, "[email protected]" will be used)
Each option definition ends with a parenthetical synopsis of how the op-
tion behaves. The following codes can be used
Arg-None, Arg-Optional, Arg-Required
These three codes are mutually exclusive and describe whether or not
the option takes an argument. Note that this does not necessarily de-
scribe whether the argument is required to be specified directly, but
rather whether an argument is required eventually. For instance,
"--to" is labeled as Arg-Required, but it is legal to specify "--to"
on the command line without an argument. This is because Swaks can
prompt for the required argument if it is not directly provided.
From-Prompt
An option labeled with From-Prompt will prompt the user interactively
for the argument if none is provided.
From-File
An option labeled with From-File will handle arguments as files in
certain situations.
If the initial argument is "-", the final argument is the contents of
"STDIN". Multiple options can all specify "STDIN", but the same con-
tent will be used for each of them.
If the initial argument is prefixed with "@", the argument will be
treated as a path to a file. The file will be opened and the contents
will be used as the final argument. If the contents of the file can't
be read, Swaks will exit. To specify a literal string value starting
with an "@", use two "@" symbols. The first will be stripped. It is
not possible to include an unqualified file which starts with an "@"
sign (like "--attach @file.txt" or "--attach @@file.txt"), but if you
include a path to the file which splits up the two "@" signs, that
will work (eg "--attach @./@file.txt" will include the contents of the
file @file.txt).
Sensitive
If an option marked Sensitive attempts to prompt the user for an argu-
ment and the "--protect-prompt" option is set, Swaks will attempt to
mask the user input from being echoed on the terminal. Swaks tries to
mask the input in several ways, but if none of them work program flow
will continue with unmasked input.
Deprecated
An option labeled Deprecated has been officially deprecated and will
be removed in a future release. See the "DEPRECATIONS" section of
this documentation for details about the deprecations.
The exact mechanism and format for using each of the types is listed be-
low.
CONFIGURATION FILES
A configuration file can be used to set commonly-used or abnormally
verbose options. By default, Swaks looks in order for
$SWAKS_HOME/.swaksrc, $HOME/.swaksrc, and $LOGDIR/.swaksrc. If one of
those is found to exist (and "--config" has not been used) that file
is used as the configuration file.
Additionally, a configuration file in a non-default location can be
specified using "--config". If this is set and not given an argument
Swaks will not use any configuration file, including any default file.
If "--config" points to a readable file, it is used as the configura-
tion file, overriding any default that may exist. If it points to a
non-readable file an error will be shown and Swaks will exit.
A set of "portable" defaults can also be created by adding options to
the end of the Swaks program file. As distributed, the last line of
Swaks should be "__END__". Any lines added after "__END__" will be
treated as the contents of a configuration file. This allows a set of
user preferences to be automatically copied from server to server in a
single file.
If configuration files have not been explicitly turned off, the
"__END__" config is always read. Only one other configuration file
will ever be used per single invocation of Swaks, even if multiple
configuration files are specified. If the "__END__" config and an-
other config are to be read, the "__END__" config will be processed
first. Specifying the "--config" option with no argument turns off
the processing of both the "__END__" config and any actual config
files.
In a configuration file lines beginning with a hash ("#") are ignored.
All other lines are assumed to be an option to Swaks, with the leading
dash or dashes optional. Everything after an option line's first
space is assumed to be the option's argument and is not shell
processed. Therefore, quoting is usually unneeded and will be in-
cluded literally in the argument.
There is a subtle difference between providing an option with no argu-
ment and providing an option with an empty argument. If an option
line does not have a space, the entire line is treated as an option
and there is no argument. If the line ends in a single space, it will
be processed as an option with an empty argument. So, "apt" will be
treated as "--apt", but "apt " will be treated as "--apt ''".
Here is an example of the contents of a configuration file:
# always use this sender, no matter server or logged in user
--from [email protected]
# I prefer my test emails have a pretty from header. Note
# the lack of dashes on option and lack of quotes around
# entire argument.
h-From: "Fred Example" <[email protected]>
Options specific to configuration file:
--config [<config-file>]
This option provides a path to a specific configuration file to be
used. If specified with no argument, no automatically-found con-
figuration file (via $HOME, etc, or "__END__") will be processed.
If the argument is a valid file, that file will be used as the
configuration file (after "__END__" config). If argument is not a
valid, readable file, Swaks will error and exit. This option can
be specified multiple times, but only the first time it is speci-
fied (in environment variable and the command line search order)
will be used. (Arg-Optional)
CONFIGURATION ENVIRONMENT VARIABLES
Options can be supplied via environment variables. The variables are
in the form $SWAKS_OPT_name, where "name" is the name of the option
that would be specified on the command line. Because dashes aren't
allowed in environment variable names in most UNIX-ish shells, no
leading dashes should be used and any dashes inside the option's name
should be replaced with underscores. The following would create the
same options shown in the configuration file example:
$ SWAKS_OPT_from='[email protected]'
$ SWAKS_OPT_h_From='"Fred Example" <[email protected]>'
Setting a variable to an empty value is the same as specifying it on
the command line with no argument. For instance, setting
<SWAKS_OPT_server=""> would cause Swaks to prompt the user for the
server to which to connect at each invocation. On Windows, it is not
possible to set empty environment variables. The behavior can be sim-
ulated by setting the environment variable to "<>" instead. Addition-
ally, embedding the header name in the header option via environment
variable is not allowed on Windows (eg "SWAKS_OPT_header_Foo=bar" will
result in an error, but "SWAKS_OPT_header="Foo: bar"" will work.)
Because there is no inherent order in options provided by setting en-
vironment variables, the options are sorted before being processed.
This is not a great solution, but it at least defines the behavior,
which would be otherwise undefined. As an example, if both
$SWAKS_OPT_from and $SWAKS_OPT_f were set, the value from
$SWAKS_OPT_from would be used, because it sorts after $SWAKS_OPT_f.
Also as a result of not having an inherent order in environment pro-
cessing, unsetting options with the "no-" prefix is unreliable. It
works if the option being turned off sorts before "no-", but fails if
it sorts after. Because "no-" is primarily meant to operate between
config types (for instance, unsetting from the command line an option
that was set in a config file), this is not likely to be a problem.
In addition to setting the equivalent of command line options,
$SWAKS_HOME can be set to a directory containing the default .swaksrc
to be used.
COMMAND LINE OPTIONS
The final method of supplying options to Swaks is via the command
line. The options behave in a manner consistent with most UNIX-ish
command line programs. Many options have both a short and long form
(for instance "-s" and "--server"). By convention short options are
specified with a single dash and long options are specified with a
double-dash. This is only a convention and either prefix will work
with either type.
The following demonstrates the example shown in the configuration file
and environment variable sections:
$ swaks --from [email protected] --h-From: '"Fred Example" <[email protected]>'
TRANSPORTS
Swaks can connect to a target via UNIX pipes ("pipes"), UNIX domain sock-
ets ("UNIX sockets"), or internet domain sockets ("network sockets").
Connecting via network sockets is the default behavior. Because of the
singular nature of the transport used, each set of options in the follow-
ing section is mutually exclusive. Specifying more than one of
"--server", "--pipe", or "--socket" will result in an error. Mixing other
options between transport types will only result in the irrelevant options
being ignored. Below is a brief description of each type of transport and
the options that are specific to that transport type.
NETWORK SOCKETS
This transport attempts to deliver a message via TCP/IP, the standard
method for delivering SMTP. This is the default transport for Swaks.
If none of "--server", "--pipe", or "--socket" are given then this
transport is used and the target server is determined from the recipi-
ent's domain (see "--server" below for more details).
This transport requires the IO::Socket::IP module for both IPv4 and
IPv6 sockets. If this module is not loadable, Swaks will attempt to
use the IO::Socket library for IPv4 and IO::Socket::INET6 for IPv6
support. Attempting to use this transport with none of those li-
braries available will result in an error and program termination.
The fall back to IO::Socket and IO::Socket::INET6 is deprecated and
will be removed in a future release. See DEPRECATIONS below
-s, --server [<target-server>[:<port>]]
Explicitly tell Swaks to use network sockets and specify the host-
name or IP address to which to connect, or prompt if no argument
is given. If this option is not given and no other transport op-
tion is given, the target mail server is determined from the ap-
propriate DNS records for the domain of the recipient email ad-
dress using the Net::DNS module. If Net::DNS is not available
Swaks will attempt to connect to localhost to deliver. The target
port can optionally be set here. Supported formats for this in-
clude SERVER:PORT (supporting names and IPv4 addresses);
[SERVER]:PORT and SERVER/PORT (supporting names, IPv4 and IPv6 ad-
dresses). A port set via this option will only be used if the
"--port" option is not used. See also "--copy-routing". (Arg-Re-
quired, From-Prompt)
-p, --port [<port>]
Specify which TCP port on the target is to be used, or prompt if
no argument is listed. The argument can be a service name (as re-
trieved by getservbyname(3)) or a port number. The default port
is smtp/25 unless influenced by the "--protocol" or "--tls-on-con-
nect" options. (Arg-Required, From-Prompt)
-li, --local-interface [<local-interface>[:<port>]]
Use argument as the local interface for the outgoing SMTP connec-
tion, or prompt user if no argument given. Argument can be an IP
address or a hostname. Default action is to let the operating
system choose the local interface. See "--server" for additional
comments on :<port> format. A port set via this option will only
be used if the "--port" option is not used. (Arg-Required, From-
Prompt)
-lp, --local-port, --lport [<port>]
Specify the outgoing port from which to originate the transaction.
The argument can be a service name (as retrieved by getservby-
name(3)) or a port number. If this option is not specified the
system will pick an ephemeral port. Note that regular users can-
not specify some ports. (Arg-Required, From-Prompt)
--copy-routing <domain>
The argument is interpreted as the domain part of an email address
and it is used to find the target server using the same logic that
would be used to look up the target server for a recipient email
address. See "--to" option for more details on how the target is
determined from the email domain. (Arg-Required)
-4, -6
Force IPv4 or IPv6. (Arg-None)
UNIX SOCKETS
This transport method attempts to deliver messages via a UNIX-domain
socket file. This is useful for testing MTA/MDAs that listen on
socket files (for instance, testing LMTP delivery to Cyrus). This
transport requires the IO::Socket::UNIX module which is part of the
standard Perl distribution. If this module is not loadable, attempt-
ing to use this transport will result in an error and program termina-
tion.
--socket [<socket-file>]
This option takes as its argument a UNIX-domain socket file. If
Swaks is unable to open this socket it will display an error and
exit. (Arg-Required, From-Prompt)
PIPES
This transport attempts to spawn a process and communicate with it via
pipes. The spawned program must be prepared to behave as a mail
server over "STDIN"/"STDOUT". Any MTA designed to operate from
inet/xinet should support this. In addition, some MTAs provide test-
ing modes that can be communicated with via "STDIN"/"STDOUT". This
transport can be used to automate that testing. For example, if you
implemented DNSBL checking with Exim and you wanted to make sure it
was working, you could run "swaks --pipe "exim -bh 127.0.0.2"". Ide-
ally, the process you are talking to should behave exactly like an
SMTP server on "STDIN" and "STDOUT". Any debugging should be sent to
"STDERR", which will be directed to your terminal. In practice, Swaks
can generally handle some debug on the child's "STDOUT", but there are
no guarantees on how much it can handle.
This transport requires the IPC::Open2 module which is part of the
standard Perl distribution. If this module is not loadable, attempt-
ing to use this transport will result in an error and program termina-
tion.
--pipe [<command-and-arguments>]
Provide a process name and arguments to the process. Swaks will
attempt to spawn the process and communicate with it via pipes.
If the argument is not an executable Swaks will display an error
and exit. (Arg-Required, From-Prompt)
PROTOCOL OPTIONS
These options are related to the protocol layer.
-t, --to [<email-address>[,<email-address>[,...]]]
--cc [<email-address>[,<email-address>[,...]]]
--bcc [<email-address>[,<email-address>[,...]]]
These options all tell Swaks to use the argument(s) as the envelope-
recipient for the email. There are subtle differences between these
three options, detailed below. If any option is specified but with no
arguments, Swaks will prompt the user for an argument.
"--to" is special in that it is the only option required by Swaks.
There is no default value for this option. If no recipients are pro-
vided via any means, user will be prompted to provide one interac-
tively. The only exception to this is if a "--quit-after" value is
provided which will cause the SMTP transaction to be terminated before
the recipient is needed. If multiple recipients are provided and the
recipient domain is needed to determine routing, the domain of the
last recipient in the "--to" argument list is used.
The primary distinction between these options is how their arguments
are treated when generating the DATA portion of the email. They each
have their own replacement tokens ("%TO_ADDRESS%", "%CC_ADDRESS%", and
"%BCC_ADDRESS%" respectively) which can be used by anyone crafting a
custom DATA. In Swaks' default message, "%TO_ADDRESS%" will be used
for the To: header and, if it is populated, "%CC_HEADER%" will be used
for a Cc: header. "%BCC_ADDRESS%" is not used in the default DATA.
(Arg-Required, From-Prompt)
-f, --from [<email-address>]
Use argument as envelope-sender for email, or prompt user if no argu-
ment specified. The string "<>" can be supplied to mean the null
sender. If user does not specify a sender address a default value is
used. The domain-part of the default sender is a best guess at the
fully-qualified domain name of the local host. The method of deter-
mining the local-part varies. If the $LOGNAME environment variable is
set, it will be used as the local-part. Otherwise the value from
Win32::LoginName() will be used on Windows and getpwuid(3) on UNIX-ish
platforms. See also "--force-getpwuid". If Swaks cannot determine a
local hostname and the sender address is needed for the transaction,
Swaks will error and exit. In this case, a valid string must be pro-
vided via this option. (Arg-Required, From-Prompt)
--ehlo, --lhlo, -h, --helo [<helo-string>]
String to use as argument to HELO/EHLO/LHLO command, or prompt user if
no argument is specified. If this option is not used a best guess at
the fully-qualified domain name of the local host is used. If Swaks
cannot determine a local hostname and the helo string is needed for
the transaction, Swaks will error and exit. In this case, a valid
string must be provided via this option. (Arg-Required, From-Prompt)
-q, --quit, --quit-after <stop-point>
Point at which the transaction should be stopped. When the requested
stopping point is reached in the transaction, and provided that Swaks
has not errored out prior to reaching it, Swaks will send "QUIT" and
attempt to close the connection cleanly. These are the valid argu-
ments and notes about their meaning. (Arg-Required)
PROXY
Quit after the server sends a response to a PROXY request. Note
that if there is not an error negotiating proxy, this will be syn-
onymous with CONNECT.
CONNECT, BANNER
Terminate the session after receiving the greeting banner from the
target.
FIRST-HELO, FIRST-EHLO, FIRST-LHLO
In a STARTTLS (but not tls-on-connect) session, terminate the
transaction after the first of two HELOs. In a non-STARTTLS
transaction, behaves the same as HELO (see below).
XCLIENT
Quit after XCLIENT is negotiation. This always quits after the
point where XCLIENT would have been negotiated, regardless of
whether it was attempted.
XCLIENT-HELO
Quit after the HELO that XCLIENT negotiation triggers. This dif-
fers from HELO and FIRST-HELO because XCLIENT negotiation can hap-
pen at multiple points in the SMTP transaction and it is impossi-
ble to specifically refer to the XCLIENT-triggered HELO using the
HELO or FIRST-HELO stop-points. This always quits after the point
where the XCLIENT-triggered HELO would have occurred, regardless
of whether it was attempted.
STARTTLS, TLS
Quit the transaction immediately following TLS negotiation. Note
that this happens in different places depending on whether START-
TLS or tls-on-connect are used. This always quits after the point
where TLS would have been negotiated, regardless of whether it was
attempted.
HELO, EHLO, LHLO
In a STARTTLS or XCLIENT session, quit after the second HELO.
Otherwise quit after the first and only HELO.
AUTHQuit after authentication. This always quits after the point
where authentication would have been negotiated, regardless of
whether it was attempted.
MAIL, FROM
Quit after MAIL FROM: is sent.
RCPT, TO
Quit after RCPT TO: is sent.
--da, --drop-after <stop-point>
The option is similar to "--quit-after", but instead of trying to
cleanly shut down the session it simply terminates the session. This
option accepts the same stop-points as "--quit-after" and additionally
accepts DATA and DOT, detailed below. (Arg-Required)
DATADrop the connection after DATA is sent by server.
DOT Drop the connection after the final '.' of the message is sent by
server.
--das, --drop-after-send <stop-point>
This option is similar to "--drop-after", but instead of dropping the
connection after reading a response to the stop-point, it drops the
connection immediately after sending stop-point. It accepts the same
stop-points as "--drop-after". If the stop-point is for an optional
part of the transaction which is not actually sent (for instance
STARTTLS or AUTH), this option will behave identically to "--drop-af-
ter". See below for specific details. (Arg-Required)
CONNECT
Connect to the server and then drops the connection before receiv-
ing the server's banner.
STARTTLS, TLS
Behaves identically to "--drop-after".
HELO, EHLO, LHLO
Doesn't necessarily work as expected. If it appears to read the
HELO response incorrectly, use FIRST-HELO instead.
--timeout [<time>]
Use argument as the SMTP transaction timeout, or prompt user if no ar-
gument given. Argument can either be a pure digit, which will be in-
terpreted as seconds, or can have a specifier s, m, or h (5s = 5 sec-
onds, 3m = 180 seconds, 1h = 3600 seconds). As a special case, 0
means don't timeout the transactions. Default value is 30s. (Arg-Re-
quired, From-Prompt)
--protocol <protocol>
Specify which protocol to use in the transaction. Valid options are
shown in the table below. Currently the 'core' protocols are SMTP,
ESMTP, and LMTP. By using variations of these protocol types one can
tersely specify default ports, whether authentication should be at-
tempted, and the type of TLS connection that should be attempted. The
default protocol is ESMTP. The following table demonstrates the
available arguments to "--protocol" and the options each sets as a
side effect. (Arg-Required)
SMTPHELO, "-p 25"
SSMTP
EHLO->HELO, "-tlsc -p 465"
SSMTPA
EHLO->HELO, "-a -tlsc -p 465"
SMTPS
HELO, "-tlsc -p 465"
ESMTP
EHLO->HELO, "-p 25"
ESMTPA
EHLO->HELO, "-a -p 25"
ESMTPS
EHLO->HELO, "-tls -p 25"
ESMTPSA
EHLO->HELO, "-a -tls -p 25"
LMTPLHLO, "-p 24"
LMTPA
LHLO, "-a -p 24"
LMTPS
LHLO, "-tls -p 24"
LMTPSA
LHLO, "-a -tls -p 24"
--pipeline
If the remote server supports it, attempt SMTP PIPELINING (RFC 2920).
(Arg-None)
--prdr
If the server supports it, attempt Per-Recipient Data Response (PRDR)
(<https://tools.ietf.org/html/draft-hall-prdr-00.txt>). PRDR is not
yet standardized, but MTAs have begun implementing the proposal. (Arg-
None)
--force-getpwuid
Tell Swaks to use the system-default method of determining the current
user's username for the default sender local-part instead of trying
$LOGNAME first. Despite the UNIX-ish-specific option name, this op-
tion also works on Windows. (Arg-None)
TLS / ENCRYPTION
These are options related to encrypting the transaction. These have been
tested and confirmed to work with all three transport methods. The
Net::SSLeay module is used to perform encryption when it is requested. If
this module is not loadable Swaks will either ignore the TLS request or
error out, depending on whether the request was optional. STARTTLS is de-
fined as an extension in the ESMTP protocol and will be unavailable if
"--protocol" is set to a variation of plain SMTP. Because it is not de-
fined in the protocol itself, "--tls-on-connect" is available for any pro-
tocol type if the target supports it.
A local certificate is not required for a TLS connection to be negotiated.
However, some servers use client certificate checking to verify that the
client is allowed to connect. Swaks can be told to use a specific local
certificate using the "--tls-cert" and "--tls-key" options, and optionally
to use a certificate chain using the "--tls-chain" option.
-tlsRequire connection to use STARTTLS. Exit if TLS not available for any
reason (not advertised, negotiations failed, etc). (Arg-None)
-tlso, --tls-optional
Attempt to use STARTTLS if available, continue with normal transaction
if TLS was unable to be negotiated for any reason. Note that this is
a semi-useless option as currently implemented because after a negoti-
ation failure the state of the connection is unknown. In some cases,
like a version mismatch, the connection should be left as plaintext.
In others, like a verification failure, the server-side may think that
it should continue speaking TLS while the client thinks it is plain-
text. There may be an attempt to add more granular state detection in
the future, but for now just be aware that odd things may happen with
this option if the TLS negotiation is attempted and fails. (Arg-None)
-tlsos, --tls-optional-strict
Attempt to use STARTTLS if available. Proceed with transaction if TLS
is negotiated successfully or STARTTLS not advertised. If STARTTLS is
advertised but TLS negotiations fail, treat as an error and abort
transaction. Due to the caveat noted above, this is a much saner op-
tion than "--tls-optional". (Arg-None)
-tlsc, --tls-on-connect
Initiate a TLS connection immediately on connection. Following common
convention, if this option is specified the default port changes from
25 to 465, though this can still be overridden with the --port option.
(Arg-None)
-tlsp, --tls-protocol <tls-version-specification>
Specify which protocols to use (or not use) when negotiating TLS. At
the time of this writing, the available protocols are sslv2, sslv3,
tlsv1, tlsv1_1, tlsv1_2, and tlsv1_3. The availability of these pro-
tocols is dependent on your underlying OpenSSL library, so not all of
these may be available. The list of available protocols is shown in
the output of "--dump" (assuming TLS is available at all).
The specification string is a comma-delimited list of protocols that
can be used or not used. For instance 'tlsv1,tlsv1_1' will only suc-
ceed if one of those two protocols is available on both the client and
the server. Conversely, 'no_sslv2,no_sslv3' will attempt to negotiate
any protocol except sslv2 and sslv3. The two forms of specification
cannot be mixed. (Arg-Required)
--tls-cipher <cipher-string>
The argument to this option is passed to the underlying OpenSSL li-
brary to set the list of acceptable ciphers to the be used for the
connection. The format of this string is opaque to Swaks and is de-
fined in <https://www.openssl.org/docs/manmaster/man1/openssl-ci-
phers.html#CIPHER-LIST-FORMAT>. A brief example would be "--tls-ci-
pher '3DES:+RSA'". (Arg-Required)
--tls-verify
Tell Swaks to attempt to verify the server's certificate. This option
is identical to specifying both the "--tls-verify-ca" and "--tls-ver-
ify-host" options. See those options for detailed descriptions of how
to fine-tune each type of verification.
By default, TLS verification is not required. If TLS verification is
required by "--tls-verify", "--tls-verify-ca", or "--tls-verify-host"
and the requested type of verification fails, TLS negotiation will not
succeed. (Arg-None)
--tls-verify-ca
Require that the server's certificate be signed by a known certificate
authority and not be expired. By default the list of known CAs will
be whatever is available via the client Swaks is running on. To pro-
vide a custom CA, see "--tls-ca-path". (Arg-None)
--tls-verify-host
Require that the target of the current connection be listed in the
server certificate's Subject Alternative Name (SAN) or Subject Common-
Name (CN).
The target that Swaks uses for verification will vary. It can be a
hostname, either provided directly via the "--server" option or looked
up via MX records. In this case, verification performs as expected.
If the target is an IP, the IP will be looked up in the certificate,
which is possible but unusual. If the transport is "--pipe" or
"--socket", there will not be a meaningful target to verify in the
certificate and verification will fail. In this situation it's better
to use only "--tls-verify-ca" or to override the target used for veri-
fication with the "--tls-verify-target" option. (Arg-None)
--tls-verify-target <verification-string>
When set, the argument to this option will be used as the host to be
verified for "--tls-verify-host". This is necessary when using
"--tls-verify-host" with either the "--pipe" or "--socket" transports,
which do not have a verifiable target by default. It can also be used
to override the default target lookup when using the "--server" trans-
port. For instance, it can be used to verify that the certificate of
a server explicitly connect to via IP contains a specific certificate.
(Arg-Required)
--tls-ca-path <ca-location>
Specify an alternate location for CA information for verifying server
certificates. The argument can point to a file or directory. The de-
fault behavior is to use the underlying OpenSSL library's default in-
formation. (Arg-Required)
--tls-cert <cert-file>
Provide a path to a file containing the local certificate Swaks should
use if TLS is negotiated. If a certificate chain needs to be pro-
vided, it can be provided via this file or via a separate file with
"--tls-chain". The file path argument is required. As currently im-
plemented the certificate in the file must be in PEM format. Contact
the author if there's a compelling need for ASN1. If this option is
set, "--tls-key" is also required. (Arg-Required)
--tls-key <key-file>
Provide a path to a file containing the local private key Swaks should
use if TLS is negotiated. The file path argument is required. As
currently implemented the certificate in the file must be in PEM for-
mat. Contact the author if there's a compelling need for ASN1. If
this option is set, "--tls-cert" is also required. (Arg-Required)
--tls-chain <chain-file>
Provide a path to a file containing the local certificate chain Swaks
should use if TLS is negotiated. The file path argument is required.
As currently implemented the certificate in the file must be in PEM
format. Contact the author if there's a compelling need for ASN1. If
this option is set, "--tls-cert" and "--tls-key" are also required.
(Arg-Required)
--tls-get-peer-cert [<output-file>]
Get a copy of the TLS peer's certificate. If no argument is given, it
will be displayed to "STDOUT". If an argument is given it is assumed
to be a filesystem path specifying where the certificate should be
written. The saved certificate can then be examined using standard
tools such as the openssl command. If a file is specified its con-
tents will be overwritten. This option will only ever return one cer-
tificate. In order to get every certificate sent by the server, see
"--tls-get-peer-chain". (Arg-Optional)
--tls-get-peer-chain [<output-file>]
Get a copy of the TLS certificate chain sent by the server. If no ar-
gument is given, it will be displayed to "STDOUT". If an argument is
given it is assumed to be a filesystem path specifying where the cer-
tificate should be written. The saved chain can then be examined us-
ing standard tools such as the openssl command. If a file is speci-
fied its contents will be overwritten. See also "--tls-get-peer-cert".
(Arg-Optional)
--tls-sni <sni-string>
Specify the Server Name Indication field to send when the TLS connec-
tion is initiated. (Arg-Required)
AUTHENTICATION
Swaks will attempt to authenticate to the target mail server if instructed
to do so. This section details available authentication types, require-
ments, options and their interactions, and other fine points in authenti-
cation usage. Because authentication is defined as an extension in the
ESMTP protocol it will be unavailable if "--protocol" is set to a varia-
tion of SMTP.
All authentication methods require base64 encoding. If the MIME::Base64
Perl module is loadable Swaks attempts to use it to perform these encod-
ings. If MIME::Base64 is not available Swaks will use its own onboard
base64 routines. These are slower than the MIME::Base64 routines and less
reviewed, though they have been tested thoroughly. Using the MIME::Base64
module is encouraged.
If authentication is required (see options below for when it is and isn't
required) and the requirements aren't met for the authentication type
available, Swaks displays an error and exits. Two ways this can happen
include forcing Swaks to use a specific authentication type that Swaks
can't use due to missing requirements, or allowing Swaks to use any au-
thentication type, but the server only advertises types Swaks can't sup-
port. In the former case Swaks errors out at option processing time since
it knows up front it won't be able to authenticate. In the latter case
Swaks will error out at the authentication stage of the SMTP transaction
since Swaks will not be aware that it will not be able to authenticate un-
til that point.
Following are the supported authentication types including any individual
notes and requirements.
The following options affect Swaks' use of authentication. These options
are all inter-related. For instance, specifying "--auth-user" implies
"--auth" and "--auth-password". Specifying "--auth-optional" implies
"--auth-user" and "--auth-password", etc.
-a, --auth [<auth-type>[,<auth-type>[,...]]]
Require Swaks to authenticate. If no argument is given, any supported
auth-types advertised by the server are tried until one succeeds or
all fail. If one or more auth-types are specified as an argument,
each that the server also supports is tried in order until one suc-
ceeds or all fail. This option requires Swaks to authenticate, so if
no common auth-types are found or no credentials succeed, Swaks dis-
plays an error and exits. (Arg-Optional)
The following tables lists the valid auth-types
LOGIN, PLAIN
These basic authentication types are fully supported and tested
and have no additional requirements
CRAM-MD5
The CRAM-MD5 authenticator requires the Digest::MD5 module. It is
fully tested and believed to work against any server that imple-
ments it.
DIGEST-MD5
The DIGEST-MD5 authenticator (RFC2831) requires the Authen::SASL
module. Version 20100211.0 and earlier used Authen::DigestMD5
which had some protocol level errors which prevented it from work-
ing with some servers. Authen::SASL's DIGEST-MD5 handling is much
more robust.
The DIGEST-MD5 implementation in Swaks is fairly immature. It
currently supports only the "auth" qop type, for instance. If you
have DIGEST-MD5 experience and would like to help Swaks support
DIGEST-MD5 better, please get in touch with me.
The DIGEST-MD5 protocol's "realm" value can be set using the
"--auth-extra" "realm" keyword. If no realm is given, a reason-
able default will be used.
The DIGEST-MD5 protocol's "digest-uri" values can be set using the
"--auth-extra" option. For instance, you could create the digest-
uri-value of "lmtp/mail.example.com/example.com" with the option
"--auth-extra dmd5-serv-type=lmtp,dmd5-host=mail.exam-
ple.com,dmd5-serv-name=example.com". The "digest-uri-value"
string and its components is defined in RFC2831. If none of these
values are given, reasonable defaults will be used.
CRAM-SHA1
The CRAM-SHA1 authenticator requires the Digest::SHA module. This
type has only been tested against a non-standard implementation on
an Exim server and may therefore have some implementation defi-
ciencies.
NTLM/SPA/MSN
These authenticators require the Authen::NTLM module. This type
has been tested against Exim, Communigate, and Exchange 2007.
In addition to the standard username and password, this authenti-
cation type can also recognize a "domain". The domain can be set
using the "--auth-extra" "domain" keyword. Note that this has
never been tested with a mail server that doesn't ignore DOMAIN so
this may be implemented incorrectly.
-ao, --auth-optional [<auth-type>[,<auth-type>[,...]]]
This option behaves identically to "--auth" except that it requests
authentication rather than requiring it. If no common auth-types are
found or no credentials succeed, Swaks proceeds as if authentication
had not been requested. (Arg-Optional)
-aos, --auth-optional-strict [<auth-type>[,<auth-type>[,...]]]
This option is a compromise between "--auth" and "--auth-optional".
If authentication is never attempted (server doesn't advertise authen-
tication or no common authentication types are found), it behaves like
"--auth-optional" and the smtp transaction continues. If authentica-
tion is attempted but fails, it behaves like "--auth" and exits with
an error. (Arg-Optional)
-au, --auth-user [<username>]
Provide the username to be used for authentication. If no username is
provided, indicate that Swaks should attempt to find the username via
.netrc (requires the Net::Netrc module). If no username is provided
and cannot be found via .netrc, the user will be prompted to provide
one. The string "<>" can be supplied to mean an empty username. (Arg-
Required, From-Prompt)
-ap, --auth-password [<password>]
Provide the password to be used for authentication. If no password is
provided, indicate that Swaks should attempt to find the password via
.netrc (requires the Net::Netrc module). If no password is provided
and cannot be found via .netrc, the user will be prompted to provide
one. The string "<>" can be supplied to mean an empty password. (Arg-
Required, From-Prompt, Sensitive)
-ae, --auth-extra <key-value-pair>[,<key-value-pair>[,...]]
Some of the authentication types allow extra information to be in-
cluded in the authentication process. Rather than add a new option
for every nook and cranny of each authenticator, the "--auth-extra"
option allows this information to be supplied. The format for
<key-value-pair> is KEYWORD=VALUE. (Arg-Required)
The following table lists the currently recognized keywords and the
authenticators that use them
realm, domain
The realm and domain keywords are synonymous. Using either will
set the "domain" option in NTLM/MSN/SPA and the "realm" option in
DIGEST-MD5
dmd5-serv-type
The dmd5-serv-type keyword is used by the DIGEST-MD5 authenticator
and is used, in part, to build the digest-uri-value string (see
RFC2831)
dmd5-host
The dmd5-host keyword is used by the DIGEST-MD5 authenticator and
is used, in part, to build the digest-uri-value string (see
RFC2831)
dmd5-serv-name
The dmd5-serv-name keyword is used by the DIGEST-MD5 authenticator
and is used, in part, to build the digest-uri-value string (see
RFC2831)
-am, --auth-map <key-value-pair>[,<key-value-pair>[,...]]
Provides a way to map alternate names onto base authentication types.
Useful for any sites that use alternate names for common types. The
format for <key-value-pair> is AUTH-ALIAS=AUTH-TYPE. This functional-
ity is actually used internally to map types SPA and MSN onto the base
type NTLM. The command line argument to simulate this would be
"--auth-map SPA=NTLM,MSN=NTLM". All of the auth-types listed above
are valid targets for mapping except SPA and MSN. (Arg-Required)
-apt, --auth-plaintext
Instead of showing AUTH strings base64 encoded as they are transmit-
ted, translate them to plaintext before printing on screen. (Arg-None)
-ahp, --auth-hide-password [<replacement-string>]
If this option is specified, any time a readable password would be
printed to the terminal (specifically AUTH PLAIN and AUTH LOGIN) the
password is replaced with the string 'PROVIDED_BUT_REMOVED' (or the
contents of <replacement-string> if provided). The dummy string may
or may not be base64 encoded, contingent on the "--auth-plaintext" op-
tion.
Note that "--auth-hide-password" is similar, but not identical, to the
"--protect-prompt" option. The former protects passwords from being
displayed in the SMTP transaction regardless of how they are entered.
The latter protects sensitive strings when the user types them at the
terminal, regardless of how the string would be used. (Arg-Optional)
XCLIENT OPTIONS
XCLIENT is an SMTP extension introduced by the Postfix project. XCLIENT
allows a (properly-authorized) client to tell a server to use alternate
information, such as IP address or hostname, for the client. This allows
much easier paths for testing mail server configurations. Full details on
the protocol are available at <http://www.post-
fix.org/XCLIENT_README.html>.
The XCLIENT verb can be passed to the server multiple times per SMTP ses-
sion with different attributes. For instance, HELO and PROTO might be
passed in one call and NAME and ADDR passed in a second. Because it can be
useful for testing, Swaks exposes some control over how the attributes are
grouped and in what order they are passed to the server. The different op-
tions attempt to expose simplicity for those using Swaks as a client, and
complexity for those using Swaks to test installs.
--xclient-addr [<string>]
--xclient-name [<string>]
--xclient-port [<string>]
--xclient-proto [<string>]
--xclient-destaddr [<string>]
--xclient-destport [<string>]
--xclient-helo [<string>]
--xclient-login [<string>]
--xclient-reverse-name [<string>]
These options specify XCLIENT attributes that should be sent to the
target server. If <string> is not provided, Swaks will prompt and
read the value on "STDIN". See <http://www.post-
fix.org/XCLIENT_README.html> for official documentation for what the
attributes mean and their possible values, including the special "[UN-
AVAILABLE]" and "[TEMPUNAVAIL]" values.
By way of simple example, setting "--xclient-name foo.example.com
--xclient-addr 192.168.1.1" will cause Swaks to send the SMTP command
"XCLIENT NAME=foo.example.com ADDR=192.168.1.1".
Note that the "REVERSE_NAME" attribute doesn't seem to appear in the
official documentation. There is a mailing list thread that documents
it, viewable at <http://comments.gmane.org/gmane.mail.post-
fix.user/192623>.
These options can all be mixed with each other, and can be mixed with
the "--xclient" option (see below). By default all attributes will be
combined into one XCLIENT call, but see "--xclient-delim". (Arg-Re-
quired, From-Prompt)
--xclient-delim
When this option is specified, it indicates a break in XCLIENT attrib-
utes to be sent. For instance, setting "--xclient-helo 'helo string'
--xclient-delim --xclient-name foo.example.com --xclient-addr
192.168.1.1" will cause Swaks to send two XCLIENT calls, "XCLIENT
HELO=helo+20string" and "XCLIENT NAME=foo.example.com
ADDR=192.168.1.1". This option is ignored where it doesn't make sense
(at the start or end of XCLIENT options, by itself, consecutively,
etc). (Arg-None)
--xclient [<string>]
This is the "free form" XCLIENT option. Whatever value is provided
for <string> will be sent verbatim as the argument to the XCLIENT SMTP
command. For example, if "--xclient 'NAME= ADDR=192.168.1.1 FOO=bar'"
is used, Swaks will send the SMTP command "XCLIENT NAME=
ADDR=192.168.1.1 FOO=bar". If no argument is passed on command line,
Swaks will prompt and read the value on STDIN.
The primary advantage to this over the more specific options above is
that there is no XCLIENT syntax validation here. This allows you to
send invalid XCLIENT to the target server for testing. Additionally,
at least one MTA (Message Systems' Momentum, formerly ecelerity) im-
plements XCLIENT without advertising supported attributes. The
"--xclient" option allows you to skip the "supported attributes" check
when communicating with this type of MTA (though see also
"--xclient-no-verify").
The "--xclient" option can be mixed freely with the "--xclient-*" op-
tions above. The argument to "--xclient" will be sent in its own com-
mand group. For instance, if "--xclient-addr 192.168.0.1
--xclient-port 26 --xclient 'FOO=bar NAME=wind'" is given to Swaks,
"XCLIENT ADDR=192.168.0.1 PORT=26" and "XCLIENT FOO=bar NAME=wind"
will both be sent to the target server. (Arg-Required, From-Prompt)
--xclient-no-verify
Do not enforce the requirement that an XCLIENT attribute must be ad-
vertised by the server in order for Swaks to send it in an XCLIENT
command. This is to support servers which don't advertise the attrib-
utes but still support them. (Arg-None)
--xclient-before-starttls
If Swaks is configured to attempt both XCLIENT and STARTTLS, it will
do STARTTLS first. If this option is specified it will attempt
XCLIENT first. (Arg-None)
--xclient-optional
--xclient-optional-strict
In normal operation, setting one of the "--xclient*" options will re-
quire a successful XCLIENT transaction to take place in order to pro-
ceed (that is, XCLIENT needs to be advertised, all the user-requested
attributes need to have been advertised, and the server needs to have
accepted Swaks' XCLIENT request). These options change that behavior.
"--xclient-optional" tells Swaks to proceed unconditionally past the
XCLIENT stage of the SMTP transaction, regardless of whether it was
successful. "--xclient-optional-strict" is similar but more granular.
The strict version will continue to XCLIENT was not advertised, but
will fail if XCLIENT was attempted but did not succeed. (Arg-None)
PROXY OPTIONS
Swaks implements the Proxy protocol as defined in
<http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt>. Proxy al-
lows an application load balancer, such as HAProxy, to be used in front of
an MTA while still allowing the MTA access to the originating host infor-
mation. Proxy support in Swaks allows direct testing of an MTA configured
to expect requests from a proxy, bypassing the proxy itself during test-
ing.
Swaks makes no effort to ensure that the Proxy options used are internally
consistent. For instance, "--proxy-family" (in version 1) is expected to
be one of "TCP4" or "TCP6". While it will likely not make sense to the
target server, Swaks makes no attempt to ensure that "--proxy-source" and
"--proxy-dest" are in the same protocol family as "--proxy-family" or each
other.
The "--proxy" option is mutually exclusive with all other "--proxy-*" op-
tions except "--proxy-version".
When "--proxy" is not used, all of "--proxy-family", "--proxy-source",
"--proxy-source-port", "--proxy-dest", and "--proxy-dest-port" are re-
quired. Additionally, when "--proxy-version" is 2, "--proxy-protocol" and
"--proxy-command" are optional.
--proxy-version [ 1 | 2 ]
Whether to use version 1 (human readable) or version 2 (binary) of the
Proxy protocol. Version 1 is the default. Version 2 is only imple-
mented through the "address block", and is roughly on par with the in-
formation provided in version 1. (Arg-Required, From-Prompt)
--proxy [<string>]
This option provides the raw proxy string which will be sent to the
server. The protocol prefix ("PROXY " for version 1, the 12-byte pro-
tocol header for version 2) can be present or not in the argument.
This option allows sending incomplete or malformed Proxy strings to a
target server for testing. This option is mutually exclusive with all
other "--proxy-*" options which provide granular proxy information.
Because version 2 of the Proxy protocol is a binary protocol, there
are multiple ways to provide the argument to this option. If the ar-
gument starts with "base64:", that prefix is stripped and the rest of
the string is base64 decoded before use. If the argument starts with
"@" it will be treated as a filename and the proxy value will be read
from the file. Any other value is assumed to be the literal value for
the proxy string. (Arg-Required, From-Prompt, From-File)
--proxy-family [<string>]
For version 1, specifies both the address family and transport proto-
col. The protocol defines TCP4 and TCP6.
For version 2, specifies only the address family. The protocol de-
fines AF_UNSPEC, AF_INET, AF_INET6, and AF_UNIX. (Arg-Required, From-
Prompt)
--proxy-protocol [<string>]
For version 2, specifies the transport protocol. The protocol defines
UNSPEC, STREAM, and DGRAM. The default is STREAM. This option is un-
used in version 1. (Arg-Required, From-Prompt)
--proxy-command [<string>]
For version 2, specifies the transport protocol. The protocol defines
LOCAL and PROXY. The default is PROXY. This option is unused in ver-
sion 1. (Arg-Required, From-Prompt)
--proxy-source [<string>]
Specify the source address of the proxied connection. (Arg-Required,
From-Prompt)
--proxy-source-port [<string>]
Specify the source port of the proxied connection. (Arg-Required,
From-Prompt)
--proxy-dest [<string>]
Specify the destination address of the proxied connection. (Arg-Re-
quired, From-Prompt)
--proxy-dest-port [<string>]
Specify the destination port of the proxied connection. (Arg-Required,
From-Prompt)
DATA OPTIONS
These options pertain to the contents for the DATA portion of the SMTP
transaction. By default a very simple message is sent. If the "--attach"
or "--attach-body" options are used, Swaks attempts to upgrade to a MIME
message.
-d, --data [<data-portion>]
Use argument as the entire contents of DATA.
If no argument is provided, user will be prompted to supply value.
If the argument "-" is provided the data will be read from "STDIN"
with no prompt.
If the argument starts with "@" it will be treated as a filename. If
you would like to pass in an argument that starts with "@" and isn't a
filename, prefix the argument with an additional "@". For example,
"@file.txt" will force processing of file.txt. @@data will use the
string '@data'.
If the argument does not contain any literal (0x0a) or representative
(0x5c, 0x6e or %NEWLINE%) newline characters, it will be treated as a
filename. If the file is open-able, the contents of the file will be
used as the data portion. If the file cannot be opened, Swaks will
error and exit. The entire behavior described in this paragraph is
deprecated and will be removed in a future release. Instead use a
leading "@" to explicitly set that the argument is a filename.
Any other argument will be used as the DATA contents.
The value can be on one single line, with "\n" (ASCII 0x5c, 0x6e) rep-
resenting where line breaks should be placed. Leading dots will be
quoted. Closing dot is not required but is allowed. The default
%FROM_ADDRESS%\nSubject: test %DATE%\nMessage-Id: <%MES-
SAGEID%>\nX-Mailer: swaks v%SWAKS_VERSION% jet-
more.org/john/code/swaks/\n%NEW_HEADERS%\n%BODY%\n".
Very basic token parsing is performed on the DATA portion. The fol-
lowing table shows the recognized tokens and their replacement values.
(Arg-Required, From-Prompt, From-File)
%FROM_ADDRESS%, ..FROM_ADDRESS..
Replaced with the envelope-sender.
%TO_ADDRESS%, ..TO_ADDRESS..
Replaced with the envelope-recipient(s) set by the "--to" option.
%CC_ADDRESS%, ..CC_ADDRESS..
Replaced with the envelope-recipient(s) set by the "--cc" option.
%BCC_ADDRESS%, ..BCC_ADDRESS..
Replaced with the envelope-recipient(s) set by the "--bcc" option.
%DATE%, ..DATE..
Replaced with the current time in a format suitable for inclusion
ule POSIX for timezone calculations. If this module is unavail-
able or the current environment doesn't support the %z strftime
format token (as on Windows) the date string will be in GMT.
%MESSAGEID%, ..MESSAGEID..
Replaced with a message ID string suitable for use in a Message-Id
header. The value for this token will remain consistent for the
life of the process.
%SWAKS_VERSION%, ..SWAKS_VERSION..
Replaced with the version of the currently-running Swaks process.
%NEW_HEADERS%, ..NEW_HEADERS..
Replaced with the contents of the "--add-header" option. If
"--add-header" is not specified this token is simply removed.
%BODY%, ..BODY..
Replaced with the value specified by the "--body" option. See
"--body" for default.
%NEWLINE%, ..BODY..
Replaced with carriage return, newline (0x0d, 0x0a). This is
identical to using "\n" (0x5c, 0x6e), but doesn't have the escap-
ing concerns that the backslash can cause on the newline.
-dab, --dump-as-body [<section>[,<section>[,...]]]
If "--dump-as-body" is used and no other option is used to change the
default body of the message, the body is replaced with output similar
to the output of what is provided by "--dump". "--dump"'s initial
program capability stanza is not displayed, and the "data" section is
not included. Additionally, "--dump" always includes passwords. By
default "--dump-as-body" does not include passwords, though this can
be changed with "--dump-as-body-shows-password". "--dump-as-body"
takes the same arguments as "--dump" except the SUPPORT and DATA argu-
ments are not supported. (Arg-Optional)
-dabsp, --dump-as-body-shows-password
Cause "--dump-as-body" to include plaintext passwords. This option is
not recommended. This option implies "--dump-as-body". (Arg-None)
--body [<body-specification>]
Specify the body of the email. The default is "This is a test mail-
ing". If no argument to "--body" is given, prompt to supply one in-
teractively. If "-" is supplied, the body will be read from standard
input. Arguments beginning with "@" will be treated as filenames con-
taining the body data to use (see "--data" for more detail).
If, after the above processing, the argument represents an open-able
file, the content of that file is used as the body. This is depre-
cated behavior and will be removed in a future release. Instead use a
leading "@" to explicitly set that the argument is a filename.
If the message is forced to MIME format (see "--attach") "--body 'body
text'" is the same as "--attach-type text/plain --attach-body 'body
text'". See "--attach-body" for details on creating a multipart/al-
ternative body. (Arg-Required, From-Prompt, From-File)
--attach [<attachment-specification>]
When one or more "--attach" option is supplied, the message is changed
into a multipart/mixed MIME message. The arguments to "--attach" are
processed the same as "--body" with respect to "STDIN", file contents,
etc. "--attach" can be supplied multiple times to create multiple at-
tachments. By default, each attachment is attached as an applica-
tion/octet-stream file. See "--attach-type" for changing this behav-
ior.
If the contents of the attachment are provided via a file name, the
MIME encoding will include that file name. See "--attach-name" for
more detail on file naming.
It is legal for "-" ("STDIN") to be specified as an argument multiple
times (once for "--body" and multiple times for "--attach"). In this
case, the same content will be attached each time it is specified.
This is useful for attaching the same content with multiple MIME
types. (Arg-Required, From-File)
--attach-body [<body-specification>]
This is a variation on "--attach" that is specifically for the body
part of the email. It behaves identically to "--attach" in that it
takes the same arguments and forces the creation of a MIME message.
However, it is different in that the argument will always be the first
MIME part in the message, no matter where in option processing order
it is encountered. Additionally, "--attach-body" options stack to al-
low creation of multipart/alternative bodies. For example, "--at-
tach-type text/plain --attach-body 'plain text body' --attach-type
text/html --attach-body 'html body'" would create a multipart/alterna-
tive message body. (Arg-Required, From-File)
--attach-type <mime-type>
By default, content that gets MIME attached to a message with the
"--attach" option is encoded as application/octet-stream (except for
the body, which is text/plain by default). "--attach-type" changes
the mime type for every "--attach" option which follows it. It can be
specified multiple times. The current MIME type gets reset to appli-
cation/octet-stream between processing body parts and other parts.
(Arg-Required)
--attach-name [<name>]
This option sets the filename that will be included in the MIME part
created for the next "--attach" option. If no argument is set for
this option, it causes no filename information to be included for the
next MIME part, even if Swaks could generate it from the local file
name. (Arg-Optional)
-ah, --add-header <header>
This option allows headers to be added to the DATA. If "%NEW_HEAD-
ERS%" is present in the DATA it is replaced with the argument to this
option. If "%NEW_HEADERS%" is not present, the argument is inserted
between the first two consecutive newlines in the DATA (that is, it is
inserted at the end of the existing headers).
The option can either be specified multiple times or a single time
with multiple headers separated by a literal "\n" string. So,
"--add-header 'Foo: bar' --add-header 'Baz: foo'" and "--add-header
'Foo: bar\nBaz: foo'" end up adding the same two headers. (Arg-Re-
quired)
--header <header-and-data>, --h-<header> <data>
These options allow a way to change headers that already exist in the
DATA. "--header 'Subject: foo'" and "--h-Subject foo" are equivalent.
If the header does not already exist in the data then this argument
behaves identically to "--add-header". However, if the header already
exists it is replaced with the one specified. Negating the version of
this option with the header name in the option (eg "--no-header-Sub-
ject") will remove all previously processed "--header" options, not
just the ones used for 'Subject'. Embedding the header name in the op-
tion via environment variable is not supported on Windows and will re-
sult in an error. (Arg-Required)
-g This option is a direct alias to "--data -" (read DATA from "STDIN").
It is totally secondary to "--data". Any occurrence of "--data" will
cause "-g" to be ignored. This option cannot be negated with the
"no-" prefix. This option is deprecated and will be removed in a fu-
ture version of Swaks. (Arg-None, Deprecated)
--no-data-fixup, -ndf
This option forces Swaks to do no massaging of the DATA portion of the
email. This includes token replacement, From_ stripping, trailing-dot
addition, "--body"/attachment inclusion, and any header additions.
This option is only useful when used with "--data", since the internal
default DATA portion uses tokens. (Arg-None)
--no-strip-from, -nsf
Don't strip the From_ line from the DATA portion, if present. (Arg-
None)
OUTPUT OPTIONS
Swaks provides a transcript of its transactions to its caller ("STD-
OUT"/"STDERR") by default. This transcript aims to be as faithful a rep-
resentation as possible of the transaction though it does modify this out-
put by adding informational prefixes to lines and by providing plaintext
versions of TLS transactions
The "informational prefixes" are referred to as transaction hints. These
hints are initially composed of those marking lines that are output of
Swaks itself, either informational or error messages, and those that indi-
cate a line of data actually sent or received in a transaction. This ta-
ble indicates the hints and their meanings:
"==="
Indicates an informational line generated by Swaks.
"***"
Indicates an error generated within Swaks.
" ->"
Indicates an expected line sent by Swaks to target server.
" ~>"
Indicates a TLS-encrypted, expected line sent by Swaks to target
server.
"**>"
Indicates an unexpected line sent by Swaks to the target server.
"*~>"
Indicates a TLS-encrypted, unexpected line sent by Swaks to target
server.
" >"
Indicates a raw chunk of text sent by Swaks to a target server (see
"--show-raw-text"). There is no concept of "expected" or "unexpected"
at this level.
"<- "
Indicates an expected line sent by target server to Swaks.
"<~ "
Indicates a TLS-encrypted, expected line sent by target server to
Swaks.
"<**"
Indicates an unexpected line sent by target server to Swaks.
"<~*"
Indicates a TLS-encrypted, unexpected line sent by target server to
Swaks.
"< "
Indicates a raw chunk of text received by Swaks from a target server
(see "--show-raw-text"). There is no concept of "expected" or "unex-
pected" at this level.
The following options control what and how output is displayed to the
caller.
-n, --suppress-data
Summarizes the DATA portion of the SMTP transaction instead of print-
ing every line. This option is very helpful, bordering on required,
when using Swaks to send certain test emails. Emails with attach-
ments, for instance, will quickly overwhelm a terminal if the DATA is
not suppressed. (Arg-None)
-stl, --show-time-lapse [i]
Display time lapse between send/receive pairs. This option is most
useful when Time::HiRes is available, in which case the time lapse
will be displayed in thousandths of a second. If Time::HiRes is un-
available or "i" is given as an argument the lapse will be displayed
in integer seconds only. (Arg-Optional)
Don't display the transaction hint for informational transactions.
This is most useful when needing to copy some portion of the informa-
tional lines, for instance the certificate output from
"--tls-get-peer-cert". (Arg-None)
-nih, --no-info-hints
-nsh, --no-send-hints
-nrh, --no-receive-hints
-nth, --no-hints
"--no-info-hints", "--no-send-hints", and "--no-receive-hints" sup-
press the transaction hints from info, send, and receive lines, re-
spectively. This is often useful when copying some portion of the
transaction for use elsewhere (for instance, "--no-send-hints
--hide-receive --hide-informational" is a useful way to get only the
client-side commands for a given transaction and "--no-info-hints
--tls-get-peer-cert" for copying the peer certificate). "--no-hints"
is identical to specifying "--no-info-hints --no-send-hints --no-re-
ceive-hints". (Arg-None)
-raw, --show-raw-text
This option will print a hex dump of raw data sent and received by
Swaks. Each hex dump is the contents of a single read or write on the
network. This should be identical to what is already being displayed
(with the exception of the "\r" characters being removed). This op-
tion is useful in seeing details when servers are sending lots of data
in single packets, or breaking up individual lines into multiple pack-
ets. If you really need to go in depth in that area you're probably
better with a packet sniffer, but this option is a good first step to
seeing odd connection issues. (Arg-None)
--output, --output-file <file-path>
--output-file-stdout <file-path>
--output-file-stderr <file-path>
These options allow the user to send output to files instead of "STD-
OUT"/"STDERR". The first option sends both to the same file. The ar-
guments of &STDOUT and &STDERR are treated specially, referring to the
"normal" file handles, so "--output-file-stderr '&STDOUT'" would redi-
rect "STDERR" to "STDOUT". These options are honored for all output
except "--help" and "--version". (Arg-Required)
-pp, --protect-prompt
Don't echo user input on prompts that are potentially sensitive (right
now only authentication password). Very specifically, any option
which is marked 'Sensitive' and eventually prompts for an argument
will do its best to mask that argument from being echoed. See also
"--auth-hide-password". (Arg-None)
-hr, --hide-receive
Don't display lines sent from the remote server being received by
Swaks. (Arg-None)
-hs, --hide-send
Don't display lines being sent by Swaks to the remote server. (Arg-
None)
-hi, --hide-informational
Don't display non-error informational lines from Swaks itself. (Arg-
None)
-ha, --hide-all
Do not display any content to the terminal. (Arg-None)
-S, --silent [ 1 | 2 | 3 ]
Cause Swaks to be silent. If no argument is given or if an argument
of "1" is given, print no output unless/until an error occurs, after
which all output is shown. If an argument of "2" is given, only print
errors. If "3" is given, show no output ever. "--silent" affects
most output but not all. For instance, "--help", "--version",
"--dump", and "--dump-mail" are not affected. For historical reasons,
-S is not settable via environment variable on Windows, use
SWAKS_OPT_silent instead. (Arg-Optional)
--support
Print capabilities and exit. Certain features require non-standard
Perl modules. This option evaluates whether these modules are present
and displays which functionality is available and which isn't, and
which modules would need to be added to gain the missing functional-
ity. (Arg-None)
--dump-mail
Cause Swaks to process all options to generate the message it would
send, then print that message to "STDOUT" instead of sending it. This
output is identical to the "data" section of "--dump", except without
the trailing dot. (Arg-None)
--dump [<section>[,<section>[,...]]]
This option causes Swaks to print the results of option processing,
immediately before mail would have been sent. No mail will be sent
when "--dump" is used. Note that "--dump" is a pure self-diagnosis
tool and no effort is made or will ever be made to mask passwords in
the "--dump" output. If a section is provided as an argument to this
option, only the requested section will be shown. Currently supported
arguments are SUPPORT, APP, OUTPUT, TRANSPORT, PROTOCOL, XCLIENT,
PROXY, TLS, AUTH, DATA, and ALL. If no argument is provided, all sec-
tions are displayed (Arg-Optional)
--help
Display this help information and exit. (Arg-None)
--version
Display version information and exit. (Arg-None)
DEPRECATIONS
The following features are deprecated and will be removed in a future ver-
sion of Swaks
use of IO::Socket and IO::Socket::INET6 modules
Will be removed no sooner than (February 1, 2025).
The primary method of sending over IPv4 and IPv6 sockets is imple-
mented with the IO::Socket::IP module. For the time being there is
still legacy support of the IO::Socket and IO::Socket::INET6 modules
which were previously used. Please ensure IO::Socket::IP is installed
to ensure future functionality.
PORTABILITY
OPERATING SYSTEMS
This program was primarily intended for use on UNIX-like operating
systems, and it should work on any reasonable version thereof. It has
been developed and tested on Solaris, Linux, and Mac OS X and is fea-
ture complete on all of these.
This program is known to demonstrate basic functionality on Windows
using Strawberry Perl. In all documentation, unless otherwise noted,
"Windows" refers to running Swaks via CMD.exe, not WSL or cygwin. It
has not been fully tested, but known to work are basic SMTP function-
ality and the LOGIN, PLAIN, and CRAM-MD5 auth types. Unknown is any
TLS functionality and the NTLM/SPA and DIGEST-MD5 auth types. Some
functionality is known to be limited on Windows, including inability
to embed header name in environment variables (see "CONFIGURATION EN-
VIRONMENT VARIABLES" and "--header"), inability to generate a local-
timezone date string (see "%DATE%" token under "--data"), inability to
use "-S" option as an environment variable (see "--silent"), and in-
ability to have a "set but empty" value in an environment variable
(see "CONFIGURATION ENVIRONMENT VARIABLES" for workaround).
Because this program should work anywhere Perl works, I would appreci-
ate knowing about any new operating systems you've thoroughly used
Swaks on as well as any problems encountered on a new OS.
MAIL SERVERS
This program was almost exclusively developed against Exim mail
servers. It has been used casually by the author, though not thor-
oughly tested, with Sendmail, Smail, Exchange, Oracle Collaboration
Suite, qpsmtpd, and Communigate. Because all functionality in Swaks
is based on known standards it should work with any fairly modern mail
server. If a problem is found, please alert the author at the address
below.
ENVIRONMENT VARIABLES
LOGNAME
If Swaks must create a sender address, $LOGNAME is used as the message
local-part if it is set, and unless "--force-getpwuid" is used.
SWAKS_HOME
Used when searching for a .swaksrc configuration file. See OPTION
PROCESSING -> "CONFIGURATION FILES" above.
SWAKS_OPT_*
Environment variable prefix used to specify Swaks options from envi-
ronment variables. See OPTION PROCESSING -> "CONFIGURATION ENVIRON-
MENT VARIABLES" above.
EXIT CODES
0 no errors occurred
1 error parsing command line options
2 error connecting to remote server
3 unknown connection type
4 while running with connection type of "pipe", fatal problem writing to
or reading from the child process
5 while running with connection type of "pipe", child process died unex-
pectedly. This can mean that the program specified with "--pipe"
doesn't exist.
6 Connection closed unexpectedly. If the close is detected in response
to the 'QUIT' Swaks sends following an unexpected response, the error
code for that unexpected response is used instead. For instance, if a
mail server returns a 550 response to a MAIL FROM: and then immedi-
ately closes the connection, Swaks detects that the connection is
closed, but uses the more specific exit code 23 to detail the nature
of the failure. If instead the server return a 250 code and then im-
mediately closes the connection, Swaks will use the exit code 6 be-
cause there is not a more specific exit code.
10 error in prerequisites (needed module not available)
21 error reading initial banner from server
22 error in HELO transaction
23 error in MAIL transaction
24 no RCPTs accepted
25 server returned error to DATA request
26 server did not accept mail following data
27 server returned error after normal-session quit request
28 error in AUTH transaction
29 error in TLS transaction
30 PRDR requested/required but not advertised
32 error in EHLO following TLS negotiation
33 error in XCLIENT transaction
34 error in EHLO following XCLIENT
35 error in PROXY option processing
36 error sending PROXY banner
ABOUT THE NAME
The name "Swaks" is a (sort-of) acronym for "SWiss Army Knife SMTP". It
was chosen to be fairly distinct and pronounceable. While "Swaks" is
unique as the name of a software package, it has some other, non-software
meanings. Please send in other uses of "swak" or "swaks" for inclusion.
"Sealed With A Kiss"
SWAK/SWAKs turns up occasionally on the internet with the meaning
"with love".
bad / poor / ill (Afrikaans)
Seen in the headline "SA se bes en swaks gekledes in 2011", which was
translated as "best and worst dressed" by native speakers. Google
Translate doesn't like "swaks gekledes", but it will translate "swak"
as "poor" and "swak geklede" as "ill-dressed".
LICENSE
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option)
any later version.
This program is distributed in the hope that it will be useful, but WITH-
OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc., 51
Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
CONTACT INFORMATION
General contact, questions, patches, requests, etc to proj-swaks@jet-
more.net.
Change logs, this help, and the latest version are found at
<http://www.jetmore.org/john/code/swaks/>.
Swaks is crafted with love by John Jetmore from the cornfields of Indiana,
United States of America.
NOTIFICATIONS
Email
[email protected]
If you would like to be put on a list to receive notifications when a
new version of Swaks is released, please send an email to this ad-
dress. There will not be a response to your email.
Website
<http://www.jetmore.org/john/blog/c/swaks/>
RSS Feed
<http://www.jetmore.org/john/blog/c/swaks/feed/>
Twitter
<http://twitter.com/SwaksSMTP>
perl v5.40.0 2024-12-07 SWAKS(1)
Updated on: 2026-May-25