1SWAKS.20061116.0(1)   User Contributed Perl Documentation  SWAKS.20061116.0(1)
2
3
4

NAME

6       swaks - SMTP transaction tester
7

USAGE

9       swaks [--help⎪--version] ⎪ (see description of options below)
10

OPTIONS

12       --pipe
13           This option takes as its argument a program and the program's argu‐
14           ments.  If this option is present, swaks opens a pipe to the pro‐
15           gram and enters an SMTP transaction over that pipe rather than con‐
16           necting to a remote server.  Some MTAs have testing modes using
17           stdin/stdout.  This option allows you to tie into those options.
18           For example, if you implemented DNSBL checking with exim and you
19           wanted to make sure it was working, you could run 'swaks --pipe
20           "exim -bh 127.0.0.2"'.
21
22           In an ideal world the process you are talking to should behave
23           exactly like an SMTP server on stdin and stdout.  Any debugging
24           should be sent to stderr, which will be directed to your terminal.
25           In the real world swaks can generally handle some debug on the
26           child's stdout, but there are no guarantees on how much it can han‐
27           dle.
28
29       --socket
30           This option takes as its argument a unix domain socket file.  If
31           this option is present, swaks enters an SMTP transaction over over
32           the unix domains socket rather than over an internet domain socket.
33           I think this option has uses when combined with a (yet unwritten)
34           LMTP mode, but to be honest at this point I just implemented it
35           because I could.
36
37       -l, --input-file
38           Argument to -l must be a path to a file containing TOKEN->VALUE
39           pairs.  The TOKEN and VALUE must be separated by whitespace.  These
40           tokens set values which would otherwise be set by command line
41           arguments.  See the description of the corresponding command line
42           argument for details of each token.  Valid tokens are FROM (-f), TO
43           (-t), SERVER (-s), DATA (-d), HELO (-h), PORT (-p), INTERFACE
44           (-li), and TIMEOUT (-to).
45
46       -t, --to
47           Use argument as "RCPT TO" address, or prompt user if no argument
48           specified.  Overridden by -l token TO.  Multiple recipients can be
49           specified by supplying as one comma-delimited argument.
50
51           There is no default for this option.  If no to addess is specified
52           with -t or TO token, user will be prompted for To: address on
53           STDIN.
54
55       -f, --from
56           Use argument as "MAIL FROM" address, or prompt user if no argument
57           specified.  Overridden by -l token FROM.  If no from address is
58           specified, default is user@host, where user is the best guess at
59           user currently running program, and host is best guess at DNS host‐
60           name of local host.  The string <> can be supplied to mean the null
61           sender.
62
63       -s, --server
64           Use argument as mail server to which to connect, or prompt user if
65           no argument specified.  Overridden by -l token SERVER.  If unspeci‐
66           fied, swaks tries to determine primary MX of destination address.
67           If Net::DNS module is not available, tries to connect to A record
68           for recipient's domain.
69
70       -p, --port
71           Use argument as port to connect to on server, or prompt user if no
72           argument is specified.  This can be either a port number or a ser‐
73           vice name.  Overridden by -l token PORT.  If unspecified, swaks
74           will use service lmtp if --protocol is LMTP, service smtps if
75           --tls-on-connect is used, and smtp otherwise.
76
77       -h, --helo, --ehlo
78           Use argument as argument to SMTP EHLO/HELO command, or prompt use
79           if no argument is specified.  Overridden by -l token HELO.  If
80           unspecified, swaks uses best guess at DNS hostname of local host.
81
82       -d, --data
83           Use argument as DATA portion of SMTP transaction, or prompt user if
84           no argument specified.  Overridden by -l token DATA.
85
86           This string should be on one single line, with a literal \n repre‐
87           senting where line breaks should be placed.  Leading dots will be
88           quoted.  Closing dot is not required but is allowed.  Very basic
89           token parsing is done.  %F is replaced with the value that will be
90           used for "MAIL FROM", %T is replaced with "RCPT TO" values, %D is
91           replaced with a timestamp, %H is replaced with the contents of
92           --add-header, and %B is replaced with the message body.  See the
93           --body option for the default body text.
94
95           Default value for this option is "Date: %D\nTo: %T\nFrom: %F\nSub‐
96           ject: test %D\nX-Mailer: swaks v$p_version jet‐
97           more.org/john/code/#swaks\n%H\n\n%B\n".
98
99       --body
100           Specify the body of the email.  The default is "This is a test
101           mailing".  If no argument to --body, you will be prompted to supply
102           one.  If '-' is supplied, body will be read from standard input.
103           If any other text is provided and the text represents an openable
104           file, the content of that file is used as the body.  If it does not
105           respresent an openable file, the text itself is used as the body.
106
107       --attach
108           When one or more --attach option is supplied, the message is
109           changed into a multipart/mixed MIME message.  The arguments to
110           --attach are processed the same as --body with regard to stdin,
111           file contents, etc.  --attach can be supplie multiple times to cre‐
112           ate multiple attachments.  By default each attachment is attached
113           as a application/octet-stream file.  See --attach-type for changing
114           this behaviour.
115
116           When the message changes to MIME format, the previous body (%B) is
117           attached as a text/plain type as the first attachment.  --body can
118           still be used to specify the contents of this body attachment.
119
120           It is legal for '-' (STDIN) to be specified as an argument multiple
121           times (once for --body and multiple times for --attach).  In this
122           case, the same content will be attached each time it is specified.
123           This is useful for attaching the same content with multiple MIME
124           types.
125
126       --attach-type
127           By default, content that gets MIME attached to a message with the
128           --attach option is encoded as application/octet-stream.
129           --attach-type changes the mime type for every --attach option which
130           follows it.  It can be specified multiple times.
131
132       -ah, --add-header
133           In the strictest sense, all this does is provide a value that
134           replaces the %H token in the data.  Because of where %H is located
135           in the default DATA, practically it is used to add custom headers
136           without having to recraft the entire body.
137
138           The option can either be specified multiple times or a single time
139           with multiple headers seperated by a literal '\n' string.  So,
140           "--add-header 'Foo: bar' --add-header 'Baz: foo'" and "--add-header
141           'Foo: bar\nBaz: foo'" end up adding the same two headers.
142
143       --header, --h-Header
144           These options allow a way to change headers that already exist in
145           the DATA.  These two calls do the same thing:
146
147           --header "Subject: foo" --h-Subject foo
148
149           Subject is the example used.  If the header does not exist in the
150           body already, these calls behave identically to --add-header.  The
151           purpose of this option it to provide a fast way to change the
152           nature of the default DATA for specific tests.  For instance if you
153           wanted to test a subject filer in a mail system, you could use
154           --h-Subject "SPAM STRING" to test rather than having to craft and
155           entire new DATA string to pass to --data.
156
157       --timeout
158           Use argument as the SMTP transaction timeout, or prompt user if no
159           argument given.  Overridden by the -l token TIMEOUT.  Argument can
160           either be a pure digit, which will be interpretted as seconds, or
161           can have a specifier s or m (5s = 5 seconds, 3m = 180 seconds).  As
162           a special case, 0 means don't timeout the transactions.  Default
163           value is 30s.
164
165       --protocol
166           Specify which protocol to use in the transaction.  Valid options
167           are shown in the table below.  Currently the 'core' protocols are
168           SMTP, ESMTP, and LMTP.  By using variations of these protocol types
169           one can specify default ports, whether authentication should be
170           attempted, and the type of TLS connection that should be attempted.
171           The default protocol is ESMTP.  This table demonstrates the avail‐
172           able arguments to --protocol and the options each sets as a side
173           effect:
174
175                      HELO            AUTH    TLS     PORT
176              --------------------------------------------------
177              SMTP    HELO                            smtp  / 25
178              SSMTP   EHLO->HELO              -tlsc   smtps / 465
179              SSMTPA  EHLO->HELO      -a      -tlsc   smtps / 465
180              SMTPS   HELO                    -tlsc   smtps / 465
181              ESMTP   EHLO->HELO                      smtp  / 25
182              ESMTPA  EHLO->HELO      -a              smtp  / 25
183              ESMTPS  EHLO->HELO              -tls    smtp  / 25
184              ESMTPSA EHLO->HELO      -a      -tls    smtp  / 25
185              LMTP    LHLO                            lmtp  / 24
186              LMTPA   LHLO            -a              lmtp  / 24
187              LMTPS   LHLO                    -tls    lmtp  / 24
188              LMTPSA  LHLO            -a      -tls    lmtp  / 24
189
190       -li, --local-interface
191           Use argument as the local interface for the SMTP connection, or
192           prompt user if no argument given.  Overridden by the -l token
193           INTERFACE.  Argument can be an IP or a hostname.  Default action is
194           to let OS choose local interface.
195
196       -g  If specified, swaks will read the DATA value for the mail from
197           STDIN.  If there is a From_ line in the email, it will be removed
198           (but see -nsf option).  Useful for delivering real message (stored
199           in files) instead of using example messages.
200
201       -nsf, --no-strip-from
202           Don't strip the From_ line from the DATA portion, if present.
203
204       -n, --suppress-data
205           If this option is specified, swaks summarizes the DATA portion of
206           the SMTP transaction instead of printing every line.
207
208       -q, --quit-after
209           The argument to this option is used as an indicator of where to
210           quit the SMTP transaction.  It can be thought of as "quit after",
211           with valid arguments CONNECT, FISRT-HELO, TLS, HELO, AUTH, MAIL,
212           and RCPT.  In a non-STARTTLS session, FIRST-HELO and HELO behave
213           the same way.  In a STARTTLS session, FIRST-HELO quits after the
214           first HELO sent, while HELO quits after the second HELO is sent.
215
216           For convenience, LHLO and EHLO are synonyms for HELO, FIRST-EHLO
217           and FIRST-LHLO for FIRST-HELO, FROM for MAIL, and TO for RCPT.
218
219       -m  Emulate Mail command.  Least used option in swaks.
220
221       --support
222           Cause swaks to print its capabilities and exit.  Certain features
223           require non-standard perl modules.  This options evaluates whether
224           these modules are present and lets you know which functionality is
225           present.
226
227       -S, --silent
228           Cause swaks to be silent.  "-S" causes swaks to print no output
229           until an error occurs, after which all output is shown.  "-S -S"
230           causes swaks to only show error conditions.  "-S -S -S" shows no
231           output.
232
233       --pipeline
234           If the remote server supports it, attempt SMTP PIPELINING (RFC
235           2920).  This is a younger option, if you experience problems with
236           it please notify the author.  Potential problem areas include
237           servers accepting DATA even though there were no valid recipients
238           (swaks should send empty body in that case, not QUIT) and deadlocks
239           caused by sending packets outside the tcp window size.
240
241       -tls
242           Require connection to use STARTTLS.  Exit if TLS not available for
243           any reason (not advertised, negotiations failed, etc).
244
245       -tlso, --tls-optional
246           Attempt to use STARTTLS if possible, continue t/ normal transaction
247           if TLS unavailable.
248
249       -tlsc, --tls-on-connect
250           Initiate a TLS connection immediately on connection.  Use to test
251           smtps/ssmtp servers.  If this options is specified, the default
252           port changes from 25 to 465, though this can still be overridden
253           with the -p option.
254
255       -a, --auth
256           Require authentication.  If Authentication fails or is unavailable,
257           stop transaction.  -a can take an argument specifying which type(s)
258           of authentication to try.  If multiple, comma-delimited arguments
259           are given, each specified auth type is tried in order until one
260           succeeds or they all fail.  swaks currently supports PLAIN, LOGIN,
261           and CRAM-MD5.  If no argument is given any available authentication
262           type is used.  If neither password (-ap) or username (-au) is sup‐
263           plied on command line, swaks will prompt on STDIN.
264
265           SPA (NTLM/MSN) authentication is now supported.  Tested as a client
266           against Exim and Stalker's CommuniGate, but implementation may be
267           incomplete.  Authen::NTLM is currently required.  Note that CPAN
268           hosts two different Authen::NTLM modules.  Current implementation
269           requires Mark Bush's implementation (Authen/NTLM-1.02.tar.gz).
270           Plan to reimplement directly at some point to avoid confusion.
271
272           DIGEST-MD5 is now supported.  Tested as a client only against
273           Stalker's Communigate, so implementation may be incomplete.
274           Requires Authen::DigestMD5 module.
275
276           CRAM-SHA1 is now supported.  Only tested against a hacked server
277           implementation in Exim, so may be incomplete or incorrect.
278           Requires Digest::SHA1 module.
279
280       -ao, --auth-optional
281           Same as -a, but if authentication is unavailable or fails, attempts
282           to continue transaction.
283
284       -au, --auth-user
285           Supply the username for authentication.  The string <> can be sup‐
286           plied to mean an empty username.
287
288           For SPA authentication, a "domain" can be specified after the regu‐
289           lar username with a % seperator.  For instance, if "-ap user@exam‐
290           ple.com%NTDOM" is passed, "user@example.com" is the username and
291           "NTDOM" is the domain.  NOTE: I don't actually have access to a
292           mail server where the domain isn't ignored, so this may be imple‐
293           mented incorrectly.
294
295       -ap, --auth-password
296           Supply the password for authentication.  The string <> can be sup‐
297           plied to mean an empty password.
298
299       -am --auth-map
300           Provides a way to map alternate names onto base authentication
301           types.  Useful for any sites that use alternate names for common
302           types.  This functionality is actually used internally to map types
303           SPA and MSN onto the base type NTLM.  The command line argument to
304           simulate this would be "--auth-map SPA=NTLM,MSN=NTLM".  The base
305           types supported are LOGIN, PLAIN, CRAM-MD5, DIGEST-MD5, and NTLM.
306           SPA and MSN are mapped on to NTLM automatically.
307
308       -apt, --auth-plaintext
309           Instead of showing AUTH strings literally (in base64), translate
310           them to plaintext before printing on screen.
311
312       -nth, --no-hints
313           Don't show transaction hints.  (Useful in conjunction with -hr to
314           create copy/paste-able transactions
315
316       -hr, --hide-receive
317           Don't display reception lines
318
319       -hs, --hide-send
320           Don't display sending lines
321
322       -stl, --show-time-lapse
323           Display time lapse between send/receive pairs.  If 'i' is provided
324           as argument or the Time::HiRes module is unavailable the time lapse
325           will be integer only, otherwise it will be to the thousandth of a
326           second.
327
328       --force-getpwuid
329           In releases 20050709.1 and earlier of swaks the local_part of an
330           automatically generated sender email address would be found using
331           the getpwuid system call on the euid of the current process.
332           Depending on the users' desires, this may be confusing.  Following
333           the 20050709.1 release the local_part is not looked up via the get‐
334           login() funtion which attempts to look up the actual username of
335           the logged in user, regardless of the euid of the process they are
336           currently running.
337
338           An example of where this might be an issue is running swaks under
339           sudo for testing reasons when interacting with --pipe or --socket.
340           It makes sense that you need to run the process as a specific user‐
341           name but you would prefer your email to be from your real username.
342           You could always do this manually using the -s option, but this is
343           an attempt to make it easier.
344
345           --force-getpwuid forces the old behaviour for anyone who prefered
346           that behaviour.  Also, if there is no "real" user for getlogin() to
347           look up, the old getpwuid method will be used.  This would happen
348           if the process was run from cron or some other headless daemon.
349
350       --help
351           This screen.
352
353       --version
354           Version info.
355

