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 --auth-user me@example.com --header-X-Test "test email"
30 Test a virus scanner using EICAR in an attachment. Don't show the
32 message DATA part.:
33 swaks -t user@example.com --attach - --server test-server.example.com --suppress-data </path/to/eicar.txt
35 Test a spam scanner using GTUBE in the body of an email, routed via the
37 MX records for example.com:
38 swaks --to user@example.com --body /path/to/gtube/file
40 Deliver a standard test email to user@example.com using the LMTP
42 protocol via a UNIX domain socket file
43 swaks --to user@example.com --socket /var/lda.sock --protocol LMTP
45 Report all the recipients in a text file that are non-verifiable on a
47 test server:
48 for E in `cat /path/to/email/file`
50 do
51 swaks --to $E --server test-server.example.com --quit-after RCPT --hide-all
52 [ $? -ne 0 ] && echo $E
53 done
54
56 This document tries to be consistent and specific in its use of the
57 following terms to reduce confusion.
58 Transaction
60 A transaction is the opening of a connection over a transport to a
61 target and using a messaging protocol to attempt to deliver a
62 message.
63 Target
65 The target of a transaction is the thing that Swaks connects to.
66 This generic term is used throughout the documentation because most
67 other terms improperly imply something about the transport being
68 used.
69 Transport
71 The transport is the underlying method used to connect to the
72 target.
73 Protocol
75 The protocol is the application language used to communicate with
76 the target. This document uses SMTP to speak generically of all
77 three supported protocols unless it states that it is speaking of
78 the specific 'SMTP' protocol and excluding the others.
79 Message
81 SMTP protocols exist to transfer messages, a set of bytes in an
82 agreed-upon format that has a sender and a recipient.
83 Envelope
85 A message's envelope contains the "true" sender and receiver of a
86 message. It can also be referred to as its components, envelope-
87 sender and envelope-recipients. It is important to note that a
88 messages envelope does not have to match its To: and From: headers.
89 DATA
91 The DATA portion of an SMTP transaction is the actual message that
92 is being transported. It consists of both the message's headers
93 and its body. DATA and body are sometimes use synonymously, but
94 they are always two distinct things in this document.
95 Headers
97 A message's headers are defined as all the lines in the message's
98 DATA section before the first blank line. They contain information
99 about the email that will be displayed to the recipient such as
100 To:, From:, Subject:, etc. In this document headers will always be
101 written with a capitalized first letter and a trailing colon.
102 Body
104 A message's body is the portion of its DATA section following the
105 first blank line.
106
108 To prevent potential confusion in this document a flag to Swaks is
109 always referred to as an "option". If the option takes additional
110 data, that additional data is referred to as an argument to the option.
111 For example, "--from fred@example.com" might be provided to Swaks on
112 the command line, with "--from" being the option and "fred@example.com"
113 being --from's argument.
114 Options can be given to Swaks in three ways. They can be specified in
116 a configuration file, in environment variables, and on the command
117 line. Depending on the specific option and whether an argument is
118 given to it, Swaks may prompt the user for the argument.
119 When Swaks evaluates its options, it first looks for a configuration
121 file (either in a default location or specified with --config). Then
122 it evaluates any options in environment variables. Finally, it
123 evaluates command line options. At each round of processing, any
124 options set earlier will be overridden. Additionally, any option can
125 be prefixed with "no-" to cause Swaks to forget that the variable had
126 previously been set (either in an earlier round, or earlier in the same
127 round). This capability is necessary because many options treat
128 defined-but-no-argument differently than not-defined.
129 As a general rule, if the same option is given multiple time, the last
131 time it is given is the one that will be used. This applies to both
132 intra-method (if "--from user1@example.com --from user2@example.com" is
133 given, user2@example.com will be used) and inter-method (if "from
134 user1@example.com" is given in a config file and "--from
135 user2@example.com" is given on the command line, user2@example.com will
136 be used)
137 The exact mechanism and format for using each of the types is listed
139 below.
140 CONFIGURATION FILES
142 A configuration file can be used to set commonly-used or abnormally
143 verbose options. By default, Swaks looks in order for
144 $SWAKS_HOME/.swaksrc, $HOME/.swaksrc, and $LOGDIR/.swaksrc. If one
145 of those is found to exist (and --config has not been used) that
146 file is used as the configuration file.
147 Additionally, a configuration file in a non-default location can be
149 specified using --config. If this is set and not given an argument
150 Swaks will not use any configuration file, including any default
151 file. If --config points to a readable file, it is used as the
152 configuration file, overriding any default that may exist. If it
153 points to a non-readable file an error will be shown and Swaks will
154 exit.
155 A set of "portable" defaults can also be created by adding options
157 to the end of the Swaks program file. As distributed, the last
158 line of Swaks should be "__END__". Any lines added after __END__
159 will be treated as the contents of a configuration file. This
160 allows a set of user preferences to be automatically copied from
161 server to server in a single file.
162 If configuration files have not been explicitly turned off, the
164 __END__ config is always read. Only one other configuration file
165 will ever be used per single invocation of Swaks, even if multiple
166 configuration files are specified. If the __END__ config and
167 another config are to be read, the __END__ config will be processed
168 first. Specifying the --config option with no argument turns off
169 the processing of both the __END__ config and any actual config
170 files.
171 In a configuration file lines beginning with a hash (#) are
173 ignored. All other lines are assumed to be an option to Swaks,
174 with the leading dash or dashes optional. Everything after a
175 option line's first space is assumed to be the option's argument
176 and is not shell processed. Therefore, quoting is usually unneeded
177 and will be included literally in the argument. Here is an example
178 of the contents of a configuration file:
179 # always use this sender, no matter server or logged in user
181 --from fred@example.com
182 # I prefer my test emails have a pretty from header. Note
183 # the lack of dashes on option and lack of quotes around
184 # entire argument.
185 h-From: "Fred Example" <fred@example.com>
186 Options specific to configuration file:
188 --config [/path/to/config]
190 This option provides a path to a specific configuration file to
191 be used. If specified with no argument, no automatically-found
192 configuration file (via $HOME, etc, or __END__) will be
193 processed. If the argument is a valid file, that file will be
194 used as the configuration file (after __END__ config). If
195 option is not a valid, readable file, Swaks will error and
196 exit. This option can be specified multiple times, but only
197 the first time it is specified (in environment variable and the
198 command line search order) will be used.
199 ENVIRONMENT VARIABLES
201 Options can be supplied via environment variables. The variables
202 are in the form $SWAKS_OPT_name, where name is the name of the
203 option that would be specified on the command line. Because dashes
204 aren't allowed in environment variable names in most UNIX-ish
205 shells, no leading dashes should be used and any dashes inside the
206 option's name should be replaced with underscores. The following
207 would create the same options shown in the configuration file
208 example:
209 $ SWAKS_OPT_from='fred@example.com'
211 $ SWAKS_OPT_h_From='"Fred Example" <fred@example.com>'
212 Setting a variable to an empty value is the same as specifying it
214 on the command line with no argument. For instance, setting
215 SWAKS_OPT_server="" would cause Swaks to prompt the use for the
216 server to which to connect at each invocation.
217 Because there is no inherent order in options provided by setting
219 environment variables, the options are sorted before being
220 processed. This is not a great solution, but it at least defines
221 the behavior, which would be otherwise undefined. As an example,
222 if both SWAKS_OPT_from and SWAKS_OPT_f were set, the value from
223 SWAKS_OPT_from would be used, because it sorts after SWAKS_OPT_f.
224 Also as a result of not having an inherent order in environment
225 processing, unsetting options with the "no-" prefix is unreliable.
226 It works if the option being turned off sorts before "no-", but
227 fails if it sorts after. Because "no-" is primarily meant to
228 operate between config types (for instance, unsetting from the
229 command line an option that was set in a config file), this is not
230 likely to be a problem.
231 In addition to setting the equivalent of command line options,
233 SWAKS_HOME can be set to a directory containing the default
234 .swaksrc to be used.
235 COMMAND LINE OPTIONS
237 The final method of supplying options to Swaks is via the command
238 line. The options behave in a manner consistent with most UNIX-ish
239 command line programs. Many options have both a short and long
240 form (for instance -s and --server). By convention short options
241 are specified with a single dash and long options are specified
242 with a double-dash. This is only a convention and either prefix
243 will work with either type.
244 The following demonstrates the example shown in the configuration
246 file and environment variable sections:
247 $ swaks --from fred@example.com --h-From: '"Fred Example" <fred@example.com>'
249
251 Swaks can connect to a target via UNIX pipes ("pipes"), UNIX domain
252 sockets ("UNIX sockets"), or internet domain sockets ("network
253 sockets"). Connecting via network sockets is the default behavior.
254 Because of the singular nature of the transport used, each set of
255 options in the following section is mutually exclusive. Specifying
256 more than one of --server, --pipe, or --socket will result in an error.
257 Mixing other options between transport types will only result in the
258 irrelevant options being ignored. Below is a brief description of each
259 type of transport and the options that are specific to that transport
260 type.
261 NETWORK SOCKETS
263 This transport attempts to deliver a message via TCP/IP, the
264 standard method for delivering SMTP. This is the default transport
265 for Swaks. If none of --server, --pipe, or --socket are given then
266 this transport is used and the target server is determined from the
267 recipient's domain (see --server below for more details).
268 This transport requires the IO::Socket module which is part of the
270 standard Perl distribution. If this module is not loadable,
271 attempting to use this transport will result in an error and
272 program termination.
273 IPv6 is supported when the IO::Socket::INET6 module is present.
275 -s, --server [target mail server[:port]]
277 Explicitly tell Swaks to use network sockets and specify the
278 hostname or IP address to which to connect, or prompt if no
279 argument is given. If this option is not given and no other
280 transport option is given, the target mail server is determined
281 from the appropriate DNS records for the domain of the
282 recipient email address using the Net::DNS module. If Net::DNS
283 is not available Swaks will attempt to connect to localhost to
284 deliver. The target port can optionally be set here.
285 Supported formats for this include SERVER:PORT (supporting
286 names and IPv4 addresses); [SERVER]:PORT and SERVER/PORT
287 (supporting names, IPv4 and IPv6 addresses). See also
288 --copy-routing.
289 -p, --port [port]
291 Specify which TCP port on the target is to be used, or prompt
292 if no argument is listed. The argument can be a service name
293 (as retrieved by getservbyname(3)) or a port number. The
294 default port is smtp/25 unless influenced by the --protocol or
295 --tls-on-connect options.
296 -li, --local-interface [IP or hostname[:port]]
298 Use argument as the local interface for the outgoing SMTP
299 connection, or prompt user if no argument given. Argument can
300 be an IP address or a hostname. Default action is to let the
301 operating system choose the local interface. See --server for
302 additional comments on :port format.
303 -lp, --local-port, --lport [port]
305 Specify the outgoing port to originate the transaction from.
306 If this option is not specified the system will pick an
307 ephemeral port. Note that regular users cannot specify some
308 ports.
309 --copy-routing [domain]
311 The argument is interpreted as the domain part of an email
312 address and it is used to find the target server using the same
313 logic that would be used to look up the target server for a
314 recipient email address. See --to option for more details on
315 how the target is determined from the email domain.
316 -4, -6
318 Force IPv4 or IPv6.
319 UNIX SOCKETS
321 This transport method attempts to deliver messages via a UNIX-
322 domain socket file. This is useful for testing MTA/MDAs that
323 listen on socket files (for instance, testing LMTP delivery to
324 Cyrus). This transport requires the IO::Socket module which is
325 part of the standard Perl distribution. If this module is not
326 loadable, attempting to use this transport will result in an error
327 and program termination.
328 --socket [/path/to/socket/file]
330 This option takes as its argument a UNIX-domain socket file.
331 If Swaks is unable to open this socket it will display an error
332 and exit.
333 PIPES
335 This transport attempts to spawn a process and communicate with it
336 via pipes. The spawned program must be prepared to behave as a
337 mail server over STDIN/STDOUT. Any MTA designed to operate from
338 inet/xinet should support this. In addition, some MTAs provide
339 testing modes that can be communicated with via STDIN/STDOUT. This
340 transport can be used to automate that testing. For example, if
341 you implemented DNSBL checking with Exim and you wanted to make
342 sure it was working, you could run 'swaks --pipe "exim -bh
343 127.0.0.2"'. Ideally, the process you are talking to should behave
344 exactly like an SMTP server on STDIN and STDOUT. Any debugging
345 should be sent to STDERR, which will be directed to your terminal.
346 In practice, Swaks can generally handle some debug on the child's
347 STDOUT, but there are no guarantees on how much it can handle.
348 This transport requires the IPC::Open2 module which is part of the
350 standard Perl distribution. If this module is not loadable,
351 attempting to use this transport will result in an error and
352 program termination.
353 --pipe [/path/to/command and arguments]
355 Provide a process name and arguments to the process. Swaks
356 will attempt to spawn the process and communicate with it via
357 pipes. If the argument is not an executable Swaks will display
358 an error and exit.
359
361 These options are related to the protocol layer.
362 -t, --to [email-address[,email-address,...]]
364 Tells Swaks to use argument(s) as the envelope-recipient for the
365 email, or prompt for recipient if no argument provided. If
366 multiple recipients are provided and the recipient domain is needed
367 to determine routing the domain of the last recipient provided is
368 used.
369 There is no default value for this option. If no recipients are
371 provided via any means, user will be prompted to provide one
372 interactively. The only exception to this is if a --quit-after
373 value is provided which will cause the SMTP transaction to be
374 terminated before the recipient is needed.
375 -f, --from [email-address]
377 Use argument as envelope-sender for email, or prompt user if no
378 argument specified. The string <> can be supplied to mean the null
379 sender. If user does not specify a sender address a default value
380 is used. The domain-part of the default sender is a best guess at
381 the fully-qualified domain name of the local host. The method of
382 determining the local-part varies. On Windows, Win32::LoginName()
383 is used. On UNIX-ish platforms, the $LOGNAME environment variable
384 is used if it is set. Otherwise getpwuid(3) is used. See also
385 --force-getpwuid. If Swaks cannot determine a local hostname and
386 the sender address is needed for the transaction, Swaks will error
387 and exit. In this case, a valid string must be provided via this
388 option.
389 --ehlo, --lhlo, -h, --helo [helo-string]
391 String to use as argument to HELO/EHLO/LHLO command, or prompt user
392 if no argument is specified. If this option is not used a best
393 guess at the fully-qualified domain name of the local host is used.
394 If Swaks cannot determine a local hostname and the helo string is
395 needed for the transaction, Swaks will error and exit. In this
396 case, a valid string must be provided via this option.
397 -q, --quit, --quit-after [stop-point]
399 Point at which the transaction should be stopped. When the
400 requested stopping point is reached in the transaction, and
401 provided that Swaks has not errored out prior to reaching it, Swaks
402 will send "QUIT" and attempt to close the connection cleanly.
403 These are the valid arguments and notes about their meaning.
404 CONNECT, BANNER
406 Terminate the session after receiving the greeting banner from
407 the target.
408 FIRST-HELO, FIRST-EHLO, FIRST-LHLO
410 In a STARTTLS (but not tls-on-connect) session, terminate the
411 transaction after the first of two HELOs. In a non-STARTTLS
412 transaction, behaves the same as HELO (see below).
413 XCLIENT
415 Quit after XCLIENT is sent.
416 STARTTLS, TLS
418 Quit the transaction immediately following TLS negotiation.
419 Note that this happens in different places depending on whether
420 STARTTLS or tls-on-connect are used. This always quits after
421 the point where TLS would have been negotiated, regardless of
422 whether it was attempted.
423 HELO, EHLO, LHLO
425 In a STARTTLS or XCLIENT session, quit after the second HELO.
426 Otherwise quit after the first and only HELO.
427 AUTH
429 Quit after authentication. This always quits after the point
430 where authentication would have been negotiated, regardless of
431 whether it was attempted.
432 MAIL, FROM
434 Quit after MAIL FROM: is sent.
435 RCPT, TO
437 Quit after RCPT TO: is sent.
438 --da, --drop-after [stop-point]
440 The option is similar to --quit-after, but instead of trying to
441 cleanly shut down the session it simply terminates the session.
442 This option accepts the same stop-points as --quit-after and
443 additionally accepts DATA and DOT, detailed below.
444 DATA
446 Quit after DATA is sent.
447 DOT Quit after the final '.' of the message is sent.
449 --das, --drop-after-send [stop-point]
451 This option is similar to --drop-after, but instead of dropping the
452 connection after reading a response to the stop-point, it drops the
453 connection immediately after sending stop-point. It accepts the
454 same stop-points as --drop-after.
455 --timeout [time]
457 Use argument as the SMTP transaction timeout, or prompt user if no
458 argument given. Argument can either be a pure digit, which will be
459 interpreted as seconds, or can have a specifier s or m (5s = 5
460 seconds, 3m = 180 seconds). As a special case, 0 means don't
461 timeout the transactions. Default value is 30s.
462 --protocol [protocol]
464 Specify which protocol to use in the transaction. Valid options
465 are shown in the table below. Currently the 'core' protocols are
466 SMTP, ESMTP, and LMTP. By using variations of these protocol types
467 one can tersely specify default ports, whether authentication
468 should be attempted, and the type of TLS connection that should be
469 attempted. The default protocol is ESMTP. This table demonstrates
470 the available arguments to --protocol and the options each sets as
471 a side effect:
472 SMTP
474 HELO, "-p 25"
475 SSMTP
477 EHLO->HELO, "-tlsc -p 465"
478 SSMTPA
480 EHLO->HELO, "-a -tlsc -p 465"
481 SMTPS
483 HELO, "-tlsc -p 465"
484 ESMTP
486 EHLO->HELO, "-p 25"
487 ESMTPA
489 EHLO->HELO, "-a -p 25"
490 ESMTPS
492 EHLO->HELO, "-tls -p 25"
493 ESMTPSA
495 EHLO->HELO, "-a -tls -p 25"
496 LMTP
498 LHLO, "-p 24"
499 LMTPA
501 LHLO, "-a -p 24"
502 LMTPS
504 LHLO, "-tls -p 24"
505 LMTPSA
507 LHLO, "-a -tls -p 24"
508 --pipeline
510 If the remote server supports it, attempt SMTP PIPELINING (RFC
511 2920).
512 --prdr
514 If the server supports it, attempt Per-Recipient Data Response
515 (PRDR) (https://tools.ietf.org/html/draft-hall-prdr-00.txt). PRDR
516 is not yet standardized, but MTAs have begun implementing the
517 proposal.
518 --force-getpwuid
520 Tell Swaks to use the getpwuid method of finding the default sender
521 local-part instead of trying $LOGNAME first.
522
524 These are options related to encrypting the transaction. These have
525 been tested and confirmed to work with all three transport methods.
526 The Net::SSLeay module is used to perform encryption when it is
527 requested. If this module is not loadable Swaks will either ignore the
528 TLS request or error out, depending on whether the request was
529 optional. STARTTLS is defined as an extension in the ESMTP protocol
530 and will be unavailable if --protocol is set to a variation of SMTP.
531 Because it is not defined in the protocol itself, --tls-on-connect is
532 available for any protocol type if the target supports it.
533 A local certificate is not required for a TLS connection to be
535 negotiated. However, some servers use client certificate checking to
536 verify that the client is allowed to connect. Swaks can be told to use
537 a specific local certificate using the --tls-cert and --tls-key
538 options.
539 -tls
541 Require connection to use STARTTLS. Exit if TLS not available for
542 any reason (not advertised, negotiations failed, etc).
543 -tlso, --tls-optional
545 Attempt to use STARTTLS if available, continue with normal
546 transaction if TLS was unable to be negotiated for any reason.
547 Note that this is a semi-useless option as currently implemented
548 because after a negotiation failure the state of the connection is
549 unknown. In some cases, like a version mismatch, the connection
550 should be left as plaintext. In others, like a verification
551 failure, the server-side may think that it should continue speaking
552 TLS while the client thinks it is plaintext. There may be an
553 attempt to add more granular state detection in the future, but for
554 now just be aware that odd things may happen with this option if
555 the TLS negotiation is attempted and fails.
556 -tlsos, --tls-optional-strict
558 Attempt to use STARTTLS if available. Proceed with transaction if
559 TLS is negotiated successfully or STARTTLS not advertised. If
560 STARTTLS is advertised but TLS negotiations fail, treat as an error
561 and abort transaction. Due to the caveat noted above, this is a
562 much saner option than --tls-optional.
563 --tlsc, --tls-on-connect
565 Initiate a TLS connection immediately on connection. Following
566 common convention, if this option is specified the default port
567 changes from 25 to 465, though this can still be overridden with
568 the --port option.
569 -tlsp, --tls-protocol SPECIFICATION
571 Specify which protocols to use (or not use) when negotiating TLS.
572 At the time of this writing, the available protocols are sslv2,
573 sslv3, tlsv1, tlsv1_1, tlsv1_2, and tlsv1_3. The availability of
574 these protocols is dependent on your underlying OpenSSL library, so
575 not all of these may be available. The list of available protocols
576 is shown in the output of --dump (assuming TLS is available at
577 all).
578 The specification string is a comma-delimited list of protocols
580 that can be used or not used. For instance 'tlsv1,tlsv1_1' will
581 only succeed if one of those two protocols is available on both the
582 client and the server. Conversely, 'no_sslv2,no_sslv3' will
583 attempt to negotiate any protocol except sslv2 and sslv3. The two
584 forms of specification cannot be mixed.
585 -tls-cipher CIPHER_STRING
587 The argument to this option is passed to the underlying OpenSSL
588 library to set the list of acceptable ciphers to the be used for
589 the connection. The format of this string is opaque to Swaks and
590 is defined in
591 http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT.
592 A brief example would be --tls-cipher '3DES:+RSA'.
593 --tls-verify
595 Tell Swaks to attempt to verify the server's certificate. If this
596 option is set and the server's certificate is not verifiable
597 (either using the system-default CA information, or custom CA
598 information (see --tls-ca-path)) TLS negotiation will not succeed.
599 By default, Swaks does not attempt certificate verification.
600 --tls-ca-path [ /path/to/CAfile | /path/to/CAdir/ ]
602 Specify an alternate location for CA information for verifying
603 server certificates. The default behavior is to use the underlying
604 OpenSSL library's default information.
605 --tls-cert /path/to/file
607 Provide a path to a file containing the local certificate Swaks
608 should use if TLS is negotiated. The file path argument is
609 required. As currently implemented the certificate in the file
610 must be in PEM format. Contact the author if there's a compelling
611 need for ASN1. If this option is set, --tls-key is also required.
612 --tls-key /path/to/file
614 Provide a path to a file containing the local private key Swaks
615 should use if TLS is negotiated. The file path argument is
616 required. As currently implemented the certificate in the file
617 must be in PEM format. Contact the author if there's a compelling
618 need for ASN1. If this option is set, --tls-cert is also required.
619 --tls-get-peer-cert [/path/to/file]
621 Get a copy of the TLS peer's certificate. If no argument is given,
622 it will be displayed to STDOUT. If an argument is given it is
623 assumed to be a filesystem path specifying where the certificate
624 should be written. The saved certificate can then be examined
625 using standard tools such as the openssl command. If a file is
626 specified its contents will be overwritten.
627
629 Swaks will attempt to authenticate to the target mail server if
630 instructed to do so. This section details available authentication
631 types, requirements, options and their interactions, and other fine
632 points in authentication usage. Because authentication is defined as
633 an extension in the ESMTP protocol it will be unavailable if --protocol
634 is set to a variation of SMTP.
635 All authentication methods require base64 encoding. If the
637 MIME::Base64 Perl module is loadable Swaks attempts to use it to
638 perform these encodings. If MIME::Base64 is not available Swaks will
639 use its own onboard base64 routines. These are slower than the
640 MIME::Base64 routines and less reviewed, though they have been tested
641 thoroughly. Using the MIME::Base64 module is encouraged.
642 If authentication is required (see options below for when it is and
644 isn't required) and the requirements aren't met for the authentication
645 type available, Swaks displays an error and exits. Two ways this can
646 happen include forcing Swaks to use a specific authentication type that
647 Swaks can't use due to missing requirements, or allowing Swaks to use
648 any authentication type, but the server only advertises types Swaks
649 can't support. In the former case Swaks errors out at option
650 processing time since it knows up front it won't be able to
651 authenticate. In the latter case Swaks will error out at the
652 authentication stage of the SMTP transaction since Swaks will not be
653 aware that it will not be able to authenticate until that point.
654 Following are the supported authentication types including any
656 individual notes and requirements.
657 The following options affect Swaks' use of authentication. These
659 options are all inter-related. For instance, specifying --auth-user
660 implies --auth and --auth-password. Specifying --auth-optional implies
661 --auth-user and --auth-password, etc.
662 -a, --auth [auth-type[,auth-type,...]]
664 Require Swaks to authenticate. If no argument is given, any
665 supported auth-types advertised by the server are tried until one
666 succeeds or all fail. If one or more auth-types are specified as
667 an argument, each that the server also supports is tried in order
668 until one succeeds or all fail. This option requires Swaks to
669 authenticate, so if no common auth-types are found or no
670 credentials succeed, Swaks displays an error and exits.
671 The following tables lists the valid auth-types
673 LOGIN, PLAIN
675 These basic authentication types are fully supported and tested
676 and have no additional requirements
677 CRAM-MD5
679 The CRAM-MD5 authenticator requires the Digest::MD5 module. It
680 is fully tested and believed to work against any server that
681 implements it.
682 DIGEST-MD5
684 The DIGEST-MD5 authenticator (RFC2831) requires the
685 Authen::SASL module. Version 20100211.0 and earlier used
686 Authen::DigestMD5 which had some protocol level errors which
687 prevented it from working with some servers. Authen::SASL's
688 DIGEST-MD5 handling is much more robust.
689 The DIGEST-MD5 implementation in Swaks is fairly immature. It
691 currently supports only the "auth" qop type, for instance. If
692 you have DIGEST-MD5 experience and would like to help Swaks
693 support DIGEST-MD5 better, please get in touch with me.
694 The DIGEST-MD5 protocol's "realm" value can be set using the
696 --auth-extra "realm" keyword. If no realm is given, a
697 reasonable default will be used.
698 The DIGEST-MD5 protocol's "digest-uri" values can be set using
700 the --auth-extra option. For instance, you could create the
701 digest-uri-value of "lmtp/mail.example.com/example.com" with
702 the option "--auth-extra
703 dmd5-serv-type=lmtp,dmd5-host=mail.example.com,dmd5-serv-name=example.com".
704 The "digest-uri-value" string and its components is defined in
705 RFC2831. If none of these values are given, reasonable
706 defaults will be used.
707 CRAM-SHA1
709 The CRAM-SHA1 authenticator requires the Digest::SHA module.
710 This type has only been tested against a non-standard
711 implementation on an Exim server and may therefore have some
712 implementation deficiencies.
713 NTLM/SPA/MSN
715 These authenticators require the Authen::NTLM module. Note
716 that there are two modules using the Authen::NTLM namespace on
717 CPAN. The Mark Bush implementation (Authen/NTLM-1.03.tar.gz)
718 is the version required by Swaks. This type has been tested
719 against Exim, Communigate, and Exchange 2007.
720 In addition to the standard username and password, this
722 authentication type can also recognize a "domain". The domain
723 can be set using the --auth-extra "domain" keyword. Note that
724 this has never been tested with a mail server that doesn't
725 ignore DOMAIN so this may be implemented incorrectly.
726 -ao, --auth-optional [auth-type[,auth-type,...]]
728 This option behaves identically to --auth except that it requests
729 authentication rather than requiring it. If no common auth-types
730 are found or no credentials succeed, Swaks proceeds as if
731 authentication had not been requested.
732 -aos, --auth-optional-strict [auth-type[,auth-type,...]]
734 This option is a compromise between --auth and --auth-optional. If
735 no common auth-types are found, Swaks behaves as if --auth-optional
736 were specified and proceeds with the transaction. If Swaks can't
737 support requested auth-type, the server doesn't advertise any
738 common auth-types, or if no credentials succeed, Swaks behaves as
739 if --auth were used and exits with an error.
740 -au, --auth-user [username]
742 Provide the username to be used for authentication, or prompt the
743 user for it if no argument is provided. The string <> can be
744 supplied to mean an empty username.
745 -ap, --auth-password [password]
747 Provide the password to be used for authentication, or prompt the
748 user for it if no argument is provided. The string <> can be
749 supplied to mean an empty password.
750 -ae, --auth-extra [KEYWORD=value[,...]]
752 Some of the authentication types allow extra information to be
753 included in the authentication process. Rather than add a new
754 option for every nook and cranny of each authenticator, the
755 --auth-extra option allows this information to be supplied.
756 The following table lists the currently recognized keywords and the
758 authenticators that use them
759 realm, domain
761 The realm and domain keywords are synonymous. Using either
762 will set the "domain" option in NTLM/MSN/SPA and the "realm"
763 option in DIGEST-MD5
764 dmd5-serv-type
766 The dmd5-serv-type keyword is used by the DIGEST-MD5
767 authenticator and is used, in part, to build the digest-uri-
768 value string (see RFC2831)
769 dmd5-host
771 The dmd5-host keyword is used by the DIGEST-MD5 authenticator
772 and is used, in part, to build the digest-uri-value string (see
773 RFC2831)
774 dmd5-serv-name
776 The dmd5-serv-name keyword is used by the DIGEST-MD5
777 authenticator and is used, in part, to build the digest-uri-
778 value string (see RFC2831)
779 -am, --auth-map [auth-alias=auth-type[,...]]
781 Provides a way to map alternate names onto base authentication
782 types. Useful for any sites that use alternate names for common
783 types. This functionality is actually used internally to map types
784 SPA and MSN onto the base type NTLM. The command line argument to
785 simulate this would be "--auth-map SPA=NTLM,MSN=NTLM". All of the
786 auth-types listed above are valid targets for mapping except SPA
787 and MSN.
788 -apt, --auth-plaintext
790 Instead of showing AUTH strings base64 encoded as they are
791 transmitted, translate them to plaintext before printing on screen.
792 -ahp, --auth-hide-password [replacement string]
794 If this option is specified, any time a readable password would be
795 printed to the terminal (specifically AUTH PLAIN and AUTH LOGIN)
796 the password is replaced with the string 'PROVIDED_BUT_REMOVED' (or
797 the contents of "replacement string" if provided). The dummy
798 string may or may not be base64 encoded, contingent on the
799 --auth-plaintext option.
800 Note that --auth-hide-password is similar, but not identical, to
802 the --protect-prompt option. The former protects passwords from
803 being displayed in the SMTP transaction regardless of how they are
804 entered. The latter protects sensitive strings when the user types
805 them at the terminal, regardless of how the string would be used.
806
808 XCLIENT is an SMTP extension introduced by the Postfix project.
809 XCLIENT allows a (properly-authorized) client to tell a server to use
810 alternate information, such as IP address or hostname, for the client.
811 This allows much easier paths for testing mail server configurations.
812 Full details on the protocol are available at
813 http://www.postfix.org/XCLIENT_README.html.
814 The XCLIENT verb can be passed to the server multiple times per SMTP
816 session with different attributes. For instance, HELO and PROTO might
817 be passed in one call and NAME and ADDR passed in a second. Because it
818 can be useful for testing, Swaks exposes some control over how the
819 attributes are grouped and in what order they are passed to the server.
820 The different options attempt to expose simplicity for those using
821 Swaks as a client, and complexity for those using Swaks to test
822 installs.
823 --xclient-addr [VALUE]
825 --xclient-name [VALUE]
826 --xclient-port [VALUE]
827 --xclient-proto [VALUE]
828 --xclient-destaddr [VALUE]
829 --xclient-destport [VALUE]
830 --xclient-helo [VALUE]
831 --xclient-login [VALUE]
832 --xclient-reverse-name [VALUE]
833 These options specify XCLIENT attributes that should be sent to the
834 target server. If [VALUE] is not provided, Swaks will prompt and
835 read the value on STDIN. See
836 http://www.postfix.org/XCLIENT_README.html for official
837 documentation for what the attributes mean and their possible
838 values, including the special "[UNAVAILABLE]" and "[TEMPUNAVAIL]"
839 values.
840 By way of simple example, setting "--xclient-name foo.example.com
842 --xclient-addr 192.168.1.1" will cause Swaks to send the SMTP
843 command "XCLIENT NAME=foo.example.com ADDR=192.168.1.1".
844 Note that the "REVERSE_NAME" attribute doesn't seem to appear in
846 the official documentation. There is a mailing list thread that
847 documents it, viewable at
848 http://comments.gmane.org/gmane.mail.postfix.user/192623.
849 These options can all be mixed with each other, and can be mixed
851 with the --xclient option (see below). By default all attributes
852 will be combined into one XCLIENT call, but see --xclient-delim.
853 --xclient-delim
855 When this option is specified, it indicates a break in XCLIENT
856 attributes to be sent. For instance, setting "--xclient-helo 'helo
857 string' --xclient-delim --xclient-name foo.example.com
858 --xclient-addr 192.168.1.1" will cause Swaks to send two XCLIENT
859 calls, "XCLIENT HELO=helo+20string" and "XCLIENT
860 NAME=foo.example.com ADDR=192.168.1.1". This option is ignored
861 where it doesn't make sense (at the start or end of XCLIENT
862 options, by itself, consecutively, etc).
863 --xclient [XCLIENT_STRING]
865 This is the "free form" XCLIENT option. Whatever value is provided
866 for XCLIENT_STRING will be sent verbatim as the argument to the
867 XCLIENT SMTP command. For example, if "--xclient 'NAME=
868 ADDR=192.168.1.1 FOO=bar'" is used, Swaks will send the SMTP
869 command "XCLIENT NAME= ADDR=192.168.1.1 FOO=bar". If no
870 XCLIENT_STRING is passed on command line, Swaks will prompt and
871 read the value on STDIN.
872 The primary advantage to this over the more specific options above
874 is that there is no XCLIENT syntax validation here. This allows
875 you to send invalid XCLIENT to the target server for testing.
876 Additionally, at least one MTA (Message Systems' Momentum, formerly
877 ecelerity) implements XCLIENT without advertising supported
878 attributes. The --xclient option allows you to skip the "supported
879 attributes" check when communicating with this type of MTA (though
880 see also --xclient-no-verify).
881 The --xclient option can be mixed freely with the --xclient-*
883 options above. The argument to --xclient will be sent in its own
884 command group. For instance, if "--xclient-addr 192.168.0.1
885 --xclient-port 26 --xclient 'FOO=bar NAME=wind'" is given to Swaks,
886 "XCLIENT ADDR=192.168.0.1 PORT=26" and "XCLIENT FOO=bar NAME=wind"
887 will both be sent to the target server.
888 --xclient-no-verify
890 Do not enforce the requirement that an XCLIENT attribute must be
891 advertised by the server in order for Swaks to send it in an
892 XCLIENT command. This is to support servers which don't advertise
893 the attributes but still support them.
894 --xclient-before-starttls
896 If Swaks is configured to attempt both XCLIENT and STARTTLS, it
897 will do STARTTLS first. If this option is specified it will
898 attempt XCLIENT first.
899 --xclient-optional
901 --xclient-optional-strict
902 In normal operation, setting one of the --xclient* options will
903 require a successful XCLIENT transaction to take place in order to
904 proceed (that is, XCLIENT needs to be advertised, all the user-
905 requested attributes need to have been advertised, and the server
906 needs to have accepted Swaks' XCLIENT request). These options
907 change that behavior. --xclient-optional tells Swaks to proceed
908 unconditionally past the XCLIENT stage of the SMTP transaction,
909 regardless of whether it was successful. --xclient-optional-strict
910 is similar but more granular. The strict version will continue to
911 XCLIENT was not advertised, but will fail if XCLIENT was attempted
912 but did not succeed.
913
915 Swaks implements the Proxy protocol as defined in
916 http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt. Proxy
917 allows an application load balancer, such as HAProxy, to be used in
918 front of an MTA while still allowing the MTA access to the originating
919 host information. Proxy support in Swaks allows direct testing of an
920 MTA configured to expect requests from a proxy, bypassing the proxy
921 itself during testing.
922 Swaks makes no effort to ensure that the Proxy options used are
924 internally consistent. For instance, --proxy-family (in version 1) is
925 expected to be one of "TCP4" or "TCP6". While it will likely not make
926 sense to the target server, Swaks makes no attempt to ensure that
927 --proxy-source and --proxy-dest are in the same protocol family as
928 --proxy-family or each other.
929 The --proxy option is mutually exclusive with all other --proxy-*
931 options except --proxy-version.
932 When --proxy is not used, all of --proxy-family, --proxy-source,
934 --proxy-source-port, --proxy-dest, and --proxy-dest-port are required.
935 Additionally, when --proxy-version is 2, --proxy-protocol and
936 --proxy-command are optional.
937 --proxy-version [ 1 | 2 ]
939 Whether to use version 1 (human readable) or version 2 (binary) of
940 the Proxy protocol. Version 1 is the default. Version 2 is only
941 implemented through the "address block", and is roughly on par with
942 the information provided in version 1.
943 --proxy [VALUE]
945 If this option is used, its argument is passed unchanged after the
946 "PROXY " portion (or the 12-byte protocol header for version 2) of
947 the Proxy exchange. This option allows sending incomplete or
948 malformed Proxy strings to a target server for testing. No attempt
949 to translate or modify this string is made, so if used with
950 "--proxy-version 2" the argument should be in the appropriate
951 binary format. This option is mutually exclusive with all other
952 --proxy-* options which provide granular proxy information.
953 --proxy-family [VALUE]
955 For version 1, specifies both the address family and transport
956 protocol. The protocol defines TCP4 and TCP6.
957 For version 2, specifies only the address family. The protocol
959 defines AF_UNSPEC, AF_INET, AF_INET6, and AF_UNIX.
960 --proxy-protocol [VALUE]
962 For version 2, specifies the transport protocol. The protocol
963 defines UNSPEC, STREAM, and DGRAM. The default is STREAM. This
964 option is unused in version 1
965 --proxy-command [VALUE]
967 For version 2, specifies the transport protocol. The protocol
968 defines LOCAL and PROXY. The default is PROXY. This option is
969 unused in version 1
970 --proxy-source [VALUE]
972 Specify the source address of the proxied connection.
973 --proxy-source-port [VALUE]
975 Specify the source port of the proxied connection.
976 --proxy-dest [VALUE]
978 Specify the destination address of the proxied connection.
979 --proxy-dest-port [VALUE]
981 Specify the destination port of the proxied connection.
982
984 These options pertain to the contents for the DATA portion of the SMTP
985 transaction. By default a very simple message is sent. If the
986 --attach or --attach-body options are used, Swaks attempts to upgrade
987 to a MIME message.
988 -d, --data [data-portion]
990 Use argument as the entire contents of DATA.
991 If no argument is provided, user will be prompted to supply value.
993 If the argument '-' is provided the data will be read from STDIN
995 with no prompt (same as -g).
996 If the argument does not contain any literal (0x0a) or
998 representative (0x5c, 0x6e or %NEWLINE%) newline characters, it
999 will be treated as a filename. If the file is open-able, the
1000 contents of the file will be used as the data portion. If the file
1001 cannot be opened, Swaks will error and exit.
1002 Any other argument will be used as the DATA contents.
1004 The value can be on one single line, with \n (ASCII 0x5c, 0x6e)
1006 representing where line breaks should be placed. Leading dots will
1007 be quoted. Closing dot is not required but is allowed. The
1008 default value for this option is "Date: %DATE%\nTo:
1009 %TO_ADDRESS%\nFrom: %FROM_ADDRESS%\nSubject: test
1010 %DATE%\nMessage-Id: <%MESSAGEID%>\nX-Mailer: swaks v%SWAKS_VERSION%
1011 jetmore.org/john/code/swaks/\n%NEW_HEADERS%\n%BODY%\n".
1012 Very basic token parsing is performed on the DATA portion. The
1014 following table shows the recognized tokens and their replacement
1015 values:
1016 %FROM_ADDRESS%
1018 Replaced with the envelope-sender.
1019 %TO_ADDRESS%
1021 Replaced with the envelope-recipient(s).
1022 %DATE%
1024 Replaced with the current time in a format suitable for
1025 inclusion in the Date: header. Note this attempts to use the
1026 standard module Time::Local for timezone calculations. If this
1027 module is unavailable the date string will be in GMT.
1028 %MESSAGEID%
1030 Replaced with a message ID string suitable for use in a
1031 Message-Id header. The value for this token will remain
1032 consistent for the life of the process.
1033 %SWAKS_VERSION%
1035 Replaced with the version of the currently-running Swaks
1036 process.
1037 %NEW_HEADERS%
1039 Replaced with the contents of the --add-header option. If
1040 --add-header is not specified this token is simply removed.
1041 %BODY%
1043 Replaced with the value specified by the --body option. See
1044 --body for default.
1045 %NEWLINE%
1047 Replaced with carriage return, newline (0x0d, 0x0a). This is
1048 identical to using '\n' (0x5c, 0x6e), but doesn't have the
1049 escaping concerns that the backslash can cause on the newline.
1050 -dab, --dump-as-body [section[,section]]
1052 If --dump-as-body is used and no other option is used to change the
1053 default body of the message, the body is replaced with output
1054 similar to the output of what is provided by --dump. --dump's
1055 initial program capability stanza is not displayed, and the "data"
1056 section is not included. Additionally, --dump always includes
1057 passwords. By default --dump-as-body does not include passwords,
1058 though this can be changed with --dump-as-body-shows-password.
1059 --dump-as-body takes the same arguments as --dump except the
1060 SUPPORT and DATA arguments are not supported.
1061 -dabsp, --dump-as-body-shows-password
1063 Cause --dump-as-body to include plaintext passwords. This option
1064 is not recommended. This option implies --dump-as-body.
1065 --body [body-specification]
1067 Specify the body of the email. The default is "This is a test
1068 mailing". If no argument to --body is given, prompt to supply one
1069 interactively. If '-' is supplied, the body will be read from
1070 standard input. If any other text is provided and the text
1071 represents an open-able file, the content of that file is used as
1072 the body. If it does not represent an open-able file, the text
1073 itself is used as the body.
1074 If the message is forced to MIME format (see --attach) "--body
1076 'body text'" is the same as "--attach-type text/plain --attach-body
1077 'body text'". See --attach-body for details on creating a
1078 multipart/alternative body.
1079 --attach [attachment-specification]
1081 When one or more --attach option is supplied, the message is
1082 changed into a multipart/mixed MIME message. The arguments to
1083 --attach are processed the same as --body with respect to STDIN,
1084 file contents, etc. --attach can be supplied multiple times to
1085 create multiple attachments. By default, each attachment is
1086 attached as an application/octet-stream file. See --attach-type
1087 for changing this behavior.
1088 If the contents of the attachment are provided via a file name, the
1090 MIME encoding will include that file name. See --attach-name for
1091 more detail on file naming.
1092 It is legal for '-' (STDIN) to be specified as an argument multiple
1094 times (once for --body and multiple times for --attach). In this
1095 case, the same content will be attached each time it is specified.
1096 This is useful for attaching the same content with multiple MIME
1097 types.
1098 --attach-body [body-specification]
1100 This is a variation on --attach that is specifically for the body
1101 part of the email. It behaves identically to --attach in that it
1102 takes the same arguments and forces the creation of a MIME message.
1103 However, it is different in that the argument will always be the
1104 first MIME part in the message, no matter where in option
1105 processing order it is encountered. Additionally, --attach-body
1106 options stack to allow creation of multipart/alternative bodies.
1107 For example, '--attach-type text/plain --attach "plain text body"
1108 --attach-type text/html --attach "html body"' would create a
1109 multipart/alternative message body.
1110 --attach-type [mime-type]
1112 By default, content that gets MIME attached to a message with the
1113 --attach option is encoded as application/octet-stream (except for
1114 the body, which is text/plain by default). --attach-type changes
1115 the mime type for every --attach option which follows it. It can
1116 be specified multiple times. The current MIME type gets reset to
1117 application/octet-stream between processing body parts and other
1118 parts.
1119 --attach-name [name]
1121 This option sets the filename that will be included in the MIME
1122 part created for the next --attach option. If no argument is set
1123 for this option, it causes no filename information to be included
1124 for the next MIME part, even if Swaks could generate it from the
1125 local file name.
1126 -ah, --add-header [header]
1128 This option allows headers to be added to the DATA. If
1129 %NEW_HEADERS% is present in the DATA it is replaced with the
1130 argument to this option. If %NEW_HEADERS% is not present, the
1131 argument is inserted between the first two consecutive newlines in
1132 the DATA (that is, it is inserted at the end of the existing
1133 headers).
1134 The option can either be specified multiple times or a single time
1136 with multiple headers separated by a literal '\n' string. So,
1137 "--add-header 'Foo: bar' --add-header 'Baz: foo'" and "--add-header
1138 'Foo: bar\nBaz: foo'" end up adding the same two headers.
1139 --header [header-and-data], --h-Header [data]
1141 These options allow a way to change headers that already exist in
1142 the DATA. '--header "Subject: foo"' and '--h-Subject foo' are
1143 equivalent. If the header does not already exist in the data then
1144 this argument behaves identically to --add-header. However, if the
1145 header already exists it is replaced with the one specified.
1146 -g If specified, Swaks will read the DATA value for the mail from
1148 STDIN. This is equivalent to "--data -". If there is a From_ line
1149 in the email, it will be removed (but see -nsf option). Useful for
1150 delivering real message (stored in files) instead of using example
1151 messages.
1152 --no-data-fixup, -ndf
1154 This option forces Swaks to do no massaging of the DATA portion of
1155 the email. This includes token replacement, From_ stripping,
1156 trailing-dot addition, --body/attachment inclusion, and any header
1157 additions. This option is only useful when used with --data, since
1158 the internal default DATA portion uses tokens.
1159 --no-strip-from, -nsf
1161 Don't strip the From_ line from the DATA portion, if present.
1162
1164 Swaks provides a transcript of its transactions to its caller
1165 (STDOUT/STDERR) by default. This transcript aims to be as faithful a
1166 representation as possible of the transaction though it does modify
1167 this output by adding informational prefixes to lines and by providing
1168 plaintext versions of TLS transactions
1169 The "informational prefixes" are referred to as transaction hints.
1171 These hints are initially composed of those marking lines that are
1172 output of Swaks itself, either informational or error messages, and
1173 those that indicate a line of data actually sent or received in a
1174 transaction. This table indicates the hints and their meanings:
1175 "==="
1177 Indicates an informational line generated by Swaks
1178 "***"
1180 Indicates an error generated within Swaks
1181 " ->"
1183 Indicates an expected line sent by Swaks to target server
1184 " ~>"
1186 Indicates a TLS-encrypted, expected line sent by Swaks to target
1187 server
1188 "**>"
1190 Indicates an unexpected line sent by Swaks to the target server
1191 "*~>"
1193 Indicates a TLS-encrypted, unexpected line sent by Swaks to target
1194 server
1195 " >"
1197 Indicates a raw chunk of text sent by Swaks to a target server (see
1198 --show-raw-text). There is no concept of "expected" or
1199 "unexpected" at this level.
1200 "<- "
1202 Indicates an expected line sent by target server to Swaks
1203 "<~ "
1205 Indicates a TLS-encrypted, expected line sent by target server to
1206 Swaks
1207 "<**"
1209 Indicates an unexpected line sent by target server to Swaks
1210 "<~*"
1212 Indicates a TLS-encrypted, unexpected line sent by target server to
1213 Swaks
1214 "< "
1216 Indicates a raw chunk of text received by Swaks from a target
1217 server (see --show-raw-text). There is no concept of "expected" or
1218 "unexpected" at this level.
1219 The following options control what and how output is displayed to the
1221 caller.
1222 -n, --suppress-data
1224 Summarizes the DATA portion of the SMTP transaction instead of
1225 printing every line. This option is very helpful, bordering on
1226 required, when using Swaks to send certain test emails. Emails
1227 with attachments, for instance, will quickly overwhelm a terminal
1228 if the DATA is not suppressed.
1229 -stl, --show-time-lapse [i]
1231 Display time lapse between send/receive pairs. This option is most
1232 useful when Time::HiRes is available, in which case the time lapse
1233 will be displayed in thousandths of a second. If Time::HiRes is
1234 unavailable or "i" is given as an argument the lapse will be
1235 displayed in integer seconds only.
1236 -nih, --no-info-hints
1238 Don't display the transaction hint for informational transactions.
1239 This is most useful when needing to copy some portion of the
1240 informational lines, for instance the certificate output from
1241 --tls-get-peer-cert.
1242 -nsh, --no-send-hints
1244 -nrh, --no-receive-hints
1245 -nth, --no-hints
1246 --no-send-hints and --no-receive-hints suppress the transaction
1247 prefix from send and receive lines, respectively. This is often
1248 useful when copying some portion of the transaction for use
1249 elsewhere (for instance, "--no-send-hints --hide-receive
1250 --hide-informational" is a useful way to get only the client-side
1251 commands for a given transaction). --no-hints is identical to
1252 specifying both --no-send-hints and --no-receive-hints.
1253 Don't show transaction hints (useful in conjunction with -hr to
1255 create copy/paste-able transactions).
1256 -raw, --show-raw-text
1258 This option will print a hex dump of raw data sent and received by
1259 Swaks. Each hex dump is the contents of a single read or write on
1260 the network. This should be identical to what is already being
1261 displayed (with the exception of the \r characters being removed).
1262 This option is useful in seeing details when servers are sending
1263 lots of data in single packets, or breaking up individual lines
1264 into multiple packets. If you really need to go in depth in that
1265 area you're probably better with a packet sniffer, but this option
1266 is a good first step to seeing odd connection issues.
1267 --output, --output-file </path/to/file>
1269 --output-file-stdout </path/to/file>
1270 --output-file-stderr </path/to/file>
1271 These options allow the user to send output to files instead of
1272 STDOUT/STDERR. The first option sends both to the same file. The
1273 arguments of &STDOUT and &STDERR are treated specially, referring
1274 to the "normal" file handles, so "--output-file-stderr '&STDOUT'"
1275 would redirect STDERR to STDOUT. These options are honored for all
1276 output except --help and --version.
1277 -pp, --protect-prompt
1279 Don't echo user input on prompts that are potentially sensitive
1280 (right now only authentication password). See also
1281 --auth-hide-password
1282 -hr, --hide-receive
1284 Don't display lines sent from the remote server being received by
1285 Swaks
1286 -hs, --hide-send
1288 Don't display lines being sent by Swaks to the remote server
1289 -hi, --hide-informational
1291 Don't display non-error informational lines from Swaks itself.
1292 -ha, --hide-all
1294 Do not display any content to the terminal.
1295 -S, --silent [level]
1297 Cause Swaks to be silent. If no argument is given or if an
1298 argument of "1" is given, print no output unless/until an error
1299 occurs, after which all output is shown. If an argument of "2" is
1300 given, only print errors. If "3" is given, show no output ever.
1301 --silent affects most output but not all. For instance, --help,
1302 --version, --dump, and --dump-mail are not affected.
1303 --support
1305 Print capabilities and exit. Certain features require non-standard
1306 Perl modules. This option evaluates whether these modules are
1307 present and displays which functionality is available and which
1308 isn't, and which modules would need to be added to gain the missing
1309 functionality.
1310 --dump-mail
1312 Cause Swaks to process all options to generate the message it would
1313 send, then print that message to STDOUT instead of sending it.
1314 This output is identical to the "data" section of --dump, except
1315 without the trailing dot.
1316 --dump [section[,section]]
1318 This option causes Swaks to print the results of option processing,
1319 immediately before mail would have been sent. No mail will be sent
1320 when --dump is used. Note that --dump is a pure self-diagnosis
1321 tool and no effort is made or will ever be made to mask passwords
1322 in the --dump output. If a section is provided as an argument to
1323 this option, only the requested section will be shown. Currently
1324 supported arguments are SUPPORT, APP, OUTPUT, TRANSPORT, PROTOCOL,
1325 XCLIENT, PROXY, TLS, AUTH, DATA, and ALL. If no argument is
1326 provided, all sections are displayed
1327 --help
1329 Display this help information and exit.
1330 --version
1332 Display version information and exit.
1333
1335 OPERATING SYSTEMS
1336 This program was primarily intended for use on UNIX-like operating
1337 systems, and it should work on any reasonable version thereof. It
1338 has been developed and tested on Solaris, Linux, and Mac OS X and
1339 is feature complete on all of these.
1340 This program is known to demonstrate basic functionality on Windows
1342 using ActiveState's Perl. It has not been fully tested. Known to
1343 work are basic SMTP functionality and the LOGIN, PLAIN, and
1344 CRAM-MD5 auth types. Unknown is any TLS functionality and the
1345 NTLM/SPA and DIGEST-MD5 auth types.
1346 Because this program should work anywhere Perl works, I would
1348 appreciate knowing about any new operating systems you've
1349 thoroughly used Swaks on as well as any problems encountered on a
1350 new OS.
1351 MAIL SERVERS
1353 This program was almost exclusively developed against Exim mail
1354 servers. It has been used casually by the author, though not
1355 thoroughly tested, with Sendmail, Smail, Exchange, Oracle
1356 Collaboration Suite, qpsmtpd, and Communigate. Because all
1357 functionality in Swaks is based on known standards it should work
1358 with any fairly modern mail server. If a problem is found, please
1359 alert the author at the address below.
1360
1362 LOGNAME
1363 If Swaks must create a sender address, $LOGNAME is used as the
1364 message local-part if it is set, and unless --force-getpwuid is
1365 used.
1366 SWAKS_HOME
1368 Used when searching for a .swaksrc configuration file. See OPTION
1369 PROCESSING -> CONFIGURATION FILES above.
1370 SWAKS_OPT_*
1372 Environment variable prefix used to specify Swaks options from
1373 environment variables. See OPTION PROCESSING -> ENVIRONMENT
1374 VARIABLES above.
1375
1377 0 no errors occurred
1378 1 error parsing command line options
1380 2 error connecting to remote server
1382 3 unknown connection type
1384 4 while running with connection type of "pipe", fatal problem writing
1386 to or reading from the child process
1387 5 while running with connection type of "pipe", child process died
1389 unexpectedly. This can mean that the program specified with --pipe
1390 doesn't exist.
1391 6 Connection closed unexpectedly. If the close is detected in
1393 response to the 'QUIT' Swaks sends following an unexpected
1394 response, the error code for that unexpected response is used
1395 instead. For instance, if a mail server returns a 550 response to
1396 a MAIL FROM: and then immediately closes the connection, Swaks
1397 detects that the connection is closed, but uses the more specific
1398 exit code 23 to detail the nature of the failure. If instead the
1399 server return a 250 code and then immediately closes the
1400 connection, Swaks will use the exit code 6 because there is not a
1401 more specific exit code.
1402 10 error in prerequisites (needed module not available)
1404 21 error reading initial banner from server
1406 22 error in HELO transaction
1408 23 error in MAIL transaction
1410 24 no RCPTs accepted
1412 25 server returned error to DATA request
1414 26 server did not accept mail following data
1416 27 server returned error after normal-session quit request
1418 28 error in AUTH transaction
1420 29 error in TLS transaction
1422 30 PRDR requested/required but not advertised
1424 32 error in EHLO following TLS negotiation
1426 33 error in XCLIENT transaction
1428 34 error in EHLO following XCLIENT
1430 35 error in PROXY option processing
1432 36 error sending PROXY banner
1434
1436 The name "Swaks" is a (sort-of) acronym for "SWiss Army Knife SMTP".
1437 It was chosen to be fairly distinct and pronounceable. While "Swaks"
1438 is unique as the name of a software package, it has some other, non-
1439 software meanings. Please send in other uses of "swak" or "swaks" for
1440 inclusion.
1441 "Sealed With A Kiss"
1443 SWAK/SWAKs turns up occasionally on the internet with the meaning
1444 "with love".
1445 bad / poor / ill (Afrikaans)
1447 Seen in the headline "SA se bes en swaks gekledes in 2011", which
1448 was translated as "best and worst dressed" by native speakers.
1449 Google Translate doesn't like "swaks gekledes", but it will
1450 translate "swak" as "poor" and "swak geklede" as "ill-dressed".
1451
1453 This program is free software; you can redistribute it and/or modify it
1454 under the terms of the GNU General Public License as published by the
1455 Free Software Foundation; either version 2 of the License, or (at your
1456 option) any later version.
1457 This program is distributed in the hope that it will be useful, but
1459 WITHOUT ANY WARRANTY; without even the implied warranty of
1460 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1461 General Public License for more details.
1462 You should have received a copy of the GNU General Public License along
1464 with this program; if not, write to the Free Software Foundation, Inc.,
1465 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
1466
1468 General contact, questions, patches, requests, etc to
1469 proj-swaks@jetmore.net.
1470 Change logs, this help, and the latest version are found at
1472 http://www.jetmore.org/john/code/swaks/.
1473 Swaks is crafted with love by John Jetmore from the cornfields of
1475 Indiana, United States of America.
1476
1478 Email
1479 updates-swaks@jetmore.net
1480 If you would like to be put on a list to receive notifications when
1482 a new version of Swaks is released, please send an email to this
1483 address. There will not be a response to your email.
1484 Website
1486 http://www.jetmore.org/john/blog/c/swaks/
1487 RSS Feed
1489 http://www.jetmore.org/john/blog/c/swaks/feed/
1490 Twitter
1492 http://twitter.com/SwaksSMTP
1493perl v5.34.0 2022-01-22 SWAKS(1)