Sync usage with man page.

[netbsd-mini2440.git] / external / ibm-public / postfix / dist / README_FILES / XCLIENT_README

P\bPo\bos\bst\btf\bfi\bix\bx X\bXC\bCL\bLI\bIE\bEN\bNT\bT H\bHo\bow\bwt\bto\bo

-------------------------------------------------------------------------------

P\bPu\bur\brp\bpo\bos\bse\be o\bof\bf t\bth\bhe\be X\bXC\bCL\bLI\bIE\bEN\bNT\bT e\bex\bxt\bte\ben\bns\bsi\bio\bon\bn t\bto\bo S\bSM\bMT\bTP\bP

When an SMTP server announces support for the XCLIENT command, an SMTP client
may send information that overrides one or more client-related session
attributes. The XCLIENT command targets the following problems:

 1. Access control tests. SMTP server access rules are difficult to verify when
    decisions can be triggered only by remote clients. In order to facilitate
    access rule testing, an authorized SMTP client test program needs the
    ability to override the SMTP server's idea of the SMTP client hostname,
    network address, and other client information, for the entire duration of
    an SMTP session.

 2. Client software that downloads mail from an up-stream mail server and
    injects it into a local MTA via SMTP. In order to take advantage of the
    local MTA's SMTP server access rules, the client software needs the ability
    to override the SMTP server's idea of the remote client name, client
    address and other information. Such information can typically be extracted
    from the up-stream mail server's Received: message header.

 3. Post-filter access control and logging. With Internet->filter->MTA style
    content filter applications, the filter can be simplified if it can
    delegate decisions concerning mail relay and other access control to the
    MTA. This is especially useful when the filter acts as a transparent proxy
    for SMTP commands. This requires that the filter can override the MTA's
    idea of the SMTP client hostname, network address, and other information.

X\bXC\bCL\bLI\bIE\bEN\bNT\bT C\bCo\bom\bmm\bma\ban\bnd\bd s\bsy\byn\bnt\bta\bax\bx

An example client-server conversation is given at the end of this document.

In SMTP server EHLO replies, the keyword associated with this extension is
XCLIENT. It is followed by the names of the attributes that the XCLIENT
implementation supports.

The XCLIENT command may be sent at any time, except in the middle of a mail
delivery transaction (i.e. between MAIL and DOT, or MAIL and RSET). The XCLIENT
command may be pipelined when the server supports ESMTP command pipelining. To
avoid triggering spamware detectors, the command should be sent at the end of a
command group.

The syntax of XCLIENT requests is described below. Upper case and quoted
strings specify terminals, lowercase strings specify meta terminals, and SP is
whitespace. Although command and attribute names are shown in upper case, they
are in fact case insensitive.

    xclient-command = XCLIENT 1*( SP attribute-name"="attribute-value )

    attribute-name = ( NAME | ADDR | PORT | PROTO | HELO )

    attribute-value = xtext

  * Attribute values are xtext encoded as per RFC 1891.

  * The NAME attribute specifies an SMTP client hostname (not an SMTP client
    address), [UNAVAILABLE] when client hostname lookup failed due to a
    permanent error, or [TEMPUNAVAIL] when the lookup error condition was
    transient.

  * The ADDR attribute specifies an SMTP client numerical IPv4 network address,
    an IPv6 address prefixed with IPV6:, or [UNAVAILABLE] when the address
    information is unavailable. Address information is not enclosed with [].

  * The PORT attribute specifies the SMTP client TCP port number as a decimal
    number, or [UNAVAILABLE] when the information is unavailable.

  * The PROTO attribute specifies either SMTP or ESMTP.

  * The HELO attribute specifies an SMTP HELO parameter value, or the value
    [UNAVAILABLE] when the information is unavailable.

Note 1: syntactically valid NAME and HELO attribute-value elements can be up to
255 characters long. The client must not send XCLIENT commands that exceed the
512 character limit for SMTP commands. To avoid exceeding the limit the client
should send the information in multiple XCLIENT commands; for example, send
NAME and ADDR first, then HELO and PROTO.

Note 2: [UNAVAILABLE], [TEMPUNAVAIL] and IPV6: may be specified in upper case,
lower case or mixed case.

Note 3: Postfix implementations prior to version 2.3 do not xtext encode
attribute values. Servers that wish to interoperate with these older
implementations should be prepared to receive unencoded information.

Note 4: Postfix implementations prior to version 2.5 do not implement the PORT
attribute.

X\bXC\bCL\bLI\bIE\bEN\bNT\bT S\bSe\ber\brv\bve\ber\br r\bre\bes\bsp\bpo\bon\bns\bse\be

Upon receipt of a correctly formatted XCLIENT command, the server resets state
to the initial SMTP greeting protocol stage. Depending on the outcome of
optional access decisions, the server responds with 220 or with a suitable
rejection code.

