1SWAKS(1) User Contributed Perl Documentation SWAKS(1)
2
6 swaks - Swiss Army Knife SMTP, the all-purpose smtp transaction tester
7
9 swaks' primary design goal is to be a flexible, scriptable,
10 transaction-oriented SMTP test tool. It handles SMTP features and
11 extensions such as TLS, authentication, and pipelining; multiple
12 version of the SMTP protocol including SMTP, ESMTP, and LMTP; and
13 multiple transport methods including unix-domain sockets, internet-
14 domain sockets, and pipes to spawned processes. Options can be
15 specified in environment variables, configuration files, and the
16 command line allowing maximum configurability and ease of use for
17 operators and scripters.
18
20 Deliver a standard test email to user@example.com on port 25 of
21 test-server.example.net:
22 swaks --to user@example.com --server test-server.example.net
24 Deliver a standard test email, requiring CRAM-MD5 authentication as
26 user me@example.com. An "X-Test" header will be added to the email
27 body. The authentication password will be prompted for.
28 swaks --to user@example.com --from me@example.com --auth CRAM-MD5
30 --auth-user me@example.com --header-X-Test "test email"
31 Test a virus scanner using EICAR in an attachment. Don't show the
33 message DATA part.:
34 swaks -t user@example.com --attach - --server
36 test-server.example.com --suppress-data </path/to/eicar.txt
37 Test a spam scanner using GTUBE in the body of an email, routed via the
39 MX records for example.com:
40 swaks --to user@example.com --body /path/to/gtube/file
42 Deliver a standard test email to user@example.com using the LMTP
44 protocol via a UNIX domain socket file
45 swaks --to user@example.com --socket /var/lda.sock --protocol LMTP
47 Report all the recipients in a text file that are non-verifyiable on a
49 test server:
50 for E in `cat /path/to/email/file`
52 do
53 swaks --to $E --server test-server.example.com --quit-after RCPT --hide-all
54 [ $? -ne 0 ] && echo $E
55 done
56
58 This document tries to be consistent and specific in its use of the
59 following terms to reduce confusion.
60 Transaction
62 A transaction is the opening of a connection over a transport to a
63 target and using a messaging protocol to attempt to deliver a
64 message.
65 Target
67 The target of a transaction is the thing that swaks connects to.
68 This generic term is used throughout the documentation because most
69 other terms improperly imply something about the transport being
70 used.
71 Transport
73 The transport is the underlying method used to connect to the
74 target.
75 Protocol
77 The protocol is the application language used to communicate with
78 the target. This document uses SMTP to speak generically of all
79 three supported protocols unless it states that it is speaking of
80 the specific 'SMTP' protocol and excluding the others.
81 Message
83 SMTP protocols exist to transfer messages, a set of bytes in an
84 agreed-upon format that has a sender and a recipient.
85 Envelope
87 A message's envelope contains the "true" sender and receiver of a
88 message. It can also be referred to as its components, envelope-
89 sender and envelope-recipients. It is important to note that a
90 messages envelope does not have to match its To: and From: headers.
91 DATA
93 The DATA portion of an SMTP transaction is the actual message that
94 is being transported. It consists of both the message's headers
95 and its body. DATA and body are sometimes use synonymously, but
96 they are always two distinct things in this document.
97 Headers
99 A message's headers are defined as all the lines in the message's
100 DATA section before the first blank line. They contain information
101 about the email that will be displayed to the recipient such as
102 To:, From:, Subject:, etc. In this document headers will always be
103 written with a capitalized first letter and a trailing colon.
104 Body
106 A message's body is the portion of its DATA section following the
107 first blank line.
108
110 To prevent potential confusion in this document a flag to swaks is
111 always referred to as an "option". If the option takes additional
112 data, that additional data is referred to as an argument to the option.
113 For example, "--from fred@example.com" might be provided to swaks on
114 the command line, with "--from" being the option and "fred@example.com"
115 being --from's argument.
116 Options can be given to swaks in three ways. They can be specified in
118 a configuration file, in environment variables, and on the command
119 line. Depending on the specific option and whether or not an argument
120 is given to it, swaks may prompt the user for the argument.
121 When swaks evaluates its options, it first looks for a configuration
123 file (either in a default location or specified with --config). Then
124 it evaluates any options in environment variables. Finally, it
125 evaluates command line options. At each round of processing, any
126 options set earlier will be overridden. Additionally, any option can
127 be prefixed with "no-" to cause swaks to forget that the variable had
128 previously been set. This capability is necessary because many options
129 treat defined-but-no-argument differently than not-defined.
130 The exact mechanism and format for using each of the types is listed
132 below.
133 CONFIGURATION FILE
135 A configuration file can be used to set commonly-used or abnormally
136 verbose options. By default swaks looks in order for
137 $SWAKS_HOME/.swaksrc, $HOME/.swaksrc, and $LOGDIR/.swaksrc. If one
138 of those is found to exist (and --config has not been used) that
139 file is used as the configuration file.
140 Additionally a configuration file in a non-default location can be
142 specified using --config. If this is set and not given an argument
143 swaks will not use any configuration file, including any default
144 file. If --config points to a readable file, it is used as the
145 configuration file, overriding any default that may exist. If it
146 points to a non-readable file and error will be shown and swaks
147 will exit.
148 A set of "portable" defaults can also be created by adding options
150 to the end of the swaks program file. As distributed, the last
151 line of swaks should be "__END__". Any lines added after __END__
152 will be treated as the contents of a configuration file. This
153 allows a set of user preferences to be automatically copied from
154 server to server in a single file.
155 If present and configuration files have not been explicitly turned
157 off, the __END config is always read. Only one other configuration
158 file will ever be used per single invocation of swaks, even if
159 multiple configuration files are specified. Specifying the
160 --config option with no argument turns off the processing of both
161 the __END__ config and any actual config files.
162 In a configuration file lines beginning with a hash (#) are
164 ignored. All other lines are assumed to be an option to swaks,
165 with the leading dash or dashes optional. Everything after a
166 option line's first space is assumed to be the option's argument
167 and is not shell processed. Therefore quoting is usually unneeded
168 and will be included literally in the argument. Here is an example
169 of the contents of a configuration file:
170 # always use this sender, no matter server or logged in user
172 --from fred@example.com
173 # I prefer my test emails have a pretty from header. Note
174 # the lack of dashes on option and lack of quotes around
175 # entire argument.
176 h-From: "Fred Example" <fred@example.com>
177 There is a deprecated option --input-file (or -l) in swaks that was
179 a precursor of the configuration file defined here. That option
180 has been judged deficient and is being replaced wholesale with the
181 idea of the configuration file defined above. The option still
182 exists for the time being but its use is strongly discouraged. It
183 is no longer documented, and it will be removed entirely in some
184 future release.
185 ENVIRONMENT VARIABLES
187 Options can be supplied via environment variables. The variables
188 are in the form $SWAKS_OPT_name, where name is the name of the
189 option that would be specified on the command line. Because dashes
190 aren't allowed in environment variable names in most unix-ish
191 shells, no leading dashes should be used and any dashes inside the
192 option's name should be replaced with underscores. The following
193 would create the same options shown in the configuration file
194 example:
195 $ SWAKS_OPT_from='fred@example.com'
197 $ SWAKS_OPT_h_From='"Fred Example" <fred@example.com>'
198 Setting a variable to an empty value is the same as specifying it
200 on the command line with no argument. For instance, setting
201 SWAKS_OPT_server="" would cause swaks to prompt the use for the
202 server to which to connect at each invocation.
203 In addition to setting the equivalent of command line options,
205 SWAKS_HOME can be set to a directory containing the default
206 .swaksrc to be used.
207 COMMAND LINE OPTIONS
209 The final method of supplying options to swaks is via the command
210 line. The options behave in a manner consistent with most unix-ish
211 command line programs. Many options have both a short and long
212 form (for instance -s and --server). By convention short options
213 are specified with a single dash and long options are specified
214 with a double-dash. This is only a convention and either prefix
215 will work with either type.
216 The following demonstrates the example shown in the configuration
218 file and environment variable sections:
219 $ swaks --from fred@example.com --h-From: '"Fred Example" <fred@example.com>'
221
223 swaks can connect to a destination via unix pipes ("pipes"), unix
224 domain sockets ("unix sockets"), or internet domain sockets ("network
225 sockets"). Connecting via network sockets is the default behavior.
226 Because of the singular nature of the transport used, each set of
227 options in the following section is mutually exclusive. Specifying
228 more than one of --server, --pipe, or --socket will result in an error.
229 Mixing other options between transport types will only result in the
230 irrelevant options being ignored. Below is a brief description of each
231 type of transport and the options that are specific to that transport
232 type.
233 NETWORK SOCKETS
235 This transport attempts to deliver a message via TCP/IP, the
236 standard method for delivering SMTP. This is the default transport
237 for swaks. If none of --server, --pipe, or --socket are given then
238 this transport is used and the destination server is determined
239 from the recipient's domain (see --server below for more details).
240 This transport requires the IO::Socket module which is part of the
242 standard perl distribution. If this module is not loadable,
243 attempting to use a this transport will result in an error and
244 program termination.
245 -s, --server [destination mail server[:port]]
247 Explicitly tell swaks to use network sockets and specify the
248 hostname or IP address to which to connect, or prompt if no
249 argument is given. If this option is not given and no other
250 transport option is given, the target mail server is determined
251 from the appropriate DNS records for the domain of the
252 recipient email address using the Net::DNS module. If Net::DNS
253 is not available swaks will attempt to connect to localhost to
254 deliver. See also --copy-routing.
255 -p, --port [port]
257 Specify which TCP port on the target is to be used, or prompt
258 if no argument is listed. The argument can be a service name
259 (as retrieved by getservbyname(3)) or a port number. The
260 default port is determined by the --protocol option. See
261 --protocol for more details.
262 -li, --local-interface [IP or hostname]
264 Use argument as the local interface for the outgoing SMTP
265 connection, or prompt user if no argument given. Argument can
266 be an IP address or a hostname. Default action is to let the
267 operating system choose local interface.
268 --copy-routing [domain]
270 The argument is interpreted as the domain part of an email
271 address and it is used to find the destination server using the
272 same logic that would be used to look up the destination server
273 for an recipient email address. See --to option for more
274 details on how the target is determined from the email domain.
275 UNIX SOCKETS
277 This transport method attempts to deliver messages via a unix-
278 domain socket file. This is useful for testing MTA/MDAs that
279 listen on socket files (for instance, testing LMTP delivery to
280 Cyrus). This transport requires the IO::Socket module which is
281 part of the standard perl distribution. If this module is not
282 loadable, attempting to use this transport will result in an error
283 and program termination.
284 --socket [/path/to/socket/file]
286 This option takes as its argument a unix-domain socket file.
287 If swaks is unable to open this socket it will display an error
288 and exit.
289 PIPES
291 This transport attempts to spawn a process and communicate with it
292 via pipes. The spawned program must be prepared to behave as a
293 mail server over STDIN/STDOUT. Any MTA designed to operate from
294 inet/xinet should support this. In addition some MTAs provide
295 testing modes that can be communicated with via STDIN/STDOUT. This
296 transport can be used to automate that testing. For example, if
297 you implemented DNSBL checking with Exim and you wanted to make
298 sure it was working, you could run 'swaks --pipe "exim -bh
299 127.0.0.2"'. In an ideal world the process you are talking to
300 should behave exactly like an SMTP server on stdin and stdout. Any
301 debugging should be sent to stderr, which will be directed to your
302 terminal. In the real world swaks can generally handle some debug
303 on the child's stdout, but there are no guarantees on how much it
304 can handle.
305 This transport requires the IPC::Open2 module which is part of the
307 standard perl distribution. If this module is not loadable,
308 attempting to use this transport will result in an error and
309 program termination.
310 --pipe [/path/to/command and arguments]
312 Provide a process name and arguments to the process. swaks
313 will attempt to spawn the process and communicate with it via
314 pipes. If the argument is not an executable swaks will display
315 an error and exit.
316
318 These options are related to the protocol layer.
319 -t, --to [email-address[,email-address,...]]
321 Tells swaks to use argument(s) as the envelope-recipient for the
322 email, or prompt for recipient if no argument provided. If
323 multiple recipients are provided and the recipient domain is needed
324 to determine routing the domain of the last recipient provided is
325 used.
326 There is no default value for this option. If no recipients are
328 provided via any means, user will be prompted to provide one
329 interactively. The only exception to this is if a --quit-after
330 value is provided which will cause the smtp transaction to be
331 terminated before the recipient is needed.
332 -f, --from [email-address]
334 Use argument as envelope-sender for email, or prompt user if no
335 argument specified. The string <> can be supplied to mean the null
336 sender. If user does not specify a sender address a default value
337 is used. The domain-part of the default sender is a best guess at
338 the fully-qualified domain name of the local host. The method of
339 determining the local-part varies. On Windows, Win32::LoginName()
340 is used. On unix-ish platforms, the $LOGNAME environment variable
341 is used if it is set. Otherwise getpwuid(3) is used. See also
342 --force-getpwuid.
343 --ehlo, --lhlo, -h, --helo [helo-string]
345 String to use as argument to HELO/EHLO/LHLO command, or prompt use
346 if no argument is specified. If this option is not used a best
347 guess at the fully-qualified domain name of the local host is used.
348 If the Sys::Hostname module, which is part of the base
349 distribution, is not available the user will be prompted for a HELO
350 value. Note that Sys::Hostname has been observed to not be able to
351 find the local hostname in certain circumstances. This has the
352 same effect as if Sys::Hostname were unavailable.
353 -q, --quit-after [stop-point]
355 Point at which the transaction should be stopped. When the
356 requested stopping point is reached in the transaction, and
357 provided that swaks has not errored out prior to reaching it,
358 swaks will send "QUIT" and attempt to close the connection cleanly.
359 These are the valid arguments and notes about their meaning.
360 CONNECT, BANNER
362 Terminate the session after receiving the greeting banner from
363 the target.
364 FIRST-HELO, FIRST-EHLO, FIRST-LHLO
366 In a STARTTLS (but not tls-on-connect) session, terminate the
367 transaction after the first of two HELOs. In a non-STARTTLS
368 transaction, behaves the same as HELO (see below).
369 TLS Quit the transaction immediately following TLS negotiation.
371 Note that this happens in different places depending on whether
372 STARTTLS or tls-on-connect are used. This always quits after
373 the point where TLS would have been negotiated, regardless of
374 whether it was attempted.
375 HELO, EHLO, LHLO
377 In a STARTTLS session, quit after the second HELO. Otherwise
378 quit after the first and only HELO.
379 AUTH
381 Quit after authentication. This always quits after the point
382 where authentication would have been negotiated, regardless of
383 whether it was attempted.
384 MAIL, FROM
386 Quit after MAIL FROM: is sent.
387 RCPT, TO
389 Quit after RCPT TO: is sent.
390 --timeout [time]
392 Use argument as the SMTP transaction timeout, or prompt user if no
393 argument given. Argument can either be a pure digit, which will be
394 interpretted as seconds, or can have a specifier s or m (5s = 5
395 seconds, 3m = 180 seconds). As a special case, 0 means don't
396 timeout the transactions. Default value is 30s.
397 --protocol [protocol]
399 Specify which protocol to use in the transaction. Valid options
400 are shown in the table below. Currently the 'core' protocols are
401 SMTP, ESMTP, and LMTP. By using variations of these protocol types
402 one can tersely specify default ports, whether authentication
403 should be attempted, and the type of TLS connection that should be
404 attempted. The default protocol is ESMTP. This table demonstrates
405 the available arguments to --protocol and the options each sets as
406 a side effect:
407 SMTP
409 HELO, "-p 25"
410 SSMTP
412 EHLO->HELO, "-tlsc -p 465"
413 SSMTPA
415 EHLO->HELO, "-a -tlsc -p 465"
416 SMTPS
418 HELO, "-tlsc -p 465"
419 ESMTP
421 EHLO->HELO, "-p 25"
422 ESMTPA
424 EHLO->HELO, "-a -p 25"
425 ESMTPS
427 EHLO->HELO, "-tls -p 25"
428 ESMTPSA
430 EHLO->HELO, "-a -tls -p 25"
431 LMTP
433 LHLO, "-p 24"
434 LMTPA
436 LHLO, "-a -p 24"
437 LMTPS
439 LHLO, "-tls -p 24"
440 LMTPSA
442 LHLO, "-a -tls -p 24"
443 --pipeline
445 If the remote server supports it, attempt SMTP PIPELINING (RFC
446 2920). This is a younger option, if you experience problems with
447 it please notify the author. Potential problem areas include
448 servers accepting DATA even though there were no valid recipients
449 (swaks should send empty body in that case, not QUIT) and deadlocks
450 caused by sending packets outside the tcp window size.
451 --force-getpwuid
453 Tell swaks to use the getpwuid method of finding the default sender
454 local-part instead of trying $LOGNAME first.
455
457 These are options related to encrypting the transaction. These have
458 been tested and confirmed to work with all three transport methods.
459 The Net::SSLeay module is used to perform encryption when it is
460 requested. If this module is not loadable swaks will either ignore the
461 TLS request or error out, depending on whether the request was
462 optional. STARTTLS is defined as an extension in the ESMTP protocol
463 and will be unavailable if --protocol is set to a variation of smtp.
464 Because it is not defined in the protocol itself, --tls-on-connect is
465 available for any protocol type if the target supports it.
466 -tls
468 Require connection to use STARTTLS. Exit if TLS not available for
469 any reason (not advertised, negotiations failed, etc).
470 -tlso, --tls-optional
472 Attempt to use STARTTLS if available, continue with normal
473 transaction if TLS was unable to be negotiated for any reason
474 -tlsos, --tls-optional-strict
476 Attempt to use STARTTLS if available. Proceed with transaction if
477 TLS is negotiated successfully or STARTTLS not advertised. If
478 STARTTLS is advertised but TLS negotiations fail, treat as an error
479 and abort transaction.
480 --tlsc, --tls-on-connect
482 Initiate a TLS connection immediately on connection. Following
483 common convention, if this option is specified the default port
484 changes from 25 to 465, though this can still be overridden with
485 the --port option.
486 --tls-get-peer-cert [/path/to/file]
488 Get a copy of the TLS peer's certificate. If no argument is given,
489 it will be displayed to STDOUT. If an argument is given it is
490 assumed to be a filesystem path specifying where the certificate
491 should be written. The saved certificate can then be examined
492 using standard tools such as the openssl command. If a file is
493 specified its contents will be overwritten.
494
496 swaks will attempt to authenticate to the target mail server if
497 instructed to do so. This section details available authentication
498 types, requirements, options and their interactions, and other fine
499 points in authentication usage. Because authentication is defined as
500 an extension in the ESMTP protocol it will be unavailable if --protocol
501 is set to a variation of smtp.
502 All authentication methods require base64 encoding. If the
504 MIME::Base64 perl module is loadable swaks attempts to use it to
505 perform these encodings. If MIME::Base64 is not available swaks will
506 use its own onboard base64 routines. These are slower than the
507 MIME::Base64 routines and less reviewed, though they have been tested
508 thoroughly. Using the MIME::Base64 module is encouraged.
509 If authentication is required (see options below for when it is and
511 isn't required) and the requirements aren't met for the authentication
512 type available, swaks displays an error and exits. Two ways this can
513 happen include forcing swaks to use a specific authentication type that
514 swaks can't use due to missing requirements, or allowing swaks to use
515 any authentication type, but the server only advertises types swaks
516 can't support. In the former case swaks errors out at option
517 processing time since it knows up front it won't be able to
518 authenticate. In the latter case swaks will error out at the
519 authentication stage of the smtp transaction since swaks will not be
520 aware that it will not be able to authenticate until that point.
521 Following are the supported authentication types including any
523 individual notes and requirements.
524 The following options affect swaks' use of authentication. These
526 options are all inter-related. For instance, specifying --auth-user
527 implies --auth and --auth-password. Specifying --auth-optional implies
528 --auth-user and --auth-password, etc.
529 -a, --auth [auth-type[,auth-type,...]]
531 Require swaks to authenticate. If no argument is given, any
532 supported auth-types advertised by the server are tried until one
533 succeeds or all fail. If one or more auth-types are specified as
534 an argument, each that the server also supports is tried in order
535 until one succeeds or all fail. This option requires swaks to
536 authenticate, so if no common auth-types are found or no
537 credentials succeed, swaks displays an error and exits.
538 The following tables lists the valid auth-types
540 LOGIN, PLAIN
542 These basic authentication types are fully supported and tested
543 and have no additional requirements
544 CRAM-MD5
546 The CRAM-MD5 authenticator requires the Digest::MD5 module. It
547 is fully tested and believed to work against any server that
548 implements it.
549 DIGEST-MD5
551 The DIGEST-MD5 authenticator (RFC2831) requires the
552 Authen::DigestMD5 module. Only known to have been tested
553 against Communigate and may therefore have some implementation
554 deficiencies.
555 CRAM-SHA1
557 The CRAM-SHA1 authenticator requires the Digest::SHA1 module.
558 This type has only been tested against a non-standard
559 implementation on an Exim server and may therefore have some
560 implementation deficiencies.
561 NTLM/SPA/MSN
563 These authenticators require the Authen::NTLM module. Note
564 that there are two modules using the Authen::NTLM namespace on
565 CPAN. The Mark Bush implementation (Authen/NTLM-1.03.tar.gz)
566 is the version required by swaks. This type has been tested
567 against Exim, Communigate, and Exchange 2007.
568 In addition to the standard username and password, this
570 authentication type can also recognize a "domain". Rather than
571 create a new option for this single authentication type, the
572 domain can be passed by adding "%DOMAIN" to the end of the
573 username. For instance, if "-ap user@example.com%NTDOM" is
574 passed, "user@example.com" is the username and "NTDOM" is the
575 domain. Note that this has never been tested with a mail
576 server that doesn't ignore DOMAIN so this may be implemented
577 incorrectly.
578 -ao, --auth-optional [auth-type[,auth-type,...]]
580 This option behaves identically to --auth except that it requests
581 authentication rather than requiring it. If no common auth-types
582 are found or no credentials succeed, swaks proceeds as if
583 authentication had not been requested.
584 -aos, --auth-optional-strict [auth-type[,auth-type,...]]
586 This option is a compromise between --auth and --auth-optional. If
587 no common auth-types are found, swaks behaves as if --auth-optional
588 were specified and proceeds with the transaction. If swaks can't
589 support requested auth-type, the server doesn't advertise any
590 common auth-types, or if no credentials succeed, swaks behaves as
591 if --auth were used and exits with an error.
592 -au, --auth-user [username]
594 Provide the username to be used for authentication, or prompt the
595 user for it if no argument is provided. The string <> can be
596 supplied to mean an empty username.
597 -ap, --auth-password [password]
599 Provide the password to be used for authentication, or prompt the
600 user for it if no argument is provided. The string <> can be
601 supplied to mean an empty password.
602 -am, --auth-map [auth-alias=auth-type[,...]]
604 Provides a way to map alternate names onto base authentication
605 types. Useful for any sites that use alternate names for common
606 types. This functionality is actually used internally to map types
607 SPA and MSN onto the base type NTLM. The command line argument to
608 simulate this would be "--auth-map SPA=NTLM,MSN=NTLM". All of the
609 auth-types listed above are valid targets for mapping except SPA
610 and MSN.
611 -apt, --auth-plaintext
613 Instead of showing AUTH strings base64 encoded as they are
614 transmitted, translate them to plaintext before printing on screen.
615
617 These options pertain to the contents for the DATA portion of the SMTP
618 transaction.
619 -d, --data [data-portion]
621 Use argument as the entire contents of DATA, or prompt user if no
622 argument specified. If the argument '-' is provided the data will
623 be read from STDIN. If any other argument is provided and it
624 represents the name of an open-able file, the contents of the file
625 will be used. Any other argument will be itself for the DATA
626 contents.
627 The value can be on one single line, with \n (ascii 0x5c, 0x6e)
629 representing where line breaks should be placed. Leading dots will
630 be quoted. Closing dot is not required but is allowed. The
631 default value for this option is "Date: %D\nTo: %T\nFrom:
632 %F\nSubject: test %D\nX-Mailer: swaks v$p_version
633 jetmore.org/john/code/#swaks\n%H\n\n%B\n".
634 Very basic token parsing is performed on the DATA portion. The
636 following table shows the recognized tokens and their replacement
637 values:
638 %F Replaced with the envelope-sender.
640 %T Replaced with the envelope-recipient(s).
642 %D Replaced with the current time in a format suitable for
644 inclusion in the Date: header. Note this attempts to use the
645 standard module Time::Local for timezone calculations. If this
646 module is unavailable the date string will be in GMT.
647 %H Replaced with the contents of the --add-header option. If
649 --add-header is not specified this token is simply removed.
650 %B Replaced with the value specified by the --body option. See
652 --body for default.
653 --body [body-specification]
655 Specify the body of the email. The default is "This is a test
656 mailing". If no argument to --body is given, prompt to supply one
657 interactively. If '-' is supplied, the body will be read from
658 standard input. If any other text is provided and the text
659 represents an open-able file, the content of that file is used as
660 the body. If it does not represent an open-able file, the text
661 itself is used as the body.
662 If the message is forced to MIME format (see --attach) the argument
664 to this option will be included unencoded as the first MIME part.
665 Its content-type will always be text/plain.
666 --attach [attachment-specification]
668 When one or more --attach option is supplied, the message is
669 changed into a multipart/mixed MIME message. The arguments to
670 --attach are processed the same as --body with regard to stdin,
671 file contents, etc. --attach can be supplied multiple times to
672 create multiple attachments. By default each attachment is
673 attached as a application/octet-stream file. See --attach-type for
674 changing this behavior.
675 If a filename is specified, the MIME encoding will include that
677 file name. See --attach-name for more detail on file naming.
678 It is legal for '-' (STDIN) to be specified as an argument multiple
680 times (once for --body and multiple times for --attach). In this
681 case, the same content will be attached each time it is specified.
682 This is useful for attaching the same content with multiple MIME
683 types.
684 --attach-type [mime-type]
686 By default, content that gets MIME attached to a message with the
687 --attach option is encoded as application/octet-stream.
688 --attach-type changes the mime type for every --attach option which
689 follows it. It can be specified multiple times.
690 --attach-name [name]
692 This option sets the filename that will be included in the MIME
693 part created for the next --attach option. If no argument is set
694 for this option, it causes no filename information to be included
695 for the next MIME part, even if swaks could generate it from the
696 local file name.
697 -ah, --add-header [header]
699 This option allows headers to be added to the DATA. If %H is
700 present in the DATA it is replaced with the argument to this
701 option. If %H is not present, the argument is inserted between the
702 first two consecutive newlines in the DATA (that is, it is inserted
703 at the end of the existing headers).
704 The option can either be specified multiple times or a single time
706 with multiple headers seperated by a literal '\n' string. So,
707 "--add-header 'Foo: bar' --add-header 'Baz: foo'" and "--add-header
708 'Foo: bar\nBaz: foo'" end up adding the same two headers.
709 --header [header-and-data], --h-Header [data]
711 These options allow a way to change headers that already exist in
712 the DATA. '--header "Subject: foo"' and '--h-Subject foo' are
713 equivalent. If the header does not already exist in the data then
714 this argument behaves identically to --add-header. However, if the
715 header already exists it is replaced with the one specified.
716 -g If specified, swaks will read the DATA value for the mail from
718 STDIN. This is equivalent to "--data -". If there is a From_ line
719 in the email, it will be removed (but see -nsf option). Useful for
720 delivering real message (stored in files) instead of using example
721 messages.
722 --no-strip-from, -nsf
724 Don't strip the From_ line from the DATA portion, if present.
725
727 By default swaks provides a transcript of its transactions to its
728 caller (STDOUT/STDERR). This transcript aims to be as faithful a
729 representation as possible of the transaction though it does modify
730 this output by adding informational prefixes to lines and by providing
731 plaintext versions of TLS transactions
732 The "informational prefixes" are referred to as transaction hints.
734 These hints are initially composed of those marking lines that are
735 output of swaks itself, either informational or error messages, and
736 those that indicate a line of data actually sent or received in a
737 transaction. This table indicates the hints and their meanings:
738 === Indicates an informational line generated by swaks
740 *** Indicates an error generated within swaks
742 -> Indicates an expected line sent by swaks to target server
744 ~> Indicates a TLS-encrypted, expected line sent by swaks to target
746 server
747 **> Indicates an unexpected line sent by swaks to the target server
749 *~> Indicates a TLS-encrypted, unexpected line sent by swaks to target
751 server
752 <- Indicates an expected line sent by target server to swaks
754 <~ Indicates a TLS-encrypted, expected line sent by target server to
756 swaks
757 <** Indicates an unexpected line sent by target server to swaks
759 <~* Indicates a TLS-encrypted, unexpected line sent by target server to
761 swaks
762 The following options control what and how output is displayed to the
764 caller.
765 -n, --suppress-data
767 Summarizes the DATA portion of the SMTP transaction instead of
768 printing every line. This option is very helpful, bordering on
769 required, when using swaks to send certain test emails. Emails
770 with attachments, for instance, will quickly overwhelm a terminal
771 if the DATA is not supressed.
772 -stl, --show-time-lapse [i]
774 Display time lapse between send/receive pairs. This option is most
775 useful when Time::HiRes is available, in which case the time lapse
776 will be displayed in thousandths of a second. If Time::HiRes is
777 unavailable or "i" is given as an argument the lapse will be
778 displayed in integer seconds only.
779 -nth, --no-hints
781 Don't show transaction hints (useful in conjunction with -hr to
782 create copy/paste-able transactions).
783 -hr, --hide-receive
785 Don't display lines sent from the remote server being received by
786 swaks
787 -hs, --hide-send
789 Don't display lines being sent by swaks to the remote server
790 -hi, --hide-informational
792 Don't display non-error informational lines from swaks itself.
793 -ha, --hide-all
795 Do not display any content to the terminal.
796 -S, --silent [level]
798 Cause swaks to be silent. If no argument is given or if an
799 argument of "1" is given, print no output unless/until an error
800 occurs, after which all output is shown. If an argument of "2" is
801 given, only print errors. If "3" is given, show no output ever.
802 Note that this used to be an additive option ("-S -S" was
804 equivalent to "-S 2"). After environment option handling was
805 introduced this was changed. The additive method still works but
806 is deprecated and will be removed entirely in a future release
807 --support
809 Print capabilities and exit. Certain features require non-standard
810 perl modules. This options evaluates whether these modules are
811 present and displays which functionality is available and which
812 isn't, and which modules would need to be added to gain the missing
813 functionality.
814 --help
816 Display this help information.
817 --version
819 Display version information.
820
822 OPERATING SYSTEMS
823 This program was primarily intended for use on unix-like operating
824 systems, and it should work on any reasonable version thereof. It
825 has been developed and tested on Solaris, Linux, and Mac OS X and
826 is feature complete on all of these.
827 This program is known to demonstrate basic functionality on Windows
829 using ActiveState's Perl. It has not been fully tested. Known to
830 work are basic SMTP functionality and the LOGIN, PLAIN, and
831 CRAM-MD5 auth types. Unknown is any TLS functionality and the
832 NTLM/SPA and Digest-MD5 auth types.
833 Because this program should work anywhere Perl works, I would
835 appreciate knowing about any new operating systems you've
836 thoroughly used swaks on as well as any problems encountered on a
837 new OS.
838 MAIL SERVERS
840 This program was almost exclusively developed against Exim mail
841 servers. It was been used casually by the author, though not
842 thoroughly tested, with Sendmail, Smail, Exchange, Oracle
843 Collaboration Suite, and Communigate. Because all functionality in
844 swaks is based off of known standards it should work with any
845 fairly modern mail server. If a problem is found, please alert the
846 author at the address below.
847
849 0 no errors occurred
850 1 error parsing command line options
852 2 error connecting to remote server
854 3 unknown connection type
856 4 while running with connection type of "pipe", fatal problem writing
858 to or reading from the child process
859 5 while running with connection type of "pipe", child process died
861 unexpectedly. This can mean that the program specified with --pipe
862 doesn't exist.
863 6 Connection closed unexpectedly. If the close is detected in
865 response to the 'QUIT' swaks sends following an unexpected
866 response, the error code for that unexpected response is used
867 instead. For instance, if a mail server returns a 550 response to
868 a MAIL FROM: and then immediately closes the connection, swaks
869 detects that the connection is closed, but uses the more specific
870 exit code 23 to detail the nature of the failure. If instead the
871 server return a 250 code and then immediately closes the
872 connection, swaks will use the exit code 6 because there is not a
873 more specific exit code.
874 10 error in prerequisites (needed module not available)
876 21 error reading initial banner from server
878 22 error in HELO transaction
880 23 error in MAIL transaction
882 24 no RCPTs accepted
884 25 server returned error to DATA request
886 26 server did not accept mail following data
888 27 server returned error after normal-session quit request
890 28 error in AUTH transaction
892 29 error in TLS transaction
894 32 error in EHLO following TLS negotiation
896
898 proj-swaks@jetmore.net
899 Please use this address for general contact, questions, patches,
900 requests, etc.
901 updates-swaks@jetmore.net
903 If you would like to be put on a list to receive notifications when
904 a new version of swaks is released, please send an email to this
905 address.
906 http://www.jetmore.org/john/code/swaks/
908 Change logs, this help, and the latest version is found at this
909 link.
910perl v5.10.1 2010-02-12 SWAKS(1)