1SWAKS.20061116.0(1) User Contributed Perl Documentation SWAKS.20061116.0(1)
2
6 swaks - SMTP transaction tester
7
9 swaks [--help⎪--version] ⎪ (see description of options below)
10
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 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 --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 -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 -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 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 -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 -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 -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 -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 -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 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 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 --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 --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 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 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 --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 -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 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 --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 --header "Subject: foo" --h-Subject foo
148 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 --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 --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 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 -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 -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 -nsf, --no-strip-from
202 Don't strip the From_ line from the DATA portion, if present.
203 -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 -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 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 -m Emulate Mail command. Least used option in swaks.
220 --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 -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 --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 -tls
242 Require connection to use STARTTLS. Exit if TLS not available for
243 any reason (not advertised, negotiations failed, etc).
244 -tlso, --tls-optional
246 Attempt to use STARTTLS if possible, continue t/ normal transaction
247 if TLS unavailable.
248 -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 -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 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 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 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 -ao, --auth-optional
281 Same as -a, but if authentication is unavailable or fails, attempts
282 to continue transaction.
283 -au, --auth-user
285 Supply the username for authentication. The string <> can be sup‐
286 plied to mean an empty username.
287 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 -ap, --auth-password
296 Supply the password for authentication. The string <> can be sup‐
297 plied to mean an empty password.
298 -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 -apt, --auth-plaintext
309 Instead of showing AUTH strings literally (in base64), translate
310 them to plaintext before printing on screen.
311 -nth, --no-hints
313 Don't show transaction hints. (Useful in conjunction with -hr to
314 create copy/paste-able transactions
315 -hr, --hide-receive
317 Don't display reception lines
318 -hs, --hide-send
320 Don't display sending lines
321 -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 --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 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 --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 --help
351 This screen.
352 --version
354 Version info.
355
357 swaks
358 prompt user for to address and send a default email.
359 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
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
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 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 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 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 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 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 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 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 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 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 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 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 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
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 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 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 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
501 0 no errors occurred
502 1 error parsing command line options
504 2 error connecting to remote server
506 3 unknown connection type
508 4 while running with connection type of "pipe", fatal problem writing
510 to or reading from the child process
511 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 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 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 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 10 error in prerequisites (needed module not available)
531 21 error reading initial banner from server
533 22 error in HELO transaction
535 23 error in MAIL transaction
537 24 no RCPTs accepted
539 25 server returned error to DATA request
541 26 server did not accept mail following data
543 27 server returned error after normal-session quit request
545 28 error in AUTH transaction
547 29 error in TLS transaction
549 32 error in EHLO following TLS negotiation
551
553 proj-swaks@jetmore.net
554 Please use this address for general contact, questions, patches,
555 requests, etc.
556 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 jetmore.org/john/code/#swaks
563 Change logs, this help, and the latest version is found at this
564 link.
565perl v5.8.8 2006-11-16 SWAKS.20061116.0(1)