EXAMPLES

357       swaks
358           prompt user for to address and send a default email.
359
360       cat mailfile ⎪ swaks -g -n -t user@example.com -tlso -a -au user -ap
361       password
362           send the contents of "mailfile" to user@example.com, using TLS if
363           available, requiring authentication, using user/password as authen‐
364           tication information.
365

COMMENTS

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

REQUIRES

377       swaks does not have any single requirement except the standard module
378       Getopt::Long.  However, there may be modules that are required for a
379       given invocation of swaks.  The following list details the features
380       reported by the --support option, what is actually being tested, and
381       the consequences of the feature being reported as "not available"
382
383       AUTH CRAM-MD5
384           CRAM-MD5 authentication requires the Digest::MD5 perl module.  If
385           this is unavailable and authentication is required, swaks will
386           error if CRAM-MD5 was the specific authentication type requested,
387           or if no specific auth type was requested but CRAM-MD5 was the only
388           type advertised by the server.
389
390       AUTH CRAM-SHA1
391           CRAM-SHA1 authentication requires the Digest::SHA1 perl module.  If
392           this is unavailable and authentication is required, swaks will
393           error if CRAM-SHA1 was the specific authentication type requested,
394           or if no specific auth type was requested but CRAM-SHA1 was the
395           only type advertised by the server.
396
397       AUTH DIGEST-MD5
398           DIGEST-MD5 authentication requires the Authen::DigestMD5 perl mod‐
399           ule.  If this is unavailable and authentication is required, swaks
400           will error if DIGEST-MD5 was the specific authentication type
401           requested, or if no specific auth type was requested but DIGEST-MD5
402           was the only type advertised by the server.
403
404       AUTH NTLM
405           NTLM/SPA/MSN authentication requires the Authen::NTLM perl module.
406           If this is unavailable and authentication is required, swaks will
407           error if NTLM was the specific authentication type requested, or if
408           no specific auth type was requested but NTLM was the only type
409           advertised by the server.  Note that there are two modules using
410           the Authen::NTLM namespace on CPAN.  The Mark Bush implementation
411           (Authen/NTLM-1.02.tar.gz) is the version required here.
412
413       Basic AUTH
414           All authentication types require base64 encoding and decoding.  If
415           possible, swaks uses the MIME::Base64 perl module to perform these
416           actions.  However, if MIME::Base64 is not available swaks will use
417           its own onboard base64 routines.  These are slower than the
418           MIME::Base64 routines and less reviewed, though they have been
419           tested thoroughly.  When possible it is recommended that you
420           install MIME::Base64.
421
422       Date Manipulation
423           swaks generates an RFC compliant date string when it interpolates
424           the %D token in message bodies.  In order to build the GMT offset
425           in this string, it needs the Time::Local module.  It would be very
426           odd for this module not to be available because it has been
427           included in the perl distribution for some time.  However, if it is
428           not loadable for some reason and swaks interpolates a %D token (as
429           it would when using the default body), the date string is in GMT
430           instead of your local timezone.
431
432       High Resolution Timing
433           When diagnosing SMTP delays using --show-time-lapse, by default
434           high resolution timing is attempted using the Time::HiRes module.
435           If this module is not available, swaks uses a much poorer timing
436           source with one second granularity.
437
438       Local Hostname Detection
439           swaks uses your local machine's hostname to build the HELO string
440           and sending email address when they are not specified on the com‐
441           mand line.  If the Sys::Hostname module (which is a part of the
442           base distribution) is not available for some reason, the user is
443           prompted interactively for the HELO and sender strings.  Note that
444           Sys::Hostname can sometimes fail to find the local hostname even
445           when the module is available, which has the same behaviour.
446
447       MX Routing
448           If the destination mail server is not specified using the --server
449           option, swaks attempts to use DNS to route the message based on the
450           recipient email address.  If the Net::DNS perl module is not avail‐
451           able, swaks uses 'localhost' as the outbound mail server.
452
453       Pipe Transport
454           The IPC::Open2 module is required to deliver a message to a spawned
455           subprocess using the --pipe option.  If this module, which is
456           included in the base perl distribution, in not available, attempt‐
457           ing to call swaks with the --pipe option will result in an error.
458
459       Socket Transport
460           The IO::Socket module is required to deliver a message to an inter‐
461           net domain socket (the default behaviour of swaks) and to a unix
462           domain socket (specified with the --socket option).  If this mod‐
463           ule, which is included in the base perl distribution, is not avail‐
464           able, attempting to call swaks with the --server or --socket
465           options (or none of the --socket, --server, and --pipe options)
466           will result in an error.
467
468       TLS TLS functionality requires the Net::SSLeay perl module.  If this
469           module is not available and TLS was required (using the
470           --tls-on-connect or --tls options), the session will error out.  If
471           TLS was requested but not required (using the --tls-optional
472           option), swaks will continue but not attempt a TLS session.
473

