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

NAME

6       Swaks - Swiss Army Knife SMTP, the all-purpose SMTP transaction tester
7

DESCRIPTION

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

QUICK START

20       Deliver a standard test email to user@example.com on port 25 of
21       test-server.example.net:
22
23        swaks --to user@example.com --server test-server.example.net
24
25       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
29        swaks --to user@example.com --from me@example.com --auth CRAM-MD5 --auth-user me@example.com --header-X-Test "test email"
30
31       Test a virus scanner using EICAR in an attachment.  Don't show the
32       message DATA part.:
33
34        swaks -t user@example.com --attach - --server test-server.example.com --suppress-data </path/to/eicar.txt
35
36       Test a spam scanner using GTUBE in the body of an email, routed via the
37       MX records for example.com:
38
39        swaks --to user@example.com --body /path/to/gtube/file
40
41       Deliver a standard test email to user@example.com using the LMTP
42       protocol via a UNIX domain socket file
43
44        swaks --to user@example.com --socket /var/lda.sock --protocol LMTP
45
46       Report all the recipients in a text file that are non-verifiable on a
47       test server:
48
49        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

TERMS AND CONVENTIONS

56       This document tries to be consistent and specific in its use of the
57       following terms to reduce confusion.
58
59       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
64       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
70       Transport
71           The transport is the underlying method used to connect to the
72           target.
73
74       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
80       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
84       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
90       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
96       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
103       Body
104           A message's body is the portion of its DATA section following the
105           first blank line.
106

OPTION PROCESSING

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
115       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
120       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
130       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
138       The exact mechanism and format for using each of the types is listed
139       below.
140
141       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
148           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
156           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
163           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
172           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
180               # 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
187           Options specific to configuration file:
188
189           --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
200       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
210               $ SWAKS_OPT_from='fred@example.com'
211               $ SWAKS_OPT_h_From='"Fred Example" <fred@example.com>'
212
213           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
218           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
232           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
236       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
245           The following demonstrates the example shown in the configuration
246           file and environment variable sections:
247
248               $ swaks --from fred@example.com --h-From: '"Fred Example" <fred@example.com>'
249

TRANSPORTS

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
262       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
269           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
274           IPv6 is supported when the IO::Socket::INET6 module is present.
275
276           -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
290           -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
297           -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
304           -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
310           --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
317           -4, -6
318               Force IPv4 or IPv6.
319
320       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
329           --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
334       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
349           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
354           --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

PROTOCOL OPTIONS

361       These options are related to the protocol layer.
362
363       -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
370           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
376       -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
390       --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
398       -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
405           CONNECT, BANNER
406               Terminate the session after receiving the greeting banner from
407               the target.
408
409           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
414           XCLIENT
415               Quit after XCLIENT is sent.
416
417           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
424           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
428           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
433           MAIL, FROM
434               Quit after MAIL FROM: is sent.
435
436           RCPT, TO
437               Quit after RCPT TO: is sent.
438
439       --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
445           DATA
446               Quit after DATA is sent.
447
448           DOT Quit after the final '.' of the message is sent.
449
450       --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
456       --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
463       --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
473           SMTP
474               HELO, "-p 25"
475
476           SSMTP
477               EHLO->HELO, "-tlsc -p 465"
478
479           SSMTPA
480               EHLO->HELO, "-a -tlsc -p 465"
481
482           SMTPS
483               HELO, "-tlsc -p 465"
484
485           ESMTP
486               EHLO->HELO, "-p 25"
487
488           ESMTPA
489               EHLO->HELO, "-a -p 25"
490
491           ESMTPS
492               EHLO->HELO, "-tls -p 25"
493
494           ESMTPSA
495               EHLO->HELO, "-a -tls -p 25"
496
497           LMTP
498               LHLO, "-p 24"
499
500           LMTPA
501               LHLO, "-a -p 24"
502
503           LMTPS
504               LHLO, "-tls -p 24"
505
506           LMTPSA
507               LHLO, "-a -tls -p 24"
508
509       --pipeline
510           If the remote server supports it, attempt SMTP PIPELINING (RFC
511           2920).
512
513       --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
519       --force-getpwuid
520           Tell Swaks to use the getpwuid method of finding the default sender
521           local-part instead of trying $LOGNAME first.
522

