"Fossies" - the Fresh Open Source Software Archive

Member "swaks-20201014.0/doc/ref.txt" (14 Oct 2020, 79523 Bytes) of package /linux/privat/swaks-20201014.0.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "ref.txt": 20201010.0_vs_20201014.0.

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