PORTABILITY

475       Operating Systems
476           This program was primarily intended for use on unix-like operating
477           systems, and it should work on any reasonable version thereof.  It
478           has been developed and tested on Solaris, Linux, and Mac OS X and
479           is feature complete on all of these.
480
481           This program is known to demonstrate basic functionality on Windows
482           using ActiveState's Perl.  It has not been fully tested.  Known to
483           work are basic SMTP functionality and the LOGIN, PLAIN, and
484           CRAM-MD5 auth types.  Unknown is any TLS functionality and the
485           NTLM/SPA and Digest-MD5 auth types.
486
487           Because this program should work anywhere Perl works, I would
488           appreciate knowing about any new operating systems you've thor‐
489           oughly used swaks on as well as any problems encountered on a new
490           OS.
491
492       Mail Servers
493           This program was almost exclusively developed against Exim mail
494           servers.  It was been used casually by the author, though not thor‐
495           oughly tested, with sendmail, smail, and Communigate.  Because all
496           functionality in swaks is based off of known standards it should
497           work with any fairly modern mail server.  If a problem is found,
498           please alert the author at the address below.
499

EXIT CODES

501       0   no errors occurred
502
503       1   error parsing command line options
504
505       2   error connecting to remote server
506
507       3   unknown connection type
508
509       4   while running with connection type of "pipe", fatal problem writing
510           to or reading from the child process
511
512       5   while running with connection type of "pipe", child process died
513           unexpectedly.  This can mean that the program specified with --pipe
514           doesn't exist.
515
516       6   Connection closed unexpectedly.  If the close is detected in
517           response to the 'QUIT' swaks sends following an unexpected
518           response, the error code for that unexpected response is used
519           instead.
520
521           For instance, if a mail server returns a 550 response to a MAIL
522           FROM: and then immediately closes the connection, swaks detects
523           that the connection is closed, but uses the more specific exit code
524           23 to detail the nature of the failure.
525
526           If instead the server return a 250 code and then immediately closes
527           the connection, swaks will use the exit code 6 because there is not
528           a more specific exit code.
529
530       10  error in prerequisites (needed module not available)
531
532       21  error reading initial banner from server
533
534       22  error in HELO transaction
535
536       23  error in MAIL transaction
537
538       24  no RCPTs accepted
539
540       25  server returned error to DATA request
541
542       26  server did not accept mail following data
543
544       27  server returned error after normal-session quit request
545
546       28  error in AUTH transaction
547
548       29  error in TLS transaction
549
550       32  error in EHLO following TLS negotiation
551

CONTACT

553       proj-swaks@jetmore.net
554           Please use this address for general contact, questions, patches,
555           requests, etc.
556
557       updates-swaks@jetmore.net
558           If you would like to be put on a list to receive notifications when
559           a new version of swaks is released, please send an email to this
560           address.
561
562       jetmore.org/john/code/#swaks
563           Change logs, this help, and the latest version is found at this
564           link.
565
566
567
568perl v5.8.8                       2006-11-16               SWAKS.20061116.0(1)
Impressum