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, configuration files, and
the command line allowing maximum configurability and ease of use for
operators and scripters.
QUICK START¶
Deliver a standard test email to user@example.com on port 25 of
test-server.example.net:
swaks --to user@example.com --server test-server.example.net
Deliver a standard test email, requiring CRAM-MD5 authentication as user
me@example.com. An "X-Test" header will be added to the email body.
The authentication password will be prompted for.
swaks --to user@example.com --from me@example.com --auth CRAM-MD5 --auth-user me@example.com --header-X-Test "test email"
Test a virus scanner using EICAR in an attachment. Don't show the message DATA
part.:
swaks -t user@example.com --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 user@example.com --body /path/to/gtube/file
Deliver a standard test email to user@example.com using the LMTP protocol via a
UNIX domain socket file
swaks --to user@example.com --socket /var/lda.sock --protocol LMTP
Report all the recipients in a text file that are non-verifyiable 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 following
terms to reduce confusion.
- 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.
- 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.
- 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 specific
'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 message. It can also be referred to as its components, envelope-sender
and envelope-recipients. It is important to note that a messages envelope
does not have to match its To: and From: headers.
- DATA
- The 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 use synonymously, but they are always 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.
- Body
- A message's body is the portion of its DATA section following the first
blank line.
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 additional data is referred to as an argument to the option. For example,
"--from fred@example.com" might be provided to swaks on the command
line, with "--from" being the option and
"fred@example.com" being --from's argument.
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 or not 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 earlier will be
overridden. Additionally, any option can be prefixed with "no-" to
cause swaks to forget that the variable had previously been set. This
capability is necessary because many options treat defined-but-no-argument
differently than not-defined.
The exact mechanism and format for using each of the types is listed below.
- CONFIGURATION FILE
- 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 configuration file, overriding any
default that may exist. If it points to a non-readable file and 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 present and 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. 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 a 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 included literally in the argument. Here
is an example of the contents of a configuration file:
# always use this sender, no matter server or logged in user
--from fred@example.com
# 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" <fred@example.com>
- 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='fred@example.com'
$ SWAKS_OPT_h_From='"Fred Example" <fred@example.com>'
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 use for the
server to which to connect at each invocation.
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 fred@example.com --h-From: '"Fred Example" <fred@example.com>'
TRANSPORTS¶
swaks can connect to a target via unix pipes ("pipes"), unix domain
sockets ("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 following 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 recipient's domain (see
--server below for more details).
This transport requires the IO::Socket module which is part of the standard
perl distribution. If this module is not loadable, attempting to use a
this transport will result in an error and program termination.
IPv6 is supported when the IO::Socket::INET6 module is present.
- -s, --server [target mail server[:port]]
- Explicitly tell swaks to use network sockets and specify the hostname or
IP address to which to connect, or prompt if no argument is given. If this
option is not given and no other transport option is given, the target
mail server is determined from the appropriate DNS records for the domain
of the recipient email address 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 include
SERVER:PORT (supporting names and IPv4 addresses); [SERVER]:PORT and
SERVER/PORT (supporting names, IPv4 and IPv6 addresses). See also
--copy-routing.
- -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 retrieved by
getservbyname(3)) or a port number. The default port is determined
by the --protocol option. See --protocol for more details.
- -li, --local-interface [IP or hostname[:port]]
- Use argument as the local interface for the outgoing SMTP connection, 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 local
interface. See --server for additional comments on :port format.
- -lp, --local-port [port]
- Specify the outgoing port to originate the transaction from. If this
option is not specified the system will pick an ephemeral port. Note that
regular users cannot specify some ports.
- --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 an recipient email address. See --to
option for more details on how the target is determined from the email
domain.
- -4, -6
- Force IPv4 or IPv6.
- 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 module which is part of the standard perl
distribution. If this module is not loadable, attempting to use this
transport will result in an error and program termination.
- --socket [/path/to/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.
- 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 testing 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"'. In an ideal world 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 the real world 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, attempting to use this
transport will result in an error and program termination.
- --pipe [/path/to/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.
PROTOCOL OPTIONS¶
These options are related to the protocol layer.
- -t, --to [email-address[,email-address,...]]
- Tells swaks to use argument(s) as the envelope-recipient for the email, or
prompt for recipient if no argument provided. If multiple recipients are
provided and the recipient domain is needed to determine routing the
domain of the last recipient provided is used.
There is no default value for this option. If no recipients are provided via
any means, user will be prompted to provide one interactively. 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.
- -f, --from [email-address]
- Use argument as envelope-sender for email, or prompt user if no argument
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 determining the local-part
varies. On Windows, Win32::LoginName() is used. On unix-ish
platforms, the $LOGNAME environment variable is used if it is set.
Otherwise getpwuid(3) is used. See also --force-getpwuid.
- --ehlo, --lhlo, -h, --helo [helo-string]
- String to use as argument to HELO/EHLO/LHLO command, or prompt use 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 the
Sys::Hostname module, which is part of the base distribution, is not
available the user will be prompted for a HELO value. Note that
Sys::Hostname has been observed to not be able to find the local hostname
in certain circumstances. This has the same effect as if Sys::Hostname
were unavailable.
- -q, --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 arguments and
notes about their meaning.
- 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 sent
- TLS
- Quit the transaction immediately following TLS negotiation. Note that this
happens in different places depending on whether STARTTLS 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.
- AUTH
- Quit 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.
- --timeout [time]
- Use argument as the SMTP transaction timeout, or prompt user if no
argument given. Argument can either be a pure digit, which will be
interpretted as seconds, or can have a specifier s or m (5s = 5 seconds,
3m = 180 seconds). As a special case, 0 means don't timeout the
transactions. Default value is 30s.
- --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 attempted, and the type of
TLS connection that should be attempted. The default protocol is ESMTP.
This table demonstrates the available arguments to --protocol and the
options each sets as a side effect:
- SMTP
- HELO, "-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"
- LMTP
- LHLO, "-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). This
is a younger option, if you experience problems with it please notify the
author. Potential problem areas include servers accepting DATA even though
there were no valid recipients (swaks should send empty body in that case,
not QUIT) and deadlocks caused by sending packets outside the tcp window
size.
- --force-getpwuid
- Tell swaks to use the getpwuid method of finding the default sender
local-part instead of trying $LOGNAME first.
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 defined as an extension in the
ESMTP protocol and will be unavailable if --protocol is set to a variation of
smtp. Because it is not defined in the protocol itself, --tls-on-connect is
available for any protocol 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 through the use of the --tls-cert and --tls-key options.
- -tls
- Require connection to use STARTTLS. Exit if TLS not available for any
reason (not advertised, negotiations failed, etc).
- -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 negotiation
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 plaintext. 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.
- -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 more sane
option than --tls-optional.
- --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.
- -tlsp, --tls-protocol 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, and tlsv1_2. The availability of these protocols 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 succeed 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.
- -tls-cipher CIPHER_STRING
- Th argument to this option is passed to the underlying OpenSSL library 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 defined in
http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT. An brief
example would be --tls-cipher '3DES:+RSA'.
- --tls-verify
- By default swaks does not do any certificate verification. Setting
--tls-verify will cause swaks to attempt to verify the server's
certificate. If this option is set and the server's certificate is not
verifiable (either using the system-default CA information, or custom CA
information (see --tls-ca-path)) TLS negotiation will not succeed.
- --tls-ca-path [ /path/to/CAfile | /path/to/CAdir/ ]
- By default swaks will use the underlying OpenSSL library's default CA
information for verifying server certificates. --tls-ca-path allows you to
specify an alternate location. See
http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html for
details of the file/directory contents.
- --tls-cert /path/to/file
- Provide a path to a file containing the local certificate 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-key is also required.
- --tls-key /path/to/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 format. Contact the
author if there's a compelling need for ASN1. If this option is set,
--tls-cert is also required.
- --tls-get-peer-cert [/path/to/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 contents will be
overwritten.
AUTHENTICATION¶
swaks will attempt to authenticate to the target mail server if instructed to do
so. This section details available authentication types, requirements, options
and their interactions, and other fine points in authentication usage. Because
authentication is defined as an extension in the ESMTP protocol it will be
unavailable if --protocol is set to a variation of smtp.
All authentication methods require base64 encoding. If the MIME::Base64 perl
module is loadable swaks attempts to use it to perform these encodings. 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 authentication type, but
the server only advertises types swaks can't support. 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 until 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 succeeds or all fail.
This option requires swaks to authenticate, so if no common auth-types are
found or no credentials succeed, swaks displays an error and exits.
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 implements 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 working 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 reasonable
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.example.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 deficiencies.
- NTLM/SPA/MSN
- These authenticators require the Authen::NTLM module. Note that there are
two modules using the Authen::NTLM namespace on CPAN. The Mark Bush
implementation (Authen/NTLM-1.03.tar.gz) is the version required by swaks.
This type has been tested against Exim, Communigate, and Exchange 2007.
In addition to the standard username and password, this authentication 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.
- -aos, --auth-optional-strict [auth-type[,auth-type,...]]
- This option is a compromise between --auth and --auth-optional. If no
common auth-types are found, swaks behaves as if --auth-optional were
specified and proceeds with the transaction. If swaks can't support
requested auth-type, the server doesn't advertise any common auth-types,
or if no credentials succeed, swaks behaves as if --auth were used and
exits with an error.
- -au, --auth-user [username]
- Provide the username to be used for authentication, or prompt the user for
it if no argument is provided. The string <> can be supplied to mean
an empty username.
- -ap, --auth-password [password]
- Provide the password to be used for authentication, or prompt the user for
it if no argument is provided. The string <> can be supplied to mean
an empty password.
- -ae, --auth-extra [KEYWORD=value[,...]]
- Some of the authentication types allow extra information to be included 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 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 [auth-alias=auth-type[,...]]
- Provides a way to map alternate names onto base authentication types.
Useful for any sites that use alternate names for common types. This
functionality 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.
- -apt, --auth-plaintext
- Instead of showing AUTH strings base64 encoded as they are transmitted,
translate them to plaintext before printing on screen.
- -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 a dummy string (or the contents of "replacement
string" if provided). The dummy string will be base64 encoded or not
contingent on the --auth-plaintext option.
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.
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.postfix.org/XCLIENT_README.html.
- --xclient-addr [VALUE]
- --xclient-name [VALUE]
- --xclient-port [VALUE]
- --xclient-proto [VALUE]
- --xclient-helo [VALUE]
- --xclient-login [VALUE]
- --xclient-reverse-name [VALUE]
- These options specify XCLIENT attrubutes that should be sent to the target
server. If [VALUE] is not provided, swaks will prompt and read the value
on STDIN. See http://www.postfix.org/XCLIENT_README.html for official
documentation for what the attributes mean and their possible values,
including the special "[UNAVAILABLE]" 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.postfix.user/192623.
These options can all be mixed with each other, and can be mixed with the
--xclient option (see below).
- --xclient [XCLIENT_STRING]
- This is the "free form" XCLIENT option. Whatever value is
provided for XCLIENT_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". 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. If no XCLIENT_STRING is passed on command line,
swaks will prompt and read the value on STDIN.
The --xclient option can be mixed freely with the --xclient-* options above.
If "--xclient-addr 192.168.0.1 --xclient 'FOO=bar NAME=wind'" is
given to swaks, "XCLIENT ADDR=192.168.0.1 FOO=bar NAME=wind"
will be sent to the target server.
- --xclient-optional
- --xclient-optional-strict
- In normal operation, setting one of the --xclient* options will cause a
successful XCLIENT transaction to take place in order to proceed (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.
DATA OPTIONS¶
These options pertain to the contents for the DATA portion of the SMTP
transaction.
- -d, --data [data-portion]
- Use argument as the entire contents of DATA, or prompt user if no argument
specified. If the argument '-' is provided the data will be read from
STDIN. If any other argument is provided and it represents the name of an
open-able file, the contents of the file will be used. Any other argument
will be itself for the DATA contents.
The value can be on one single line, with \n (ascii 0x5c, 0x6e) representing
where line breaks should be placed. Leading dots will be quoted. Closing
dot is not required but is allowed. The default value for this option is
"Date: %DATE%\nTo: %TO_ADDRESS%\nFrom: %FROM_ADDRESS%\nSubject: test
%DATE%\nX-Mailer: swaks v$p_version
jetmore.org/john/code/swaks/\n%NEW_HEADERS%\n%BODY%\n".
Very basic token parsing is performed on the DATA portion. See
--use-old-data-tokens for details about the single-character tokens marked
as deprecated. The following table shows the recognized tokens and their
replacement values:
- %FROM_ADDRESS%
- Replaced with the envelope-sender. Replaces the deprecated %F token.
- %TO_ADDRESS%
- Replaced with the envelope-recipient(s). Replaces the deprecated %T
token.
- %DATE%
- Replaced with the current time in a format suitable for inclusion in the
Date: header. Note this attempts to use the standard module Time::Local
for timezone calculations. If this module is unavailable the date string
will be in GMT. Replaces the deprecated %D token.
- %NEW_HEADERS%
- Replaced with the contents of the --add-header option. If --add-header is
not specified this token is simply removed. Replaces the deprecated %H
token.
- %BODY%
- Replaced with the value specified by the --body option. See --body for
default. Replaces the deprecated %H token.
- --use-old-data-tokens
- In previous versions of swaks the DATA tokens as described in the --data
option above used single-character tokens (e.g., %F). These were not a
great choice for default tokens, and proved especially troublesome with
encoded, non-english languages where these character combinations might be
common. The single-character tokens were replaced with the
slightly-less-error-prone versions listed above. The retention of the old
tokens and the inclusion of this option to activate them are intended as a
temporary aid to users who have an existing message corpus using the old
tokens. The single-character tokens and the --use-old-data-tokens option
should be considered deprecated and likely to be removed in the next
release.
- -dab, --dump-as-body
- If --dump-as-body is used and no other option is used to changed 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.
- -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.
- --body [body-specification]
- Specify the body of the email. The default is "This is a test
mailing". If no argument to --body is given, prompt to supply one
interactively. If '-' is supplied, the body will be read from standard
input. If any other text is provided and the text represents an open-able
file, the content of that file is used as the body. If it does not
represent an open-able file, the text itself is used as the body.
If the message is forced to MIME format (see --attach) the argument to this
option will be included unencoded as the first MIME part. Its content-type
will always be text/plain.
- --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 regard to stdin, file contents, etc. --attach can
be supplied multiple times to create multiple attachments. By default each
attachment is attached as a application/octet-stream file. See
--attach-type for changing this behavior.
If a filename is specified, 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.
- --attach-type [mime-type]
- By default, content that gets MIME attached to a message with the --attach
option is encoded as application/octet-stream. --attach-type changes the
mime type for every --attach option which follows it. It can be specified
multiple times.
- --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.
- -ah, --add-header [header]
- This option allows headers to be added to the DATA. If %H is present in
the DATA it is replaced with the argument to this option. If %H 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.
- --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.
- -g
- If specified, swaks will read the DATA value for the mail from STDIN. This
is equivalent to "--data -". If there is a From_ line in the
email, it will be removed (but see -nsf option). Useful for delivering
real message (stored in files) instead of using example messages.
- --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 really only useful when used with --data, since the internal
default DATA portion uses tokens.
- --no-strip-from, -nsf
- Don't strip the From_ line from the DATA portion, if present.
OUTPUT OPTIONS¶
By default swaks provides a transcript of its transactions to its caller
(STDOUT/STDERR). This transcript aims to be as faithful a representation as
possible of the transaction though it does modify this output 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 indicate
a line of data actually sent or received in a transaction. This table
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 test 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
"unexpected" 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 printing
every line. This option is very helpful, bordering on required, when using
swaks to send certain test emails. Emails with attachments, for instance,
will quickly overwhelm a terminal if the DATA is not supressed.
- -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 unavailable or
"i" is given as an argument the lapse will be displayed in
integer seconds only.
- -nih, --no-info-hints
- Don't display the transaction hint for informational transactions. This is
most useful when needing to copy some portiong of the informational lines,
for instance the certificate output from --tls-get-peer-cert.
- -nsh, --no-send-hints
- -nrh, --no-receive-hints
- -nth, --no-hints
- --no-send-hints and --no-receive-hints supress the transaction prefix from
send and receive lines, respectively. 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).
--no-hints is identical to specifying both --no-send-hints and
--no-receive-hints.
Don't show transaction hints (useful in conjunction with -hr to create
copy/paste-able transactions).
- -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 option is useful in
seeing details when servers are sending lots of data in single packets, or
breaking up individual lines into multiple packets. 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.
- --output-file </path/to/file>
- --output-file-stdout </path/to/file>
- --output-file-stderr </path/to/file>
- These options allow the user to send output to files instead of
stdout/stderr. The first option sends both to the same file. The arguments
of &STDOUT and &STDERR are treated specially, refering to the
"normal" file handles, so "--output-file-stderr
'&STDOUT'" would redirect STDERR to STDOUT.
- -pp, --protect-prompt
- Don't echo user input on prompts that are potentially sensitive (right now
only authentication password). See also --auth-hide-password
- -hr, --hide-receive
- Don't display lines sent from the remote server being received by
swaks
- -hs, --hide-send
- Don't display lines being sent by swaks to the remote server
- -hi, --hide-informational
- Don't display non-error informational lines from swaks itself.
- -ha, --hide-all
- Do not display any content to the terminal.
- -S, --silent [level]
- 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.
- --support
- Print capabilities and exit. Certain features require non-standard perl
modules. This options 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 functionality.
- --dump
- 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 considered to be a pure self-diagnosis
tool and no effort is made or will ever be made to mask passwords in the
--dump output.
- --help
- Display this help information.
- --version
- Display version information.
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 feature
complete on all of these.
This program is known to demonstrate basic functionality on Windows using
ActiveState's Perl. It has not been fully tested. Known to work are basic
SMTP functionality and the LOGIN, PLAIN, and CRAM-MD5 auth types. Unknown
is any TLS functionality and the NTLM/SPA and DIGEST-MD5 auth types.
Because this program should work anywhere Perl works, I would appreciate
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 was been used casually by the author, though not thoroughly tested,
with Sendmail, Smail, Exchange, Oracle Collaboration Suite, qpsmtpd, and
Communigate. Because all functionality in swaks is based off of known
standards it should work with any fairly modern mail server. If a problem
is found, please alert the author at the address below.
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
unexpectedly. 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 immediately 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 immediately closes the connection,
swaks will use the exit code 6 because 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
- 32
- error in EHLO following TLS negotiation
- 33
- error in XCLIENT transaction
- 34
- error in EHLO following XCLIENT
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 it 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".
- proj-swaks@jetmore.net
- Please use this address for general contact, questions, patches, requests,
etc.
- updates-swaks@jetmore.net
- 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 address.
- http://www.jetmore.org/john/code/swaks/
- Change logs, this help, and the latest version is found at this link.