TLS / ENCRYPTION

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
534       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
540       -tls
541           Require connection to use STARTTLS.  Exit if TLS not available for
542           any reason (not advertised, negotiations failed, etc).
543
544       -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
557       -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
564       --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
570       -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
579           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
586       -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
594       --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
601       --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
606       --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
613       --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
620       --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

AUTHENTICATION

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
636       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
643       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
655       Following are the supported authentication types including any
656       individual notes and requirements.
657
658       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
663       -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
672           The following tables lists the valid auth-types
673
674           LOGIN, PLAIN
675               These basic authentication types are fully supported and tested
676               and have no additional requirements
677
678           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
683           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
690               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
695               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
699               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
708           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
714           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
721               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
727       -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
733       -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
741       -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
746       -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
751       -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
757           The following table lists the currently recognized keywords and the
758           authenticators that use them
759
760           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
765           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
770           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
775           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
780       -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
789       -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
793       -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
801           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

XCLIENT OPTIONS

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
815       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
824       --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
841           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
845           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
850           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
854       --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
864       --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
873           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
882           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
889       --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
895       --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
900       --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

PROXY OPTIONS

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
923       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
930       The --proxy option is mutually exclusive with all other --proxy-*
931       options except --proxy-version.
932
933       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
938       --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
944       --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
954       --proxy-family [VALUE]
955           For version 1, specifies both the address family and transport
956           protocol.  The protocol defines TCP4 and TCP6.
957
958           For version 2, specifies only the address family.  The protocol
959           defines AF_UNSPEC, AF_INET, AF_INET6, and AF_UNIX.
960
961       --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
966       --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
971       --proxy-source [VALUE]
972           Specify the source address of the proxied connection.
973
974       --proxy-source-port [VALUE]
975           Specify the source port of the proxied connection.
976
977       --proxy-dest [VALUE]
978           Specify the destination address of the proxied connection.
979
980       --proxy-dest-port [VALUE]
981           Specify the destination port of the proxied connection.
982

DATA OPTIONS

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
989       -d, --data [data-portion]
990           Use argument as the entire contents of DATA.
991
992           If no argument is provided, user will be prompted to supply value.
993
994           If the argument '-' is provided the data will be read from STDIN
995           with no prompt (same as -g).
996
997           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
1003           Any other argument will be used as the DATA contents.
1004
1005           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
1013           Very basic token parsing is performed on the DATA portion.  The
1014           following table shows the recognized tokens and their replacement
1015           values:
1016
1017           %FROM_ADDRESS%
1018               Replaced with the envelope-sender.
1019
1020           %TO_ADDRESS%
1021               Replaced with the envelope-recipient(s).
1022
1023           %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
1029           %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
1034           %SWAKS_VERSION%
1035               Replaced with the version of the currently-running Swaks
1036               process.
1037
1038           %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
1042           %BODY%
1043               Replaced with the value specified by the --body option.  See
1044               --body for default.
1045
1046           %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
1051       -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
1062       -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
1066       --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
1075           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
1080       --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
1089           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
1093           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
1099       --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
1111       --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
1120       --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
1127       -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
1135           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
1140       --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
1147       -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
1153       --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
1160       --no-strip-from, -nsf
1161           Don't strip the From_ line from the DATA portion, if present.
1162

