Section 5. Session Administration Commands

5.1.  Initial Connection
5.1.1.  Usage
   This command MUST NOT be pipelined.
   Responses [1]
     200    Service available, posting allowed
     201    Service available, posting prohibited
     400    Service temporarily unavailable [2]
     502    Service permanently unavailable [2]
   [1] These are the only valid response codes for the initial greeting;
       the server MUST not return any other generic response code.
   [2] Following a 400 or 502 response, the server MUST immediately
       close the connection.
5.1.2.  Description
   There is no command presented by the client upon initial connection
   to the server.  The server MUST present an appropriate response code
   as a greeting to the client.  This response informs the client
   whether service is available and whether the client is permitted to
   post.
   If the server will accept further commands from the client including
   POST, the server MUST present a 200 greeting code.  If the server
   will accept further commands from the client, but the client is not
   authorized to post articles using the POST command, the server MUST
   present a 201 greeting code.
   Otherwise, the server MUST present a 400 or 502 greeting code and
   then immediately close the connection. 400 SHOULD be used if the
   issue is only temporary (for example, because of load) and the client
   can expect to be able to connect successfully at some point in the
   future without making any changes. 502 MUST be used if the client is
   not permitted under any circumstances to interact with the server,
   and MAY be used if the server has insufficient information to
   determine whether the issue is temporary or permanent.
   Note: the distinction between the 200 and 201 response codes has
   turned out in practice to be insufficient; for example, some servers
   do not allow posting until the client has authenticated, while other
   clients assume that a 201 response means that posting will never be
   possible even after authentication.  Therefore, clients SHOULD use
   the CAPABILITIES command (Section 5.2) rather than rely on this
   response.
5.1.3.  Examples
   Example of a normal connection from an authorized client that then
   terminates the session (see Section 5.4):
      [Initial connection set-up completed.]
      [S] 200 NNTP Service Ready, posting permitted
      [C] QUIT
      [S] 205 NNTP Service exits normally
      [Server closes connection.]
   Example of a normal connection from an authorized client that is not
   permitted to post, which also immediately terminates the session:
      [Initial connection set-up completed.]
      [S] 201 NNTP Service Ready, posting prohibited
      [C] QUIT
      [S] 205 NNTP Service exits normally
      [Server closes connection.]
   Example of a normal connection from an unauthorized client:
      [Initial connection set-up completed.]
      [S] 502 NNTP Service permanently unavailable
      [Server closes connection.]
   Example of a connection from a client if the server is unable to
   provide service:
      [Initial connection set-up completed.]
      [S] 400 NNTP Service temporarily unavailable
      [Server closes connection.]
5.2.  CAPABILITIES
5.2.1.  Usage
   This command is mandatory.
   Syntax
     CAPABILITIES [keyword]
   Responses
     101    Capability list follows (multi-line)
   Parameters
     keyword    additional feature, see description
5.2.2.  Description
   The CAPABILITIES command allows a client to determine the
   capabilities of the server at any given time.
   This command MAY be issued at any time; the server MUST NOT require
   it to be issued in order to make use of any capability.  The response
   generated by this command MAY change during a session because of
   other state information (which, in turn, may be changed by the
   effects of other commands or by external events).  An NNTP client is
   only able to get the current and correct information concerning
   available capabilities at any point during a session by issuing a
   CAPABILITIES command at that point of that session and processing the
   response.
   The capability list is returned as a multi-line data block following
   the 101 response code.  Each capability is described by a separate
   capability line.  The server MUST NOT list the same capability twice
   in the response, even with different arguments.  Except that the
   VERSION capability MUST be the first line, the order in which the
   capability lines appears is not significant; the server need not even
   consistently return the same order.
   While some capabilities are likely to be always available or never
   available, others (notably extensions) will appear and disappear
   depending on server state changes within the session or on external
   events between sessions.  An NNTP client MAY cache the results of
   this command, but MUST NOT rely on the correctness of any cached
   results, whether from earlier in this session or from a previous
   session, MUST cope gracefully with the cached status being out of
   date, and SHOULD (if caching results) provide a way to force the
   cached information to be refreshed.  Furthermore, a client MUST NOT
   use cached results in relation to security, privacy, and
   authentication extensions.  See Section 12.6 for further discussion
   of this topic.
   The keyword argument is not used by this specification.  It is
   provided so that extensions or revisions to this specification can
   include extra features for this command without requiring the
   CAPABILITIES command to be used twice (once to determine if the extra
   features are available, and a second time to make use of them).  If
   the server does not recognise the argument (and it is a keyword), it
   MUST respond with the 101 response code as if the argument had been
   omitted.  If an argument is provided that the server does recognise,
   it MAY use the 101 response code or MAY use some other response code
   (which will be defined in the specification of that feature).  If the
   argument is not a keyword, the 501 generic response code MUST be
   returned.  The server MUST NOT generate any other response code to
   the CAPABILITIES command.
