"Fossies" - the Fresh Open Source Software Archive

Member "swaks-20181104.0/doc/ref.txt" (4 Nov 2018, 65243 Bytes) of package /linux/privat/swaks-20181104.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": 20170101.0_vs_20181104.0.

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