OUTPUT OPTIONS

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
1170       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
1176       "==="
1177           Indicates an informational line generated by Swaks
1178
1179       "***"
1180           Indicates an error generated within Swaks
1181
1182       " ->"
1183           Indicates an expected line sent by Swaks to target server
1184
1185       " ~>"
1186           Indicates a TLS-encrypted, expected line sent by Swaks to target
1187           server
1188
1189       "**>"
1190           Indicates an unexpected line sent by Swaks to the target server
1191
1192       "*~>"
1193           Indicates a TLS-encrypted, unexpected line sent by Swaks to target
1194           server
1195
1196       "  >"
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
1201       "<- "
1202           Indicates an expected line sent by target server to Swaks
1203
1204       "<~ "
1205           Indicates a TLS-encrypted, expected line sent by target server to
1206           Swaks
1207
1208       "<**"
1209           Indicates an unexpected line sent by target server to Swaks
1210
1211       "<~*"
1212           Indicates a TLS-encrypted, unexpected line sent by target server to
1213           Swaks
1214
1215       "<  "
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
1220       The following options control what and how output is displayed to the
1221       caller.
1222
1223       -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
1230       -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
1237       -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
1243       -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
1254           Don't show transaction hints (useful in conjunction with -hr to
1255           create copy/paste-able transactions).
1256
1257       -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
1268       --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
1278       -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
1283       -hr, --hide-receive
1284           Don't display lines sent from the remote server being received by
1285           Swaks
1286
1287       -hs, --hide-send
1288           Don't display lines being sent by Swaks to the remote server
1289
1290       -hi, --hide-informational
1291           Don't display non-error informational lines from Swaks itself.
1292
1293       -ha, --hide-all
1294           Do not display any content to the terminal.
1295
1296       -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
1304       --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
1311       --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
1317       --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
1328       --help
1329           Display this help information and exit.
1330
1331       --version
1332           Display version information and exit.
1333

PORTABILITY

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
1341           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
1347           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
1352       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

ENVIRONMENT VARIABLES

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
1367       SWAKS_HOME
1368           Used when searching for a .swaksrc configuration file.  See OPTION
1369           PROCESSING -> CONFIGURATION FILES above.
1370
1371       SWAKS_OPT_*
1372           Environment variable prefix used to specify Swaks options from
1373           environment variables.  See OPTION PROCESSING -> ENVIRONMENT
1374           VARIABLES above.
1375

EXIT CODES

1377       0   no errors occurred
1378
1379       1   error parsing command line options
1380
1381       2   error connecting to remote server
1382
1383       3   unknown connection type
1384
1385       4   while running with connection type of "pipe", fatal problem writing
1386           to or reading from the child process
1387
1388       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
1392       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
1403       10  error in prerequisites (needed module not available)
1404
1405       21  error reading initial banner from server
1406
1407       22  error in HELO transaction
1408
1409       23  error in MAIL transaction
1410
1411       24  no RCPTs accepted
1412
1413       25  server returned error to DATA request
1414
1415       26  server did not accept mail following data
1416
1417       27  server returned error after normal-session quit request
1418
1419       28  error in AUTH transaction
1420
1421       29  error in TLS transaction
1422
1423       30  PRDR requested/required but not advertised
1424
1425       32  error in EHLO following TLS negotiation
1426
1427       33  error in XCLIENT transaction
1428
1429       34  error in EHLO following XCLIENT
1430
1431       35  error in PROXY option processing
1432
1433       36  error sending PROXY banner
1434

ABOUT THE NAME

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
1442       "Sealed With A Kiss"
1443           SWAK/SWAKs turns up occasionally on the internet with the meaning
1444           "with love".
1445
1446       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

LICENSE

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
1458       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
1463       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

CONTACT INFORMATION

1468       General contact, questions, patches, requests, etc to
1469       proj-swaks@jetmore.net.
1470
1471       Change logs, this help, and the latest version are found at
1472       http://www.jetmore.org/john/code/swaks/.
1473
1474       Swaks is crafted with love by John Jetmore from the cornfields of
1475       Indiana, United States of America.
1476

NOTIFICATIONS

1478       Email
1479           updates-swaks@jetmore.net
1480
1481           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
1485       Website
1486           http://www.jetmore.org/john/blog/c/swaks/
1487
1488       RSS Feed
1489           http://www.jetmore.org/john/blog/c/swaks/feed/
1490
1491       Twitter
1492           http://twitter.com/SwaksSMTP
1493
1494
1495
1496perl v5.34.0                      2022-01-22                          SWAKS(1)
Impressum