5.2.3.  Examples
   Example of a minimal response (a read-only server):
      [C] CAPABILITIES
      [S] 101 Capability list:
      [S] VERSION 2
      [S] READER
      [S] LIST ACTIVE NEWSGROUPS
      [S] .
   Example of a response from a server that has a range of facilities
   and that also describes itself:
      [C] CAPABILITIES
      [S] 101 Capability list:
      [S] VERSION 2
      [S] READER
      [S] IHAVE
      [S] POST
      [S] NEWNEWS
      [S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES OVERVIEW.FMT
      [S] IMPLEMENTATION INN 4.2 2004-12-25
      [S] OVER MSGID
      [S] STREAMING
      [S] XSECRET
      [S] .
   Example of a server that supports more than one version of NNTP:
      [C] CAPABILITIES
      [S] 101 Capability list:
      [S] VERSION 2 3
      [S] READER
      [S] LIST ACTIVE NEWSGROUPS
      [S] .
   Example of a client attempting to use a feature of the CAPABILITIES
   command that the server does not support:
      [C] CAPABILITIES AUTOUPDATE
      [S] 101 Capability list:
      [S] VERSION 2
      [S] READER
      [S] IHAVE
      [S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT HEADERS
      [S] OVER MSGID
      [S] HDR
      [S] NEWNEWS
      [S] .
5.3.  MODE READER
5.3.1.  Usage
   Indicating capability: MODE-READER
   This command MUST NOT be pipelined.
   Syntax
     MODE READER
   Responses
     200    Posting allowed
     201    Posting prohibited
     502    Reading service permanently unavailable [1]
   [1] Following a 502 response the server MUST immediately close the
       connection.
5.3.2.  Description
   The MODE READER command instructs a mode-switching server to switch
   modes, as described in Section 3.4.2.
   If the server is mode-switching, it switches from its transit mode to
   its reader mode, indicating this by changing the capability list
   accordingly.  It MUST then return a 200 or 201 response with the same
   meaning as for the initial greeting (as described in Section 5.1.1).
   Note that the response need not be the same as that presented during
   the initial greeting.  The client MUST NOT issue MODE READER more
   than once in a session or after any security or privacy commands are
   issued.  When the MODE READER command is issued, the server MAY reset
   its state to that immediately after the initial connection before
   switching mode.
   If the server is not mode-switching, then the following apply:
   o  If it advertises the READER capability, it MUST return a 200 or
      201 response with the same meaning as for the initial greeting; in
      this case, the command MUST NOT affect the server state in any
      way.
   o  If it does not advertise the READER capability, it MUST return a
      502 response and then immediately close the connection.
5.3.3.  Examples
   Example of use of the MODE READER command on a transit-only server
   (which therefore does not providing reading facilities):
      [C] CAPABILITIES
      [S] 101 Capability list:
      [S] VERSION 2
      [S] IHAVE
      [S] .
      [C] MODE READER
      [S] 502 Transit service only
      [Server closes connection.]
   Example of use of the MODE READER command on a server that provides
   reading facilities:
      [C] CAPABILITIES
      [S] 101 Capability list:
      [S] VERSION 2
      [S] READER
      [S] LIST ACTIVE NEWSGROUPS
      [S] .
      [C] MODE READER
      [S] 200 Reader mode, posting permitted
      [C] IHAVE <i.am.an.article.you.have@example.com>
      [S] 500 Permission denied
      [C] GROUP misc.test
      [S] 211 1234 3000234 3002322 misc.test
   Note that in both of these situations, the client SHOULD NOT use MODE
   READER.
   Example of use of the MODE READER command on a mode-switching server:
      [C] CAPABILITIES
      [S] 101 Capability list:
      [S] VERSION 2
      [S] IHAVE
      [S] MODE-READER
      [S] .
      [C] MODE READER
      [S] 200 Reader mode, posting permitted
      [C] CAPABILITIES
      [S] 101 Capability list:
      [S] VERSION 2
      [S] READER
      [S] NEWNEWS
      [S] LIST ACTIVE NEWSGROUPS
      [S] STARTTLS
      [S] .
   In this case, the server offers (but does not require) TLS privacy in
   its reading mode but not in its transit mode.
   Example of use of the MODE READER command where the client is not
   permitted to post:
      [C] MODE READER
      [S] 201 NNTP Service Ready, posting prohibited
5.4.  QUIT
5.4.1.  Usage
   This command is mandatory.
   Syntax
     QUIT
   Responses
     205    Connection closing
5.4.2.  Description
   The client uses the QUIT command to terminate the session.  The
   server MUST acknowledge the QUIT command and then close the
   connection to the client.  This is the preferred method for a client
   to indicate that it has finished all of its transactions with the
   NNTP server.
   If a client simply disconnects (or if the connection times out or
   some other fault occurs), the server MUST gracefully cease its
   attempts to service the client, disconnecting from its end if
   necessary.
   The server MUST NOT generate any response code to the QUIT command
   other than 205 or, if any arguments are provided, 501.
5.4.3.  Examples
      [C] QUIT
      [S] 205 closing connection
      [Server closes connection.]