.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "SWAKS 1" .TH SWAKS 1 "2019-02-27" "perl v5.28.1" "SWAKS" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Swaks \- Swiss Army Knife SMTP, the all\-purpose SMTP transaction tester .SH "DESCRIPTION" .IX Header "DESCRIPTION" Swaks' primary design goal is to be a flexible, scriptable, transaction-oriented \s-1SMTP\s0 test tool. It handles \s-1SMTP\s0 features and extensions such as \s-1TLS,\s0 authentication, and pipelining; multiple version of the \s-1SMTP\s0 protocol including \s-1SMTP, ESMTP,\s0 and \s-1LMTP\s0; and multiple transport methods including UNIX-domain sockets, internet-domain sockets, and pipes to spawned processes. Options can be specified in environment variables, configuration files, and the command line allowing maximum configurability and ease of use for operators and scripters. .SH "QUICK START" .IX Header "QUICK START" Deliver a standard test email to user@example.com on port 25 of test\-server.example.net: .Sp .Vb 1 \& swaks \-\-to user@example.com \-\-server test\-server.example.net .Ve .PP Deliver a standard test email, requiring \s-1CRAM\-MD5\s0 authentication as user me@example.com. An \*(L"X\-Test\*(R" header will be added to the email body. The authentication password will be prompted for. .Sp .Vb 1 \& swaks \-\-to user@example.com \-\-from me@example.com \-\-auth CRAM\-MD5 \-\-auth\-user me@example.com \-\-header\-X\-Test "test email" .Ve .PP Test a virus scanner using \s-1EICAR\s0 in an attachment. Don't show the message \s-1DATA\s0 part.: .Sp .Vb 1 \& swaks \-t user@example.com \-\-attach \- \-\-server test\-server.example.com \-\-suppress\-data .Ve .IP "\s-1ENVIRONMENT VARIABLES\s0" 4 .IX Item "ENVIRONMENT VARIABLES" Options can be supplied via environment variables. The variables are in the form \f(CW$SWAKS_OPT_name\fR, where name is the name of the option that would be specified on the command line. Because dashes aren't allowed in environment variable names in most UNIX-ish shells, no leading dashes should be used and any dashes inside the option's name should be replaced with underscores. The following would create the same options shown in the configuration file example: .Sp .Vb 2 \& $ SWAKS_OPT_from=\*(Aqfred@example.com\*(Aq \& $ SWAKS_OPT_h_From=\*(Aq"Fred Example" \*(Aq .Ve .Sp Setting a variable to an empty value is the same as specifying it on the command line with no argument. For instance, setting SWAKS_OPT_server="" would cause Swaks to prompt the use for the server to which to connect at each invocation. .Sp In addition to setting the equivalent of command line options, \s-1SWAKS_HOME\s0 can be set to a directory containing the default .swaksrc to be used. .IP "\s-1COMMAND LINE OPTIONS\s0" 4 .IX Item "COMMAND LINE OPTIONS" The final method of supplying options to Swaks is via the command line. The options behave in a manner consistent with most UNIX-ish command line programs. Many options have both a short and long form (for instance \-s and \-\-server). By convention short options are specified with a single dash and long options are specified with a double-dash. This is only a convention and either prefix will work with either type. .Sp The following demonstrates the example shown in the configuration file and environment variable sections: .Sp .Vb 1 \& $ swaks \-\-from fred@example.com \-\-h\-From: \*(Aq"Fred Example" \*(Aq .Ve .SH "TRANSPORTS" .IX Header "TRANSPORTS" Swaks can connect to a target via \s-1UNIX\s0 pipes (\*(L"pipes\*(R"), \s-1UNIX\s0 domain sockets (\*(L"\s-1UNIX\s0 sockets\*(R"), or internet domain sockets (\*(L"network sockets\*(R"). Connecting via network sockets is the default behavior. Because of the singular nature of the transport used, each set of options in the following section is mutually exclusive. Specifying more than one of \-\-server, \-\-pipe, or \-\-socket will result in an error. Mixing other options between transport types will only result in the irrelevant options being ignored. Below is a brief description of each type of transport and the options that are specific to that transport type. .IP "\s-1NETWORK SOCKETS\s0" 4 .IX Item "NETWORK SOCKETS" This transport attempts to deliver a message via \s-1TCP/IP,\s0 the standard method for delivering \s-1SMTP.\s0 This is the default transport for Swaks. If none of \-\-server, \-\-pipe, or \-\-socket are given then this transport is used and the target server is determined from the recipient's domain (see \-\-server below for more details). .Sp This transport requires the IO::Socket module which is part of the standard Perl distribution. If this module is not loadable, attempting to use this transport will result in an error and program termination. .Sp IPv6 is supported when the IO::Socket::INET6 module is present. .RS 4 .IP "\-s, \-\-server [target mail server[:port]]" 4 .IX Item "-s, --server [target mail server[:port]]" Explicitly tell Swaks to use network sockets and specify the hostname or \s-1IP\s0 address to which to connect, or prompt if no argument is given. If this option is not given and no other transport option is given, the target mail server is determined from the appropriate \s-1DNS\s0 records for the domain of the recipient email address using the Net::DNS module. If Net::DNS is not available Swaks will attempt to connect to localhost to deliver. The target port can optionally be set here. Supported formats for this include \s-1SERVER:PORT\s0 (supporting names and IPv4 addresses); [\s-1SERVER\s0]:PORT and \s-1SERVER/PORT\s0 (supporting names, IPv4 and IPv6 addresses). See also \-\-copy\-routing. .IP "\-p, \-\-port [port]" 4 .IX Item "-p, --port [port]" Specify which \s-1TCP\s0 port on the target is to be used, or prompt if no argument is listed. The argument can be a service name (as retrieved by \fBgetservbyname\fR\|(3)) or a port number. The default port is determined by the \-\-protocol option. See \-\-protocol for more details. .IP "\-li, \-\-local\-interface [\s-1IP\s0 or hostname[:port]]" 4 .IX Item "-li, --local-interface [IP or hostname[:port]]" Use argument as the local interface for the outgoing \s-1SMTP\s0 connection, or prompt user if no argument given. Argument can be an \s-1IP\s0 address or a hostname. Default action is to let the operating system choose the local interface. See \-\-server for additional comments on :port format. .IP "\-lp, \-\-local\-port, \-\-lport [port]" 4 .IX Item "-lp, --local-port, --lport [port]" Specify the outgoing port to originate the transaction from. If this option is not specified the system will pick an ephemeral port. Note that regular users cannot specify some ports. .IP "\-\-copy\-routing [domain]" 4 .IX Item "--copy-routing [domain]" The argument is interpreted as the domain part of an email address and it is used to find the target server using the same logic that would be used to look up the target server for a recipient email address. See \-\-to option for more details on how the target is determined from the email domain. .IP "\-4, \-6" 4 .IX Item "-4, -6" Force IPv4 or IPv6. .RE .RS 4 .RE .IP "\s-1UNIX SOCKETS\s0" 4 .IX Item "UNIX SOCKETS" This transport method attempts to deliver messages via a UNIX-domain socket file. This is useful for testing MTA/MDAs that listen on socket files (for instance, testing \s-1LMTP\s0 delivery to Cyrus). This transport requires the IO::Socket module which is part of the standard Perl distribution. If this module is not loadable, attempting to use this transport will result in an error and program termination. .RS 4 .IP "\-\-socket [/path/to/socket/file]" 4 .IX Item "--socket [/path/to/socket/file]" This option takes as its argument a UNIX-domain socket file. If Swaks is unable to open this socket it will display an error and exit. .RE .RS 4 .RE .IP "\s-1PIPES\s0" 4 .IX Item "PIPES" This transport attempts to spawn a process and communicate with it via pipes. The spawned program must be prepared to behave as a mail server over \s-1STDIN/STDOUT.\s0 Any \s-1MTA\s0 designed to operate from inet/xinet should support this. In addition, some MTAs provide testing modes that can be communicated with via \s-1STDIN/STDOUT.\s0 This transport can be used to automate that testing. For example, if you implemented \s-1DNSBL\s0 checking with Exim and you wanted to make sure it was working, you could run 'swaks \-\-pipe \*(L"exim \-bh 127.0.0.2\*(R"'. Ideally, the process you are talking to should behave exactly like an \s-1SMTP\s0 server on \s-1STDIN\s0 and \s-1STDOUT.\s0 Any debugging should be sent to \s-1STDERR,\s0 which will be directed to your terminal. In practice, Swaks can generally handle some debug on the child's \s-1STDOUT,\s0 but there are no guarantees on how much it can handle. .Sp This transport requires the IPC::Open2 module which is part of the standard Perl distribution. If this module is not loadable, attempting to use this transport will result in an error and program termination. .RS 4 .IP "\-\-pipe [/path/to/command and arguments]" 4 .IX Item "--pipe [/path/to/command and arguments]" Provide a process name and arguments to the process. Swaks will attempt to spawn the process and communicate with it via pipes. If the argument is not an executable Swaks will display an error and exit. .RE .RS 4 .RE .SH "PROTOCOL OPTIONS" .IX Header "PROTOCOL OPTIONS" These options are related to the protocol layer. .IP "\-t, \-\-to [email\-address[,email\-address,...]]" 4 .IX Item "-t, --to [email-address[,email-address,...]]" Tells Swaks to use argument(s) as the envelope-recipient for the email, or prompt for recipient if no argument provided. If multiple recipients are provided and the recipient domain is needed to determine routing the domain of the last recipient provided is used. .Sp There is no default value for this option. If no recipients are provided via any means, user will be prompted to provide one interactively. The only exception to this is if a \-\-quit\-after value is provided which will cause the \s-1SMTP\s0 transaction to be terminated before the recipient is needed. .IP "\-f, \-\-from [email\-address]" 4 .IX Item "-f, --from [email-address]" Use argument as envelope-sender for email, or prompt user if no argument specified. The string <> can be supplied to mean the null sender. If user does not specify a sender address a default value is used. The domain-part of the default sender is a best guess at the fully-qualified domain name of the local host. The method of determining the local-part varies. On Windows, \fBWin32::LoginName()\fR is used. On UNIX-ish platforms, the \f(CW$LOGNAME\fR environment variable is used if it is set. Otherwise \fBgetpwuid\fR\|(3) is used. See also \-\-force\-getpwuid. .IP "\-\-ehlo, \-\-lhlo, \-h, \-\-helo [helo\-string]" 4 .IX Item "--ehlo, --lhlo, -h, --helo [helo-string]" String to use as argument to \s-1HELO/EHLO/LHLO\s0 command, or prompt use if no argument is specified. If this option is not used a best guess at the fully-qualified domain name of the local host is used. If the Sys::Hostname module, which is part of the base distribution, is not available the user will be prompted for a \s-1HELO\s0 value. Note that Sys::Hostname has been observed to not be able to find the local hostname in certain circumstances. This has the same effect as if Sys::Hostname were unavailable. .IP "\-q, \-\-quit, \-\-quit\-after [stop\-point]" 4 .IX Item "-q, --quit, --quit-after [stop-point]" Point at which the transaction should be stopped. When the requested stopping point is reached in the transaction, and provided that Swaks has not errored out prior to reaching it, Swaks will send \*(L"\s-1QUIT\*(R"\s0 and attempt to close the connection cleanly. These are the valid arguments and notes about their meaning. .RS 4 .IP "\s-1CONNECT, BANNER\s0" 4 .IX Item "CONNECT, BANNER" Terminate the session after receiving the greeting banner from the target. .IP "FIRST-HELO, FIRST-EHLO, FIRST-LHLO" 4 .IX Item "FIRST-HELO, FIRST-EHLO, FIRST-LHLO" In a \s-1STARTTLS\s0 (but not tls-on-connect) session, terminate the transaction after the first of two HELOs. In a non-STARTTLS transaction, behaves the same as \s-1HELO\s0 (see below). .IP "\s-1XCLIENT\s0" 4 .IX Item "XCLIENT" Quit after \s-1XCLIENT\s0 is sent .IP "\s-1TLS\s0" 4 .IX Item "TLS" Quit the transaction immediately following \s-1TLS\s0 negotiation. Note that this happens in different places depending on whether \s-1STARTTLS\s0 or tls-on-connect are used. This always quits after the point where \s-1TLS\s0 would have been negotiated, regardless of whether it was attempted. .IP "\s-1HELO, EHLO, LHLO\s0" 4 .IX Item "HELO, EHLO, LHLO" In a \s-1STARTTLS\s0 or \s-1XCLIENT\s0 session, quit after the second \s-1HELO.\s0 Otherwise quit after the first and only \s-1HELO.\s0 .IP "\s-1AUTH\s0" 4 .IX Item "AUTH" Quit after authentication. This always quits after the point where authentication would have been negotiated, regardless of whether it was attempted. .IP "\s-1MAIL, FROM\s0" 4 .IX Item "MAIL, FROM" Quit after \s-1MAIL FROM:\s0 is sent. .IP "\s-1RCPT, TO\s0" 4 .IX Item "RCPT, TO" Quit after \s-1RCPT TO:\s0 is sent. .RE .RS 4 .RE .IP "\-\-da, \-\-drop\-after [stop\-point]" 4 .IX Item "--da, --drop-after [stop-point]" The option is similar to \-\-quit\-after, but instead of trying to cleanly shut down the session it simply terminates the session. This option accepts the same stop-points as \-\-quit\-after. .IP "\-\-das, \-\-drop\-after\-send [stop\-point]" 4 .IX Item "--das, --drop-after-send [stop-point]" This option is similar to \-\-drop\-after, but instead of dropping the connection after reading a response to the stop-point, it drops the connection immediately after sending stop-point. .IP "\-\-timeout [time]" 4 .IX Item "--timeout [time]" Use argument as the \s-1SMTP\s0 transaction timeout, or prompt user if no argument given. Argument can either be a pure digit, which will be interpreted as seconds, or can have a specifier s or m (5s = 5 seconds, 3m = 180 seconds). As a special case, 0 means don't timeout the transactions. Default value is 30s. .IP "\-\-protocol [protocol]" 4 .IX Item "--protocol [protocol]" Specify which protocol to use in the transaction. Valid options are shown in the table below. Currently the 'core' protocols are \s-1SMTP, ESMTP,\s0 and \s-1LMTP.\s0 By using variations of these protocol types one can tersely specify default ports, whether authentication should be attempted, and the type of \s-1TLS\s0 connection that should be attempted. The default protocol is \s-1ESMTP.\s0 This table demonstrates the available arguments to \-\-protocol and the options each sets as a side effect: .RS 4 .IP "\s-1SMTP\s0" 4 .IX Item "SMTP" \&\s-1HELO,\s0 \*(L"\-p 25\*(R" .IP "\s-1SSMTP\s0" 4 .IX Item "SSMTP" \&\s-1EHLO\-\s0>\s-1HELO,\s0 \*(L"\-tlsc \-p 465\*(R" .IP "\s-1SSMTPA\s0" 4 .IX Item "SSMTPA" \&\s-1EHLO\-\s0>\s-1HELO,\s0 \*(L"\-a \-tlsc \-p 465\*(R" .IP "\s-1SMTPS\s0" 4 .IX Item "SMTPS" \&\s-1HELO,\s0 \*(L"\-tlsc \-p 465\*(R" .IP "\s-1ESMTP\s0" 4 .IX Item "ESMTP" \&\s-1EHLO\-\s0>\s-1HELO,\s0 \*(L"\-p 25\*(R" .IP "\s-1ESMTPA\s0" 4 .IX Item "ESMTPA" \&\s-1EHLO\-\s0>\s-1HELO,\s0 \*(L"\-a \-p 25\*(R" .IP "\s-1ESMTPS\s0" 4 .IX Item "ESMTPS" \&\s-1EHLO\-\s0>\s-1HELO,\s0 \*(L"\-tls \-p 25\*(R" .IP "\s-1ESMTPSA\s0" 4 .IX Item "ESMTPSA" \&\s-1EHLO\-\s0>\s-1HELO,\s0 \*(L"\-a \-tls \-p 25\*(R" .IP "\s-1LMTP\s0" 4 .IX Item "LMTP" \&\s-1LHLO,\s0 \*(L"\-p 24\*(R" .IP "\s-1LMTPA\s0" 4 .IX Item "LMTPA" \&\s-1LHLO,\s0 \*(L"\-a \-p 24\*(R" .IP "\s-1LMTPS\s0" 4 .IX Item "LMTPS" \&\s-1LHLO,\s0 \*(L"\-tls \-p 24\*(R" .IP "\s-1LMTPSA\s0" 4 .IX Item "LMTPSA" \&\s-1LHLO,\s0 \*(L"\-a \-tls \-p 24\*(R" .RE .RS 4 .RE .IP "\-\-pipeline" 4 .IX Item "--pipeline" If the remote server supports it, attempt \s-1SMTP PIPELINING\s0 (\s-1RFC 2920\s0). .IP "\-\-prdr" 4 .IX Item "--prdr" If the server supports it, attempt Per-Recipient Data Response (\s-1PRDR\s0) (https://tools.ietf.org/html/draft\-hall\-prdr\-00.txt). \s-1PRDR\s0 is not yet standardized, but MTAs have begun implementing the proposal. .IP "\-\-force\-getpwuid" 4 .IX Item "--force-getpwuid" Tell Swaks to use the getpwuid method of finding the default sender local-part instead of trying \f(CW$LOGNAME\fR first. .SH "TLS / ENCRYPTION" .IX Header "TLS / ENCRYPTION" These are options related to encrypting the transaction. These have been tested and confirmed to work with all three transport methods. The Net::SSLeay module is used to perform encryption when it is requested. If this module is not loadable Swaks will either ignore the \s-1TLS\s0 request or error out, depending on whether the request was optional. \s-1STARTTLS\s0 is defined as an extension in the \s-1ESMTP\s0 protocol and will be unavailable if \-\-protocol is set to a variation of \s-1SMTP.\s0 Because it is not defined in the protocol itself, \-\-tls\-on\-connect is available for any protocol type if the target supports it. .PP A local certificate is not required for a \s-1TLS\s0 connection to be negotiated. However, some servers use client certificate checking to verify that the client is allowed to connect. Swaks can be told to use a specific local certificate using the \-\-tls\-cert and \-\-tls\-key options. .IP "\-tls" 4 .IX Item "-tls" Require connection to use \s-1STARTTLS.\s0 Exit if \s-1TLS\s0 not available for any reason (not advertised, negotiations failed, etc). .IP "\-tlso, \-\-tls\-optional" 4 .IX Item "-tlso, --tls-optional" Attempt to use \s-1STARTTLS\s0 if available, continue with normal transaction if \s-1TLS\s0 was unable to be negotiated for any reason. Note that this is a semi-useless option as currently implemented because after a negotiation failure the state of the connection is unknown. In some cases, like a version mismatch, the connection should be left as plaintext. In others, like a verification failure, the server-side may think that it should continue speaking \s-1TLS\s0 while the client thinks it is plaintext. There may be an attempt to add more granular state detection in the future, but for now just be aware that odd things may happen with this option if the \s-1TLS\s0 negotiation is attempted and fails. .IP "\-tlsos, \-\-tls\-optional\-strict" 4 .IX Item "-tlsos, --tls-optional-strict" Attempt to use \s-1STARTTLS\s0 if available. Proceed with transaction if \s-1TLS\s0 is negotiated successfully or \s-1STARTTLS\s0 not advertised. If \s-1STARTTLS\s0 is advertised but \s-1TLS\s0 negotiations fail, treat as an error and abort transaction. Due to the caveat noted above, this is a much saner option than \-\-tls\-optional. .IP "\-\-tlsc, \-\-tls\-on\-connect" 4 .IX Item "--tlsc, --tls-on-connect" Initiate a \s-1TLS\s0 connection immediately on connection. Following common convention, if this option is specified the default port changes from 25 to 465, though this can still be overridden with the \-\-port option. .IP "\-tlsp, \-\-tls\-protocol \s-1SPECIFICATION\s0" 4 .IX Item "-tlsp, --tls-protocol SPECIFICATION" Specify which protocols to use (or not use) when negotiating \s-1TLS.\s0 At the time of this writing, the available protocols are sslv2, sslv3, tlsv1, tlsv1_1, tlsv1_2, and tlsv1_3. The availability of these protocols is dependent on your underlying OpenSSL library, so not all of these may be available. The list of available protocols is shown in the output of \-\-dump (assuming \s-1TLS\s0 is available at all). .Sp The specification string is a comma-delimited list of protocols that can be used or not used. For instance 'tlsv1,tlsv1_1' will only succeed if one of those two protocols is available on both the client and the server. Conversely, 'no_sslv2,no_sslv3' will attempt to negotiate any protocol except sslv2 and sslv3. The two forms of specification cannot be mixed. .IP "\-tls\-cipher \s-1CIPHER_STRING\s0" 4 .IX Item "-tls-cipher CIPHER_STRING" The argument to this option is passed to the underlying OpenSSL library to set the list of acceptable ciphers to the be used for the connection. The format of this string is opaque to Swaks and is defined in http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT. A brief example would be \-\-tls\-cipher '3DES:+RSA'. .IP "\-\-tls\-verify" 4 .IX Item "--tls-verify" Tell Swaks to attempt to verify the server's certificate. If this option is set and the server's certificate is not verifiable (either using the system-default \s-1CA\s0 information, or custom \s-1CA\s0 information (see \-\-tls\-ca\-path)) \s-1TLS\s0 negotiation will not succeed. By default, Swaks does not attempt certificate verification. .IP "\-\-tls\-ca\-path [ /path/to/CAfile | /path/to/CAdir/ ]" 4 .IX Item "--tls-ca-path [ /path/to/CAfile | /path/to/CAdir/ ]" Specify an alternate location for \s-1CA\s0 information for verifying server certificates. The default behavior is to use the underlying OpenSSL library's default information. .IP "\-\-tls\-cert /path/to/file" 4 .IX Item "--tls-cert /path/to/file" Provide a path to a file containing the local certificate Swaks should use if \s-1TLS\s0 is negotiated. The file path argument is required. As currently implemented the certificate in the file must be in \s-1PEM\s0 format. Contact the author if there's a compelling need for \s-1ASN1.\s0 If this option is set, \-\-tls\-key is also required. .IP "\-\-tls\-key /path/to/file" 4 .IX Item "--tls-key /path/to/file" Provide a path to a file containing the local private key Swaks should use if \s-1TLS\s0 is negotiated. The file path argument is required. As currently implemented the certificate in the file must be in \s-1PEM\s0 format. Contact the author if there's a compelling need for \s-1ASN1.\s0 If this option is set, \-\-tls\-cert is also required. .IP "\-\-tls\-get\-peer\-cert [/path/to/file]" 4 .IX Item "--tls-get-peer-cert [/path/to/file]" Get a copy of the \s-1TLS\s0 peer's certificate. If no argument is given, it will be displayed to \s-1STDOUT.\s0 If an argument is given it is assumed to be a filesystem path specifying where the certificate should be written. The saved certificate can then be examined using standard tools such as the openssl command. If a file is specified its contents will be overwritten. .SH "AUTHENTICATION" .IX Header "AUTHENTICATION" Swaks will attempt to authenticate to the target mail server if instructed to do so. This section details available authentication types, requirements, options and their interactions, and other fine points in authentication usage. Because authentication is defined as an extension in the \s-1ESMTP\s0 protocol it will be unavailable if \-\-protocol is set to a variation of \s-1SMTP.\s0 .PP All authentication methods require base64 encoding. If the MIME::Base64 Perl module is loadable Swaks attempts to use it to perform these encodings. If MIME::Base64 is not available Swaks will use its own onboard base64 routines. These are slower than the MIME::Base64 routines and less reviewed, though they have been tested thoroughly. Using the MIME::Base64 module is encouraged. .PP If authentication is required (see options below for when it is and isn't required) and the requirements aren't met for the authentication type available, Swaks displays an error and exits. Two ways this can happen include forcing Swaks to use a specific authentication type that Swaks can't use due to missing requirements, or allowing Swaks to use any authentication type, but the server only advertises types Swaks can't support. In the former case Swaks errors out at option processing time since it knows up front it won't be able to authenticate. In the latter case Swaks will error out at the authentication stage of the \s-1SMTP\s0 transaction since Swaks will not be aware that it will not be able to authenticate until that point. .PP Following are the supported authentication types including any individual notes and requirements. .PP The following options affect Swaks' use of authentication. These options are all inter-related. For instance, specifying \-\-auth\-user implies \-\-auth and \-\-auth\-password. Specifying \-\-auth\-optional implies \-\-auth\-user and \-\-auth\-password, etc. .IP "\-a, \-\-auth [auth\-type[,auth\-type,...]]" 4 .IX Item "-a, --auth [auth-type[,auth-type,...]]" Require Swaks to authenticate. If no argument is given, any supported auth-types advertised by the server are tried until one succeeds or all fail. If one or more auth-types are specified as an argument, each that the server also supports is tried in order until one succeeds or all fail. This option requires Swaks to authenticate, so if no common auth-types are found or no credentials succeed, Swaks displays an error and exits. .Sp The following tables lists the valid auth-types .RS 4 .IP "\s-1LOGIN, PLAIN\s0" 4 .IX Item "LOGIN, PLAIN" These basic authentication types are fully supported and tested and have no additional requirements .IP "\s-1CRAM\-MD5\s0" 4 .IX Item "CRAM-MD5" The \s-1CRAM\-MD5\s0 authenticator requires the Digest::MD5 module. It is fully tested and believed to work against any server that implements it. .IP "\s-1DIGEST\-MD5\s0" 4 .IX Item "DIGEST-MD5" The \s-1DIGEST\-MD5\s0 authenticator (\s-1RFC2831\s0) requires the Authen::SASL module. Version 20100211.0 and earlier used Authen::DigestMD5 which had some protocol level errors which prevented it from working with some servers. Authen::SASL's \s-1DIGEST\-MD5\s0 handling is much more robust. .Sp The \s-1DIGEST\-MD5\s0 implementation in Swaks is fairly immature. It currently supports only the \*(L"auth\*(R" qop type, for instance. If you have \s-1DIGEST\-MD5\s0 experience and would like to help Swaks support \s-1DIGEST\-MD5\s0 better, please get in touch with me. .Sp The \s-1DIGEST\-MD5\s0 protocol's \*(L"realm\*(R" value can be set using the \-\-auth\-extra \*(L"realm\*(R" keyword. If no realm is given, a reasonable default will be used. .Sp The \s-1DIGEST\-MD5\s0 protocol's \*(L"digest-uri\*(R" values can be set using the \-\-auth\-extra option. For instance, you could create the digest-uri-value of \*(L"lmtp/mail.example.com/example.com\*(R" with the option \*(L"\-\-auth\-extra dmd5\-serv\-type=lmtp,dmd5\-host=mail.example.com,dmd5\-serv\-name=example.com\*(R". The \*(L"digest-uri-value\*(R" string and its components is defined in \s-1RFC2831.\s0 If none of these values are given, reasonable defaults will be used. .IP "\s-1CRAM\-SHA1\s0" 4 .IX Item "CRAM-SHA1" The \s-1CRAM\-SHA1\s0 authenticator requires the Digest::SHA module. This type has only been tested against a non-standard implementation on an Exim server and may therefore have some implementation deficiencies. .IP "\s-1NTLM/SPA/MSN\s0" 4 .IX Item "NTLM/SPA/MSN" These authenticators require the Authen::NTLM module. Note that there are two modules using the Authen::NTLM namespace on \s-1CPAN.\s0 The Mark Bush implementation (Authen/NTLM\-1.03.tar.gz) is the version required by Swaks. This type has been tested against Exim, Communigate, and Exchange 2007. .Sp In addition to the standard username and password, this authentication type can also recognize a \*(L"domain\*(R". The domain can be set using the \-\-auth\-extra \*(L"domain\*(R" keyword. Note that this has never been tested with a mail server that doesn't ignore \s-1DOMAIN\s0 so this may be implemented incorrectly. .RE .RS 4 .RE .IP "\-ao, \-\-auth\-optional [auth\-type[,auth\-type,...]]" 4 .IX Item "-ao, --auth-optional [auth-type[,auth-type,...]]" This option behaves identically to \-\-auth except that it requests authentication rather than requiring it. If no common auth-types are found or no credentials succeed, Swaks proceeds as if authentication had not been requested. .IP "\-aos, \-\-auth\-optional\-strict [auth\-type[,auth\-type,...]]" 4 .IX Item "-aos, --auth-optional-strict [auth-type[,auth-type,...]]" This option is a compromise between \-\-auth and \-\-auth\-optional. If no common auth-types are found, Swaks behaves as if \-\-auth\-optional were specified and proceeds with the transaction. If Swaks can't support requested auth-type, the server doesn't advertise any common auth-types, or if no credentials succeed, Swaks behaves as if \-\-auth were used and exits with an error. .IP "\-au, \-\-auth\-user [username]" 4 .IX Item "-au, --auth-user [username]" Provide the username to be used for authentication, or prompt the user for it if no argument is provided. The string <> can be supplied to mean an empty username. .IP "\-ap, \-\-auth\-password [password]" 4 .IX Item "-ap, --auth-password [password]" Provide the password to be used for authentication, or prompt the user for it if no argument is provided. The string <> can be supplied to mean an empty password. .IP "\-ae, \-\-auth\-extra [KEYWORD=value[,...]]" 4 .IX Item "-ae, --auth-extra [KEYWORD=value[,...]]" Some of the authentication types allow extra information to be included in the authentication process. Rather than add a new option for every nook and cranny of each authenticator, the \-\-auth\-extra option allows this information to be supplied. .Sp The following table lists the currently recognized keywords and the authenticators that use them .RS 4 .IP "realm, domain" 4 .IX Item "realm, domain" The realm and domain keywords are synonymous. Using either will set the \*(L"domain\*(R" option in \s-1NTLM/MSN/SPA\s0 and the \*(L"realm\*(R" option in \s-1DIGEST\-MD5\s0 .IP "dmd5\-serv\-type" 4 .IX Item "dmd5-serv-type" The dmd5\-serv\-type keyword is used by the \s-1DIGEST\-MD5\s0 authenticator and is used, in part, to build the digest-uri-value string (see \s-1RFC2831\s0) .IP "dmd5\-host" 4 .IX Item "dmd5-host" The dmd5\-host keyword is used by the \s-1DIGEST\-MD5\s0 authenticator and is used, in part, to build the digest-uri-value string (see \s-1RFC2831\s0) .IP "dmd5\-serv\-name" 4 .IX Item "dmd5-serv-name" The dmd5\-serv\-name keyword is used by the \s-1DIGEST\-MD5\s0 authenticator and is used, in part, to build the digest-uri-value string (see \s-1RFC2831\s0) .RE .RS 4 .RE .IP "\-am, \-\-auth\-map [auth\-alias=auth\-type[,...]]" 4 .IX Item "-am, --auth-map [auth-alias=auth-type[,...]]" Provides a way to map alternate names onto base authentication types. Useful for any sites that use alternate names for common types. This functionality is actually used internally to map types \s-1SPA\s0 and \s-1MSN\s0 onto the base type \s-1NTLM.\s0 The command line argument to simulate this would be \*(L"\-\-auth\-map SPA=NTLM,MSN=NTLM\*(R". All of the auth-types listed above are valid targets for mapping except \s-1SPA\s0 and \s-1MSN.\s0 .IP "\-apt, \-\-auth\-plaintext" 4 .IX Item "-apt, --auth-plaintext" Instead of showing \s-1AUTH\s0 strings base64 encoded as they are transmitted, translate them to plaintext before printing on screen. .IP "\-ahp, \-\-auth\-hide\-password [replacement string]" 4 .IX Item "-ahp, --auth-hide-password [replacement string]" If this option is specified, any time a readable password would be printed to the terminal (specifically \s-1AUTH PLAIN\s0 and \s-1AUTH LOGIN\s0) the password is replaced with the string '\s-1PROVIDED_BUT_REMOVED\s0' (or the contents of \*(L"replacement string\*(R" if provided). The dummy string may or may not be base64 encoded, contingent on the \-\-auth\-plaintext option. .Sp Note that \-\-auth\-hide\-password is similar, but not identical, to the \-\-protect\-prompt option. The former protects passwords from being displayed in the \s-1SMTP\s0 transaction regardless of how they are entered. The latter protects sensitive strings when the user types them at the terminal, regardless of how the string would be used. .SH "XCLIENT OPTIONS" .IX Header "XCLIENT OPTIONS" \&\s-1XCLIENT\s0 is an \s-1SMTP\s0 extension introduced by the Postfix project. \s-1XCLIENT\s0 allows a (properly-authorized) client to tell a server to use alternate information, such as \s-1IP\s0 address or hostname, for the client. This allows much easier paths for testing mail server configurations. Full details on the protocol are available at http://www.postfix.org/XCLIENT_README.html. .PP The \s-1XCLIENT\s0 verb can be passed to the server multiple times per \s-1SMTP\s0 session with different attributes. For instance, \s-1HELO\s0 and \s-1PROTO\s0 might be passed in one call and \s-1NAME\s0 and \s-1ADDR\s0 passed in a second. Because it can be useful for testing, Swaks exposes some control over how the attributes are grouped and in what order they are passed to the server. The different options attempt to expose simplicity for those using Swaks as a client, and complexity for those using Swaks to test installs. .IP "\-\-xclient\-addr [\s-1VALUE\s0]" 4 .IX Item "--xclient-addr [VALUE]" .PD 0 .IP "\-\-xclient\-name [\s-1VALUE\s0]" 4 .IX Item "--xclient-name [VALUE]" .IP "\-\-xclient\-port [\s-1VALUE\s0]" 4 .IX Item "--xclient-port [VALUE]" .IP "\-\-xclient\-proto [\s-1VALUE\s0]" 4 .IX Item "--xclient-proto [VALUE]" .IP "\-\-xclient\-destaddr [\s-1VALUE\s0]" 4 .IX Item "--xclient-destaddr [VALUE]" .IP "\-\-xclient\-destport [\s-1VALUE\s0]" 4 .IX Item "--xclient-destport [VALUE]" .IP "\-\-xclient\-helo [\s-1VALUE\s0]" 4 .IX Item "--xclient-helo [VALUE]" .IP "\-\-xclient\-login [\s-1VALUE\s0]" 4 .IX Item "--xclient-login [VALUE]" .IP "\-\-xclient\-reverse\-name [\s-1VALUE\s0]" 4 .IX Item "--xclient-reverse-name [VALUE]" .PD These options specify \s-1XCLIENT\s0 attributes that should be sent to the target server. If [\s-1VALUE\s0] is not provided, Swaks will prompt and read the value on \s-1STDIN.\s0 See http://www.postfix.org/XCLIENT_README.html for official documentation for what the attributes mean and their possible values, including the special \*(L"[\s-1UNAVAILABLE\s0]\*(R" and \*(L"[\s-1TEMPUNAVAIL\s0]\*(R" values. .Sp By way of simple example, setting \*(L"\-\-xclient\-name foo.example.com \-\-xclient\-addr 192.168.1.1\*(R" will cause Swaks to send the \s-1SMTP\s0 command \*(L"\s-1XCLIENT\s0 NAME=foo.example.com ADDR=192.168.1.1\*(R". .Sp Note that the \*(L"\s-1REVERSE_NAME\*(R"\s0 attribute doesn't seem to appear in the official documentation. There is a mailing list thread that documents it, viewable at http://comments.gmane.org/gmane.mail.postfix.user/192623. .Sp These options can all be mixed with each other, and can be mixed with the \-\-xclient option (see below). By default all attributes will be combined into one \s-1XCLIENT\s0 call, but see \-\-xclient\-delim. .IP "\-\-xclient\-delim" 4 .IX Item "--xclient-delim" When this option is specified, it indicates a break in \s-1XCLIENT\s0 attributes to be sent. For instance, setting \*(L"\-\-xclient\-helo 'helo string' \-\-xclient\-delim \-\-xclient\-name foo.example.com \-\-xclient\-addr 192.168.1.1\*(R" will cause Swaks to send two \s-1XCLIENT\s0 calls, \*(L"\s-1XCLIENT\s0 HELO=helo+20string\*(R" and \*(L"\s-1XCLIENT\s0 NAME=foo.example.com ADDR=192.168.1.1\*(R". This option is ignored where it doesn't make sense (at the start or end of \s-1XCLIENT\s0 options, by itself, consecutively, etc). .IP "\-\-xclient [\s-1XCLIENT_STRING\s0]" 4 .IX Item "--xclient [XCLIENT_STRING]" This is the \*(L"free form\*(R" \s-1XCLIENT\s0 option. Whatever value is provided for \s-1XCLIENT_STRING\s0 will be sent verbatim as the argument to the \s-1XCLIENT SMTP\s0 command. For example, if \*(L"\-\-xclient 'NAME= ADDR=192.168.1.1 FOO=bar'\*(R" is used, Swaks will send the \s-1SMTP\s0 command \*(L"\s-1XCLIENT\s0 NAME= ADDR=192.168.1.1 FOO=bar\*(R". If no \s-1XCLIENT_STRING\s0 is passed on command line, Swaks will prompt and read the value on \s-1STDIN.\s0 .Sp The primary advantage to this over the more specific options above is that there is no \s-1XCLIENT\s0 syntax validation here. This allows you to send invalid \s-1XCLIENT\s0 to the target server for testing. Additionally, at least one \s-1MTA\s0 (Message Systems' Momentum, formerly ecelerity) implements \s-1XCLIENT\s0 without advertising supported attributes. The \-\-xclient option allows you to skip the \*(L"supported attributes\*(R" check when communicating with this type of \s-1MTA\s0 (though see also \-\-xclient\-no\-verify). .Sp The \-\-xclient option can be mixed freely with the \-\-xclient\-* options above. If \*(L"\-\-xclient\-addr 192.168.0.1 \-\-xclient 'FOO=bar NAME=wind'\*(R" is given to Swaks, \*(L"\s-1XCLIENT\s0 ADDR=192.168.0.1 FOO=bar NAME=wind\*(R" will be sent to the target server. .IP "\-\-xclient\-no\-verify" 4 .IX Item "--xclient-no-verify" Do not enforce the requirement that an \s-1XCLIENT\s0 attribute must be advertised by the server in order for Swaks to send it in an \s-1XCLIENT\s0 command. This is to support servers which don't advertise the attributes but still support them. .IP "\-\-xclient\-before\-starttls" 4 .IX Item "--xclient-before-starttls" If Swaks is configured to attempt both \s-1XCLIENT\s0 and \s-1STARTTLS,\s0 it will do \s-1STARTTLS\s0 first. If this option is specified it will attempt \s-1XCLIENT\s0 first. .IP "\-\-xclient\-optional" 4 .IX Item "--xclient-optional" .PD 0 .IP "\-\-xclient\-optional\-strict" 4 .IX Item "--xclient-optional-strict" .PD In normal operation, setting one of the \-\-xclient* options will require a successful \s-1XCLIENT\s0 transaction to take place in order to proceed (that is, \s-1XCLIENT\s0 needs to be advertised, all the user-requested attributes need to have been advertised, and the server needs to have accepted Swaks' \s-1XCLIENT\s0 request). These options change that behavior. \-\-xclient\-optional tells Swaks to proceed unconditionally past the \s-1XCLIENT\s0 stage of the \s-1SMTP\s0 transaction, regardless of whether it was successful. \-\-xclient\-optional\-strict is similar but more granular. The strict version will continue to \s-1XCLIENT\s0 was not advertised, but will fail if \s-1XCLIENT\s0 was attempted but did not succeed. .SH "PROXY OPTIONS" .IX Header "PROXY OPTIONS" Swaks implements the Proxy protocol as defined in http://www.haproxy.org/download/1.5/doc/proxy\-protocol.txt. Proxy allows an application load balancer, such as HAProxy, to be used in front of an \s-1MTA\s0 while still allowing the \s-1MTA\s0 access to the originating host information. Proxy support in Swaks allows direct testing of an \s-1MTA\s0 configured to expect requests from a proxy, bypassing the proxy itself during testing. .PP Swaks makes no effort to ensure that the Proxy options used are internally consistent. For instance, \-\-proxy\-family (in version 1) is expected to be one of \*(L"\s-1TCP4\*(R"\s0 or \*(L"\s-1TCP6\*(R".\s0 While it will likely not make sense to the target server, Swaks makes no attempt to ensure that \-\-proxy\-source and \-\-proxy\-dest are in the same protocol family as \-\-proxy\-family or each other. .PP The \-\-proxy option is mutually exclusive with all other \-\-proxy\-* options except \-\-proxy\-version. .PP When \-\-proxy is not used, all of \-\-proxy\-family, \-\-proxy\-source, \-\-proxy\-source\-port, \-\-proxy\-dest, and \-\-proxy\-dest\-port are required. Additionally, when \-\-proxy\-version is 2, \-\-proxy\-protocol and \-\-proxy\-command are optional. .IP "\-\-proxy\-version [ 1 | 2 ]" 4 .IX Item "--proxy-version [ 1 | 2 ]" Whether to use version 1 (human readable) or version 2 (binary) of the Proxy protocol. Version 1 is the default. Version 2 is only implemented through the \*(L"address block\*(R", and is roughly on par with the information provided in version 1. .IP "\-\-proxy [\s-1VALUE\s0]" 4 .IX Item "--proxy [VALUE]" If this option is used, its argument is passed unchanged after the \*(L"\s-1PROXY \*(R"\s0 portion (or the 12\-byte protocol header for version 2) of the Proxy exchange. This option allows sending incomplete or malformed Proxy strings to a target server for testing. No attempt to translate or modify this string is made, so if used with \*(L"\-\-proxy\-version 2\*(R" the argument should be in the appropriate binary format. This option is mutually exclusive with all other \-\-proxy\-* options which provide granular proxy information. .IP "\-\-proxy\-family [\s-1VALUE\s0]" 4 .IX Item "--proxy-family [VALUE]" For version 1, specifies both the address family and transport protocol. The protocol defines \s-1TCP4\s0 and \s-1TCP6.\s0 .Sp For version 2, specifies only the address family. The protocol defines \s-1AF_UNSPEC, AF_INET, AF_INET6,\s0 and \s-1AF_UNIX.\s0 .IP "\-\-proxy\-protocol [\s-1VALUE\s0]" 4 .IX Item "--proxy-protocol [VALUE]" For version 2, specifies the transport protocol. The protocol defines \s-1UNSPEC, STREAM,\s0 and \s-1DGRAM.\s0 The default is \s-1STREAM.\s0 This option is unused in version 1 .IP "\-\-proxy\-command [\s-1VALUE\s0]" 4 .IX Item "--proxy-command [VALUE]" For version 2, specifies the transport protocol. The protocol defines \s-1LOCAL\s0 and \s-1PROXY.\s0 The default is \s-1PROXY.\s0 This option is unused in version 1 .IP "\-\-proxy\-source [\s-1VALUE\s0]" 4 .IX Item "--proxy-source [VALUE]" Specify the source address of the proxied connection. .IP "\-\-proxy\-source\-port [\s-1VALUE\s0]" 4 .IX Item "--proxy-source-port [VALUE]" Specify the source port of the proxied connection. .IP "\-\-proxy\-dest [\s-1VALUE\s0]" 4 .IX Item "--proxy-dest [VALUE]" Specify the destination address of the proxied connection. .IP "\-\-proxy\-dest\-port [\s-1VALUE\s0]" 4 .IX Item "--proxy-dest-port [VALUE]" Specify the destination port of the proxied connection. .SH "DATA OPTIONS" .IX Header "DATA OPTIONS" These options pertain to the contents for the \s-1DATA\s0 portion of the \s-1SMTP\s0 transaction. .IP "\-d, \-\-data [data\-portion]" 4 .IX Item "-d, --data [data-portion]" Use argument as the entire contents of \s-1DATA,\s0 or prompt user if no argument specified. If the argument '\-' is provided the data will be read from \s-1STDIN.\s0 If any other argument is provided and it represents the name of an open-able file, the contents of the file will be used. Any other argument will be itself for the \s-1DATA\s0 contents. .Sp The value can be on one single line, with \en (\s-1ASCII\s0 0x5c, 0x6e) representing where line breaks should be placed. Leading dots will be quoted. Closing dot is not required but is allowed. The default value for this option is \*(L"Date: \f(CW%DATE\fR%\enTo: \f(CW%TO_ADDRESS\fR%\enFrom: \f(CW%FROM_ADDRESS\fR%\enSubject: test \f(CW%DATE\fR%\enMessage\-Id: <%MESSAGEID%>\enX\-Mailer: swaks v%SWAKS_VERSION jetmore.org/john/code/swaks/\en%NEW_HEADERS%\en%BODY%\en\*(R". .Sp Very basic token parsing is performed on the \s-1DATA\s0 portion. The following table shows the recognized tokens and their replacement values: .RS 4 .ie n .IP "%FROM_ADDRESS%" 4 .el .IP "\f(CW%FROM_ADDRESS\fR%" 4 .IX Item "%FROM_ADDRESS%" Replaced with the envelope-sender. .ie n .IP "%TO_ADDRESS%" 4 .el .IP "\f(CW%TO_ADDRESS\fR%" 4 .IX Item "%TO_ADDRESS%" Replaced with the envelope\-recipient(s). .ie n .IP "%DATE%" 4 .el .IP "\f(CW%DATE\fR%" 4 .IX Item "%DATE%" Replaced with the current time in a format suitable for inclusion in the Date: header. Note this attempts to use the standard module Time::Local for timezone calculations. If this module is unavailable the date string will be in \s-1GMT.\s0 .ie n .IP "%MESSAGEID%" 4 .el .IP "\f(CW%MESSAGEID\fR%" 4 .IX Item "%MESSAGEID%" Replaced with a message \s-1ID\s0 string suitable for use in a Message-Id header. The value for this token will remain consistent for the life of the process. .ie n .IP "%SWAKS_VERSION%" 4 .el .IP "\f(CW%SWAKS_VERSION\fR%" 4 .IX Item "%SWAKS_VERSION%" Replaced with the version of the currently-running Swaks process. .ie n .IP "%NEW_HEADERS%" 4 .el .IP "\f(CW%NEW_HEADERS\fR%" 4 .IX Item "%NEW_HEADERS%" Replaced with the contents of the \-\-add\-header option. If \-\-add\-header is not specified this token is simply removed. .ie n .IP "%BODY%" 4 .el .IP "\f(CW%BODY\fR%" 4 .IX Item "%BODY%" Replaced with the value specified by the \-\-body option. See \-\-body for default. .RE .RS 4 .RE .IP "\-dab, \-\-dump\-as\-body [section[,section]]" 4 .IX Item "-dab, --dump-as-body [section[,section]]" If \-\-dump\-as\-body is used and no other option is used to change the default body of the message, the body is replaced with output similar to the output of what is provided by \-\-dump. \-\-dump's initial program capability stanza is not displayed, and the \*(L"data\*(R" section is not included. Additionally, \-\-dump always includes passwords. By default \-\-dump\-as\-body does not include passwords, though this can be changed with \-\-dump\-as\-body\-shows\-password. \-\-dump\-as\-body takes the same arguments as \-\-dump except the \s-1SUPPORT\s0 and \s-1DATA\s0 arguments are not supported. .IP "\-dabsp, \-\-dump\-as\-body\-shows\-password" 4 .IX Item "-dabsp, --dump-as-body-shows-password" Cause \-\-dump\-as\-body to include plaintext passwords. This option is not recommended. This option implies \-\-dump\-as\-body. .IP "\-\-body [body\-specification]" 4 .IX Item "--body [body-specification]" Specify the body of the email. The default is \*(L"This is a test mailing\*(R". If no argument to \-\-body is given, prompt to supply one interactively. If '\-' is supplied, the body will be read from standard input. If any other text is provided and the text represents an open-able file, the content of that file is used as the body. If it does not represent an open-able file, the text itself is used as the body. .Sp If the message is forced to \s-1MIME\s0 format (see \-\-attach) the argument to this option will be included unencoded as the first \s-1MIME\s0 part. Its content-type will always be text/plain. .IP "\-\-attach [attachment\-specification]" 4 .IX Item "--attach [attachment-specification]" When one or more \-\-attach option is supplied, the message is changed into a multipart/mixed \s-1MIME\s0 message. The arguments to \-\-attach are processed the same as \-\-body with respect to \s-1STDIN,\s0 file contents, etc. \-\-attach can be supplied multiple times to create multiple attachments. By default, each attachment is attached as an application/octet\-stream file. See \-\-attach\-type for changing this behavior. .Sp If a filename is specified, the \s-1MIME\s0 encoding will include that file name. See \-\-attach\-name for more detail on file naming. .Sp It is legal for '\-' (\s-1STDIN\s0) to be specified as an argument multiple times (once for \-\-body and multiple times for \-\-attach). In this case, the same content will be attached each time it is specified. This is useful for attaching the same content with multiple \s-1MIME\s0 types. .IP "\-\-attach\-type [mime\-type]" 4 .IX Item "--attach-type [mime-type]" By default, content that gets \s-1MIME\s0 attached to a message with the \-\-attach option is encoded as application/octet\-stream. \-\-attach\-type changes the mime type for every \-\-attach option which follows it. It can be specified multiple times. .IP "\-\-attach\-name [name]" 4 .IX Item "--attach-name [name]" This option sets the filename that will be included in the \s-1MIME\s0 part created for the next \-\-attach option. If no argument is set for this option, it causes no filename information to be included for the next \s-1MIME\s0 part, even if Swaks could generate it from the local file name. .IP "\-ah, \-\-add\-header [header]" 4 .IX Item "-ah, --add-header [header]" This option allows headers to be added to the \s-1DATA.\s0 If \f(CW%H\fR is present in the \s-1DATA\s0 it is replaced with the argument to this option. If \f(CW%H\fR is not present, the argument is inserted between the first two consecutive newlines in the \s-1DATA\s0 (that is, it is inserted at the end of the existing headers). .Sp The option can either be specified multiple times or a single time with multiple headers separated by a literal '\en' string. So, \*(L"\-\-add\-header 'Foo: bar' \-\-add\-header 'Baz: foo'\*(R" and \*(L"\-\-add\-header 'Foo: bar\enBaz: foo'\*(R" end up adding the same two headers. .IP "\-\-header [header\-and\-data], \-\-h\-Header [data]" 4 .IX Item "--header [header-and-data], --h-Header [data]" These options allow a way to change headers that already exist in the \s-1DATA.\s0 '\-\-header \*(L"Subject: foo\*(R"' and '\-\-h\-Subject foo' are equivalent. If the header does not already exist in the data then this argument behaves identically to \-\-add\-header. However, if the header already exists it is replaced with the one specified. .IP "\-g" 4 .IX Item "-g" If specified, Swaks will read the \s-1DATA\s0 value for the mail from \s-1STDIN.\s0 This is equivalent to \*(L"\-\-data \-\*(R". If there is a From_ line in the email, it will be removed (but see \-nsf option). Useful for delivering real message (stored in files) instead of using example messages. .IP "\-\-no\-data\-fixup, \-ndf" 4 .IX Item "--no-data-fixup, -ndf" This option forces Swaks to do no massaging of the \s-1DATA\s0 portion of the email. This includes token replacement, From_ stripping, trailing-dot addition, \-\-body/attachment inclusion, and any header additions. This option is only useful when used with \-\-data, since the internal default \s-1DATA\s0 portion uses tokens. .IP "\-\-no\-strip\-from, \-nsf" 4 .IX Item "--no-strip-from, -nsf" Don't strip the From_ line from the \s-1DATA\s0 portion, if present. .SH "OUTPUT OPTIONS" .IX Header "OUTPUT OPTIONS" Swaks provides a transcript of its transactions to its caller (\s-1STDOUT/STDERR\s0) by default. This transcript aims to be as faithful a representation as possible of the transaction though it does modify this output by adding informational prefixes to lines and by providing plaintext versions of \s-1TLS\s0 transactions .PP The \*(L"informational prefixes\*(R" are referred to as transaction hints. These hints are initially composed of those marking lines that are output of Swaks itself, either informational or error messages, and those that indicate a line of data actually sent or received in a transaction. This table indicates the hints and their meanings: .ie n .IP """===""" 4 .el .IP "\f(CW===\fR" 4 .IX Item "===" Indicates an informational line generated by Swaks .ie n .IP """***""" 4 .el .IP "\f(CW***\fR" 4 .IX Item "***" Indicates an error generated within Swaks .ie n .IP """\ \->""" 4 .el .IP "\f(CW\ \->\fR" 4 .IX Item "->" Indicates an expected line sent by Swaks to target server .ie n .IP """\ ~>""" 4 .el .IP "\f(CW\ ~>\fR" 4 .IX Item "~>" Indicates a TLS-encrypted, expected line sent by Swaks to target server .ie n .IP """**>""" 4 .el .IP "\f(CW**>\fR" 4 .IX Item "**>" Indicates an unexpected line sent by Swaks to the target server .ie n .IP """*~>""" 4 .el .IP "\f(CW*~>\fR" 4 .IX Item "*~>" Indicates a TLS-encrypted, unexpected line sent by Swaks to target server .ie n .IP """\ \ >""" 4 .el .IP "\f(CW\ \ >\fR" 4 .IX Item ">" Indicates a raw chunk of text sent by Swaks to a target server (see \-\-show\-raw\-text). There is no concept of \*(L"expected\*(R" or \*(L"unexpected\*(R" at this level. .ie n .IP """<\-\ """ 4 .el .IP "\f(CW<\-\ \fR" 4 .IX Item "<-" Indicates an expected line sent by target server to Swaks .ie n .IP """<~\ """ 4 .el .IP "\f(CW<~\ \fR" 4 .IX Item "<~" Indicates a TLS-encrypted, expected line sent by target server to Swaks .ie n .IP """<**""" 4 .el .IP "\f(CW<**\fR" 4 .IX Item "<**" Indicates an unexpected line sent by target server to Swaks .ie n .IP """<~*""" 4 .el .IP "\f(CW<~*\fR" 4 .IX Item "<~*" Indicates a TLS-encrypted, unexpected line sent by target server to Swaks .ie n .IP """<\ \ """ 4 .el .IP "\f(CW<\ \ \fR" 4 .IX Item "<" Indicates a raw chunk of text received by Swaks from a target server (see \-\-show\-raw\-text). There is no concept of \*(L"expected\*(R" or \*(L"unexpected\*(R" at this level. .PP The following options control what and how output is displayed to the caller. .IP "\-n, \-\-suppress\-data" 4 .IX Item "-n, --suppress-data" Summarizes the \s-1DATA\s0 portion of the \s-1SMTP\s0 transaction instead of printing every line. This option is very helpful, bordering on required, when using Swaks to send certain test emails. Emails with attachments, for instance, will quickly overwhelm a terminal if the \s-1DATA\s0 is not suppressed. .IP "\-stl, \-\-show\-time\-lapse [i]" 4 .IX Item "-stl, --show-time-lapse [i]" Display time lapse between send/receive pairs. This option is most useful when Time::HiRes is available, in which case the time lapse will be displayed in thousandths of a second. If Time::HiRes is unavailable or \*(L"i\*(R" is given as an argument the lapse will be displayed in integer seconds only. .IP "\-nih, \-\-no\-info\-hints" 4 .IX Item "-nih, --no-info-hints" Don't display the transaction hint for informational transactions. This is most useful when needing to copy some portion of the informational lines, for instance the certificate output from \-\-tls\-get\-peer\-cert. .IP "\-nsh, \-\-no\-send\-hints" 4 .IX Item "-nsh, --no-send-hints" .PD 0 .IP "\-nrh, \-\-no\-receive\-hints" 4 .IX Item "-nrh, --no-receive-hints" .IP "\-nth, \-\-no\-hints" 4 .IX Item "-nth, --no-hints" .PD \&\-\-no\-send\-hints and \-\-no\-receive\-hints suppress the transaction prefix from send and receive lines, respectively. This is often useful when copying some portion of the transaction for use elsewhere (for instance, \*(L"\-\-no\-send\-hints \-\-hide\-receive \-\-hide\-informational\*(R" is a useful way to get only the client-side commands for a given transaction). \-\-no\-hints is identical to specifying both \-\-no\-send\-hints and \-\-no\-receive\-hints. .Sp Don't show transaction hints (useful in conjunction with \-hr to create copy/paste\-able transactions). .IP "\-raw, \-\-show\-raw\-text" 4 .IX Item "-raw, --show-raw-text" This option will print a hex dump of raw data sent and received by Swaks. Each hex dump is the contents of a single read or write on the network. This should be identical to what is already being displayed (with the exception of the \er characters being removed). This option is useful in seeing details when servers are sending lots of data in single packets, or breaking up individual lines into multiple packets. If you really need to go in depth in that area you're probably better with a packet sniffer, but this option is a good first step to seeing odd connection issues. .IP "\-\-output, \-\-output\-file " 4 .IX Item "--output, --output-file " .PD 0 .IP "\-\-output\-file\-stdout " 4 .IX Item "--output-file-stdout " .IP "\-\-output\-file\-stderr " 4 .IX Item "--output-file-stderr " .PD These options allow the user to send output to files instead of \s-1STDOUT/STDERR.\s0 The first option sends both to the same file. The arguments of &STDOUT and &STDERR are treated specially, referring to the \*(L"normal\*(R" file handles, so \*(L"\-\-output\-file\-stderr '&STDOUT'\*(R" would redirect \s-1STDERR\s0 to \s-1STDOUT.\s0 These options are honored for all output except \-\-help and \-\-version. .IP "\-pp, \-\-protect\-prompt" 4 .IX Item "-pp, --protect-prompt" Don't echo user input on prompts that are potentially sensitive (right now only authentication password). See also \-\-auth\-hide\-password .IP "\-hr, \-\-hide\-receive" 4 .IX Item "-hr, --hide-receive" Don't display lines sent from the remote server being received by Swaks .IP "\-hs, \-\-hide\-send" 4 .IX Item "-hs, --hide-send" Don't display lines being sent by Swaks to the remote server .IP "\-hi, \-\-hide\-informational" 4 .IX Item "-hi, --hide-informational" Don't display non-error informational lines from Swaks itself. .IP "\-ha, \-\-hide\-all" 4 .IX Item "-ha, --hide-all" Do not display any content to the terminal. .IP "\-S, \-\-silent [level]" 4 .IX Item "-S, --silent [level]" Cause Swaks to be silent. If no argument is given or if an argument of \*(L"1\*(R" is given, print no output unless/until an error occurs, after which all output is shown. If an argument of \*(L"2\*(R" is given, only print errors. If \*(L"3\*(R" is given, show no output ever. \-\-silent affects most output but not all. For instance, \-\-help, \-\-version, \-\-dump, and \-\-dump\-mail are not affected. .IP "\-\-support" 4 .IX Item "--support" Print capabilities and exit. Certain features require non-standard Perl modules. This option evaluates whether these modules are present and displays which functionality is available and which isn't, and which modules would need to be added to gain the missing functionality. .IP "\-\-dump\-mail" 4 .IX Item "--dump-mail" Cause Swaks to process all options to generate the message it would send, then print that message to \s-1STDOUT\s0 instead of sending it. This output is identical to the \*(L"data\*(R" section of \-\-dump, except without the trailing dot. .IP "\-\-dump [section[,section]]" 4 .IX Item "--dump [section[,section]]" This option causes Swaks to print the results of option processing, immediately before mail would have been sent. No mail will be sent when \-\-dump is used. Note that \-\-dump is a pure self-diagnosis tool and no effort is made or will ever be made to mask passwords in the \-\-dump output. If a section is provided as an argument to this option, only the requested section will be shown. Currently supported arguments are \s-1SUPPORT, APP, OUTPUT, TRANSPORT, PROTOCOL, XCLIENT, PROXY, TLS, AUTH, DATA,\s0 and \s-1ALL.\s0 If no argument is provided, all sections are displayed .IP "\-\-help" 4 .IX Item "--help" Display this help information. .IP "\-\-version" 4 .IX Item "--version" Display version information. .SH "PORTABILITY" .IX Header "PORTABILITY" .IP "\s-1OPERATING SYSTEMS\s0" 4 .IX Item "OPERATING SYSTEMS" This program was primarily intended for use on UNIX-like operating systems, and it should work on any reasonable version thereof. It has been developed and tested on Solaris, Linux, and Mac \s-1OS X\s0 and is feature complete on all of these. .Sp This program is known to demonstrate basic functionality on Windows using ActiveState's Perl. It has not been fully tested. Known to work are basic \s-1SMTP\s0 functionality and the \s-1LOGIN, PLAIN,\s0 and \s-1CRAM\-MD5\s0 auth types. Unknown is any \s-1TLS\s0 functionality and the \s-1NTLM/SPA\s0 and \s-1DIGEST\-MD5\s0 auth types. .Sp Because this program should work anywhere Perl works, I would appreciate knowing about any new operating systems you've thoroughly used Swaks on as well as any problems encountered on a new \s-1OS.\s0 .IP "\s-1MAIL SERVERS\s0" 4 .IX Item "MAIL SERVERS" This program was almost exclusively developed against Exim mail servers. It has been used casually by the author, though not thoroughly tested, with Sendmail, Smail, Exchange, Oracle Collaboration Suite, qpsmtpd, and Communigate. Because all functionality in Swaks is based on known standards it should work with any fairly modern mail server. If a problem is found, please alert the author at the address below. .SH "EXIT CODES" .IX Header "EXIT CODES" .IP "0" 4 no errors occurred .IP "1" 4 .IX Item "1" error parsing command line options .IP "2" 4 .IX Item "2" error connecting to remote server .IP "3" 4 .IX Item "3" unknown connection type .IP "4" 4 .IX Item "4" while running with connection type of \*(L"pipe\*(R", fatal problem writing to or reading from the child process .IP "5" 4 .IX Item "5" while running with connection type of \*(L"pipe\*(R", child process died unexpectedly. This can mean that the program specified with \-\-pipe doesn't exist. .IP "6" 4 .IX Item "6" Connection closed unexpectedly. If the close is detected in response to the '\s-1QUIT\s0' Swaks sends following an unexpected response, the error code for that unexpected response is used instead. For instance, if a mail server returns a 550 response to a \s-1MAIL FROM:\s0 and then immediately closes the connection, Swaks detects that the connection is closed, but uses the more specific exit code 23 to detail the nature of the failure. If instead the server return a 250 code and then immediately closes the connection, Swaks will use the exit code 6 because there is not a more specific exit code. .IP "10" 4 .IX Item "10" error in prerequisites (needed module not available) .IP "21" 4 .IX Item "21" error reading initial banner from server .IP "22" 4 .IX Item "22" error in \s-1HELO\s0 transaction .IP "23" 4 .IX Item "23" error in \s-1MAIL\s0 transaction .IP "24" 4 .IX Item "24" no RCPTs accepted .IP "25" 4 .IX Item "25" server returned error to \s-1DATA\s0 request .IP "26" 4 .IX Item "26" server did not accept mail following data .IP "27" 4 .IX Item "27" server returned error after normal-session quit request .IP "28" 4 .IX Item "28" error in \s-1AUTH\s0 transaction .IP "29" 4 .IX Item "29" error in \s-1TLS\s0 transaction .IP "30" 4 .IX Item "30" \&\s-1PRDR\s0 requested/required but not advertised .IP "32" 4 .IX Item "32" error in \s-1EHLO\s0 following \s-1TLS\s0 negotiation .IP "33" 4 .IX Item "33" error in \s-1XCLIENT\s0 transaction .IP "34" 4 .IX Item "34" error in \s-1EHLO\s0 following \s-1XCLIENT\s0 .IP "35" 4 .IX Item "35" error in \s-1PROXY\s0 option processing .IP "36" 4 .IX Item "36" error sending \s-1PROXY\s0 banner .SH "ABOUT THE NAME" .IX Header "ABOUT THE NAME" The name \*(L"Swaks\*(R" is a (sort-of) acronym for \*(L"SWiss Army Knife \s-1SMTP\*(R".\s0 It was chosen to be fairly distinct and pronounceable. While \*(L"Swaks\*(R" is unique as the name of a software package, it has some other, non-software meanings. Please send in other uses of \*(L"swak\*(R" or \*(L"swaks\*(R" for inclusion. .ie n .IP """Sealed With A Kiss""" 4 .el .IP "``Sealed With A Kiss''" 4 .IX Item "Sealed With A Kiss" SWAK/SWAKs turns up occasionally on the internet with the meaning \*(L"with love\*(R". .IP "bad / poor / ill (Afrikaans)" 4 .IX Item "bad / poor / ill (Afrikaans)" Seen in the headline \*(L"\s-1SA\s0 se bes en swaks gekledes in 2011\*(R", which was translated as \*(L"best and worst dressed\*(R" by native speakers. Google Translate doesn't like \*(L"swaks gekledes\*(R", but it will translate \*(L"swak\*(R" as \*(L"poor\*(R" and \*(L"swak geklede\*(R" as \*(L"ill-dressed\*(R". .SH "LICENSE" .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. .PP This program is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See the \&\s-1GNU\s0 General Public License for more details. .PP You should have received a copy of the \s-1GNU\s0 General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, \s-1MA 02110\-1301, USA.\s0 .SH "CONTACT INFORMATION" .IX Header "CONTACT INFORMATION" General contact, questions, patches, requests, etc to proj\-swaks@jetmore.net. .PP Change logs, this help, and the latest version are found at http://www.jetmore.org/john/code/swaks/. .PP Swaks is crafted with love by John Jetmore from the cornfields of Indiana, United States of America. .SH "NOTIFICATIONS" .IX Header "NOTIFICATIONS" .IP "Email" 4 .IX Item "Email" updates\-swaks@jetmore.net .Sp If you would like to be put on a list to receive notifications when a new version of Swaks is released, please send an email to this address. There will not be a response to your email. .IP "Website" 4 .IX Item "Website" http://www.jetmore.org/john/blog/c/swaks/ .IP "\s-1RSS\s0 Feed" 4 .IX Item "RSS Feed" http://www.jetmore.org/john/blog/c/swaks/feed/ .IP "Twitter" 4 .IX Item "Twitter" http://twitter.com/SwaksSMTP