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