swaks - SMTP transaction tester

swaks [--help|--version] | (see description of options below)

--pipe

This option takes as its argument a program and the program's arguments. If this option is present, swaks opens a pipe to the program and enters an SMTP transaction over that pipe rather than connecting to a remote server. Some MTAs have testing modes using stdin/stdout. This option allows you to tie into those options. 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'.

--socket

This option takes as its argument a unix domain socket file. If this option is present, swaks enters an SMTP transaction over over the unix domains socket rather than over an internet domain socket. I think this option has uses when combined with a (yet unwritten) LMTP mode, but to be honest at this point I just implemented it because I could.

-l, --input-file

Argument to -l must be a path to a file containing TOKEN->VALUE pairs. The TOKEN and VALUE must be separated by whitespace. These tokens set values which would otherwise be set by command line arguments. See the description of the corresponding command line argument for details of each token. Valid tokens are FROM (-f), TO (-t), SERVER (-s), DATA (-d), HELO (-h), PORT (-p), INTERFACE (-li), and TIMEOUT (-to).

-t, --to

Use argument as RCPT TO address, or prompt user if no argument specified. Overridden by -l token TO. Multiple recipients can be specified by supplying as one comma-delimited argument. There is no default for this option. If no to addess is specified with -t or TO token, user will be prompted for To: address on STDIN.

-f, --from

Use argument as MAIL FROM address, or prompt user if no argument specified. Overridden by -l token FROM. If no from address is specified, default is user@host, where user is the best guess at user currently running program, and host is best guess at DNS hostname of local host. The string <> can be supplied to mean the null sender.

-s, --server

Use argument as mail server to which to connect, or prompt user if no argument specified. Overridden by -l token SERVER. If unspecified, swaks tries to determine primary MX of destination address. If Net::DNS module is not available, tries to connect to A record for recipient's domain.

-p, --port

Use argument as port to connect to on server, or prompt user if no argument is specified. Overridden by -l token PORT. If unspecified, swaks will try to connect to port 25.

-h, --helo, --ehlo

Use argument as argument to SMTP EHLO/HELO command, or prompt use if no argument is specified. Overridden by -l token HELO. If unspecified, swaks uses best guess at DNS hostname of local host.

-d, --data

Use argument as DATA portion of SMTP transaction, or prompt user if no argument specified. Overridden by -l token DATA. This string should be on one single line, with a literal \n representing where line breaks should be placed. Leading dots will be quoted. Closing dot is not required but is allowed. Very basic token parsing is done. CW%F is replaced with the value that will be used for MAIL FROM, CW%T is replaced with RCPT TO values, and CW%D is replaced with a timestamp. Default value for this option is Date: CW%D\nTo: CW%T\nFrom: CW%F\nSubject: test CW%D\nX-Mailer: swaks v$p_version jetmore.org/john/code/#swaks\n\nThis is a test mailing\n.

--timeout

Use argument as the SMTP transaction timeout, or prompt user if no argument given. Overridden by the -l token TIMEOUT. 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.

-li, --local-interface

Use argument as the local interface for the SMTP connection, or prompt user if no argument given. Overridden by the -l token INTERFACE. Argument can be an IP or a hostname. Default action is to let OS choose local interface.

-g

If specified, swaks will read the DATA value for the mail from STDIN. 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.

-nsf, --no-strip-from

Don't strip the From_ line from the DATA portion, if present.

-n, --suppress-data

If this option is specified, swaks summarizes the DATA portion of the SMTP transaction instead of printing every line.

-q, --quit-after

The argument to this option is used as an indicator of where to quit the SMTP transaction. It can be thought of as quit after, with valid arguments CONNECT, FISRT-HELO, TLS, HELO, AUTH, MAIL, and RCPT. In a non-STARTTLS session, FIRST-HELO and HELO behave the same way. In a STARTTLS session, FIRST-HELO quits after the first HELO sent, while HELO quits after the second HELO is sent.

-m

Emulate Mail command. Least used option in swaks.

--support

Cause swaks to print its capabilities and exit. Certain features require non-standard perl modules. This options evaluates whether these modules are present and lets you know which functionality is present.

-S, --silent