For practical reasons it is not always possible to reset the complete server
state to the initial SMTP greeting protocol stage:

  * TLS session information may not be reset, because turning off TLS leaves
    the connection in an undefined state. Consequently, the server may not
    announce STARTTLS when TLS is already active, and access decisions may be
    influenced by client certificate information that was received prior to the
    XCLIENT command.

  * The SMTP server must not reset attributes that were received with the last
    XCLIENT command. This includes HELO or PROTO attributes.

NOTE: Postfix implementations prior to version 2.3 do not jump back to the
initial SMTP greeting protocol stage. These older implementations will not
correctly simulate connection-level access decisions under some conditions.

X\bXC\bCL\bLI\bIE\bEN\bNT\bT s\bse\ber\brv\bve\ber\br r\bre\bep\bpl\bly\by c\bco\bod\bde\bes\bs

     _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b 
    |C\bCo\bod\bde\be |M\bMe\bea\ban\bni\bin\bng\bg                                                |
    |_\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
    |220  |success                                                |
    |_\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
    |421  |unable to proceed, disconnecting                       |
    |_\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
    |501  |bad command parameter syntax                           |
    |_\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
    |503  |mail transaction in progress                           |
    |_\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
    |550  |insufficient authorization                             |
    |_\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
    |other|connection rejected by connection-level access decision|
    |_\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |

X\bXC\bCL\bLI\bIE\bEN\bNT\bT E\bEx\bxa\bam\bmp\bpl\ble\be

In the example, the client impersonates a mail originating system by passing
all SMTP client information via the XCLIENT command. Information sent by the
client is shown in bold font.

    220 server.example.com ESMTP Postfix
    E\bEH\bHL\bLO\bO c\bcl\bli\bie\ben\bnt\bt.\b.e\bex\bxa\bam\bmp\bpl\ble\be.\b.c\bco\bom\bm
    250-server.example.com
    250-PIPELINING
    250-SIZE 10240000
    250-VRFY
    250-ETRN
    250-XCLIENT NAME ADDR PROTO HELO
    250 8BITMIME
    X\bXC\bCL\bLI\bIE\bEN\bNT\bT N\bNA\bAM\bME\bE=\b=s\bsp\bpi\bik\bke\be.\b.p\bpo\bor\brc\bcu\bup\bpi\bin\bne\be.\b.o\bor\brg\bg A\bAD\bDD\bDR\bR=\b=1\b16\b68\b8.\b.1\b10\b00\b0.\b.1\b18\b89\b9.\b.2\b2
    220 server.example.com ESMTP Postfix
    E\bEH\bHL\bLO\bO s\bsp\bpi\bik\bke\be.\b.p\bpo\bor\brc\bcu\bup\bpi\bin\bne\be.\b.o\bor\brg\bg
    250-server.example.com
    250-PIPELINING
    250-SIZE 10240000
    250-VRFY
    250-ETRN
    250-XCLIENT NAME ADDR PROTO HELO
    250 8BITMIME
    M\bMA\bAI\bIL\bL F\bFR\bRO\bOM\bM:\b:<\b<w\bwi\bie\bet\bts\bse\be@\b@p\bpo\bor\brc\bcu\bup\bpi\bin\bne\be.\b.o\bor\brg\bg>\b>
    250 Ok
    R\bRC\bCP\bPT\bT T\bTO\bO:\b:<\b<u\bus\bse\ber\br@\b@e\bex\bxa\bam\bmp\bpl\ble\be.\b.c\bco\bom\bm>\b>
    250 Ok
    D\bDA\bAT\bTA\bA
    354 End data with <CR><LF>.<CR><LF>
    .\b. .\b. .\b.m\bme\bes\bss\bsa\bag\bge\be c\bco\bon\bnt\bte\ben\bnt\bt.\b. .\b. .\b.
    .\b.
    250 Ok: queued as 763402AAE6
    Q\bQU\bUI\bIT\bT
    221 Bye

S\bSe\bec\bcu\bur\bri\bit\bty\by

The XCLIENT command changes audit trails and/or SMTP client access permissions.
Use of this command must be restricted to authorized SMTP clients.

S\bSM\bMT\bTP\bP c\bco\bon\bnn\bne\bec\bct\bti\bio\bon\bn c\bca\bac\bch\bhi\bin\bng\bg

XCLIENT attributes persist until the end of an SMTP session. If one session is
used to deliver mail on behalf of different SMTP clients, the XCLIENT
attributes need to be reset as appropriate before each MAIL FROM command.

R\bRe\bef\bfe\ber\bre\ben\bnc\bce\bes\bs

Moore, K, "SMTP Service Extension for Delivery Status Notifications", RFC 1891,
January 1996.