Cause swaks to be silent. -S causes swaks to print no output until an error occurs, after which all output is shown. -S -S causes swaks to only show error conditions. -S -S -S shows no output.

-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 possible, continue t/ normal transaction if TLS unavailable.

-tlsc, --tls-on-connect

Initiate a TLS connection immediately on connection. Use to test smtps/ssmtp servers. If this options is specified, the default port changes from 25 to 465, though this can still be overridden with the -p option.

-a, --auth

Require authentication. If Authentication fails or is unavailable, stop transaction. -a can take an argument specifying which type of authentication to use. swaks currently supports PLAIN, LOGIN, and CRAM-MD5. If no argument is given any available authentication type is used. If neither password (-ap) or username (-au) is supplied on command line, swaks will prompt on STDIN. SPA (NTLM/MSN) authentication is now supported. Tested as a client against Exim and Stalker's CommuniGate, but implementation may be incomplete. Authen::NTLM is currently required. Note that CPAN hosts two different Authen::NTLM modules. Current implementation requires Mark Bush's implementation (Authen/NTLM-1.02.tar.gz). Plan to reimplement directly at some point to avoid confusion. DIGEST-MD5 is now supported. Tested as a client only against Stalker's Communigate, so implementation may be incomplete. Requires Authen::DigestMD5 module.

-ao, --auth-optional

Same as -a, but if authentication is unavailable or fails, attempts to continue transaction.

-au, --auth-user

Supply the username for authentication. The string <> can be supplied to mean an empty username. For SPA authentication, a domain can be specified after the regular username with a % seperator. For instance, if -ap user@example.com%NTDOM is passed, user@example.com is the username and NTDOM is the domain. NOTE: I don't actually have access to a mail server where the domain isn't ignored, so this may be implemented incorrectly.

-ap, --auth-password

Supply the password for authentication. The string <> can be supplied to mean an empty password.

-am --auth-map

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. The base types supported are LOGIN, PLAIN, CRAM-MD5, DIGEST-MD5, and NTLM. SPA and MSN are mapped on to NTLM automatically.

-apt, --auth-plaintext

Instead of showing AUTH strings literally (in base64), translate them to plaintext before printing on screen.

-nth, --no-hints

Don't show transaction hints. (Useful in conjunction with -hr to create copy/paste-able transactions

-hr, --hide-receive

Don't display reception lines

-hs, --hide-send

Don't display sending lines

-stl, --show-time-lapse

Display time lapse between send/receive pairs. If 'i' is provided as argument or the Time::HiRes module is unavailable the time lapse will be integer only, otherwise it will be to the thousandth of a second.

--help

This screen.

--version

Version info.

swaks

prompt user for to address and send a default email.

cat mailfile | swaks -g -n -t user@example.com -tlso -a -au user -ap password

send the contents of mailfile to user@example.com, using TLS if available, requiring authentication, using user/password as authentication information.

This program was written because I was testing a new MTA on an alternate port. I did so much testing that using interactive telnet grew tiresome. Over the next several years this program was fleshed out and every single option was added as a direct need of some testing I was doing as the mail admin of a medium sized ISP, with the exception of TLS support which was added on a whim. As such, all options are reasonably well thought out and fairly well tested (though TLS could use more testing).

IO::Socket, Sys::Hostname, Getop::Long, Time::Local

These modules are all required for the program to run at all. This shouldn't be an issue as I believe these are all core modules.

Net::DNS

This module is required to look up MX records for domains. If unavailable the -s option can be used to statically route the message.

Net::SSLeay

This module is required for TLS sessions. STARTTLS will not be supported if module is unavailable.

MIME::Base64

This module is required for all SMTP AUTH transactions. If it is unavailable no AUTH methods will be supported.

Digest::MD5

This module is required for CRAM-MD5 authentication.

Authen::NTLM

This module is required for SPA/MSN/NTLM authentication. Note that there are two modules using the Authen::NTLM namespace on CPAN. The Mark Bush implementation (Authen/NTLM-1.02.tar.gz) is the version required here.

Authen::DigestMD5

This module is required for DIGEST-MD5 authentication.

Time::HiRes

This module is required for high resolution timing. If unavailable only integer timing is available.

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, 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.

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.

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

proj-swaks@jetmore.net