NNTP Commands

NNTP Commands

NewsCache speaks NNTP to newsreaders (RFC 3977, with the common RFC 2980 extensions). This page lists the commands it answers, from the command table in src/NewsCache.cc. Commands are case-insensitive. HELP lists the commands available to the client.

Which commands a client may use depends on its access entry: without the read right the reading commands and LIST are not available, without the post right POST isn't, and before a required login most commands get 480. See Access and Authentication.

Session

Command	Reply	Notes
greeting	200 NewsCache <version>, accepting NNRP commands	201 ..., posting prohibited when the client may not post at that moment (also before a login that would add the post right); 400 too many users above MaxConnections; 502 for clients without access
CAPABILITIES	101	What the client may do now: VERSION 2, IMPLEMENTATION, and READER, HDR, OVER, LIST ACTIVE ACTIVE.TIMES EXTENSIONS HEADERS NEWSGROUPS OVERVIEW.FMT with the read right, POST with the post right, AUTHINFO USER before a login (AUTHINFO without USER on a plain connection whose entry has AuthRequiresTLS yes). Before a required login only AUTHINFO USER
MODE READER	200 or 201	Like the greeting. Accepted for compatibility (also MODE QUERY), also before the login; NewsCache is always a reader server
AUTHINFO USER name / AUTHINFO PASS password	381, then 281	Login, see Access and Authentication; a failed login 481, wrong order 482, after a login or without Authentication 502, on a plain connection with AuthRequiresTLS yes 483
DATE	111 yyyymmddhhmmss	Server time in UTC
HELP	100	The commands and their arguments
QUIT	205

Groups

Command	Reply	Notes
GROUP name	211 count first last name	411 only for a group that doesn't exist; 403 when the upstream server fails for a group the spool doesn't know yet; 480/502 if the client may not read it
LISTGROUP [name [range]]	211 count first last name, then the numbers	Requests adaptive ranges upstream and passes each list on as it arrives; see Caching and Large Groups. The read check comes before the group is selected. 411/403 as for GROUP; without a name, 412 when no group is selected or the current group no longer exists
LIST [ACTIVE [wildmat]]	215	Groups in the client's List; a wildmat only narrows it
LIST ACTIVE.TIMES [wildmat]	215	Local first-seen times, not upstream creation times; the creator is news
LIST NEWSGROUPS [wildmat]	215	Descriptions from SpoolDirectory/.newsgroups, which you create yourself; only groups in the client's List (and matching the wildmat)
LIST OVERVIEW.FMT	215	NewsCache's overview format; byte and line counts are :bytes and :lines
LIST HEADERS [MSGID|RANGE]	215	Fields HDR can return (below)
LIST EXTENSIONS	202	Old-style extension list (over, pat, authinfo user)
NEWGROUPS date time [GMT]	231	Groups first seen by NewsCache since then, in LIST ACTIVE format (group high low status); this is not the upstream creation time

Articles

range is n, n- or n-m. Article numbers are 64-bit; a number with trailing characters or one that doesn't fit gets 501.

Command	Reply	Notes
ARTICLE, HEAD, BODY [n|<id>]	220/221/222	423 no such number, 430 no such message-ID, 420 no current article, 412 no group; 403 when the upstream server fails
STAT [n|<id>]	223 n <message-id>	423 for a missing number; a successful STAT n makes it the current article
NEXT, LAST	223	421/422 at the end or start of the group
OVER [range], XOVER [range]	224	Overview records; OVER returns 423 for an empty range, while XOVER returns an empty 224 list. Both return 420 without a range when there is no current article. OVER <message-id> is unsupported and returns 503
HDR field [range|<id>]	225	See below
XHDR header [range|<id>]	221	n value lines, or <id> value; (none) for a missing header. XHDR Lines gives the number of body lines, as the overview does, also for articles with a Lines header. 420 without a range when there is no current article
XPAT header range|<id> pattern...	221	The XHDR lines whose value matches the wildmat pattern (several pattern words are joined with spaces)
POST	340, then 240	After the article only 240 or 441: 441 for an invalid article, an invalid Newsgroups header, a group not in PostTo, an article larger than MaxPostSize or cut off before the final ., and a post that failed. Without the post right, POST itself gets 480 if a login could add it, otherwise 440

By message-ID, articles come from the upstream server, or from the spool with History on (see Caching and Large Groups). In both cases the client must be allowed to read at least one of the article's groups, or it gets 480/502.

Error replies

Reply	When
500 What?	Unknown command
501	Wrong syntax; 501 Line too long for a command line of more than about 1020 characters or 256 words (the session goes on); 501 invalid message-id for a message-ID argument that RFC 3977 doesn't allow; 501 NUL in command
400	The session ends: service timed out! after ClientTimeout, service discontinued when the daemon stops, service discontinued (max passwords retries) after the third failed login, service not available when the spool can't be opened
480 / 502 / 440	Not allowed (440 for POST); see Access and Authentication
412	No group selected, or the current group no longer exists (412 current group no longer exists)
420	No current article
403	The upstream server failed (403 upstream failure for requests by message-ID), or an internal fault (403 internal error, 403 operation failed, 403 spool database damaged, try again)

Up to 1.3.22 the internal faults and upstream failures answered 503, an article by number that the upstream server failed to send 423, a current group that couldn't be opened 412, and one that no longer exists 411. In RFC 3977, 503 means "feature not supported"; NewsCache uses it for unsupported forms such as OVER by message-ID and HDR fields it can't serve. If an error interrupts a multi-line reply after it has begun, NewsCache closes the connection rather than ending the list as if it were complete.

HDR and LIST HEADERS (RFC 3977)

• By number (a range, or the current article), HDR reads the overview: Subject, From, Date, Message-ID, References, Xref, and the metadata :bytes and :lines. Other headers get 503, as the RFC asks, rather than an empty result. HDR Lines gets 503 too: the overview's line count is metadata, and HDR must return the article's own header.
• By message-ID it fetches the article, so every header is available, plus :bytes.
• An article without the header gets a line with an empty value; a range with no articles gets 423.

LIST HEADERS MSGID answers : (any header) and :bytes; LIST HEADERS RANGE the overview headers, :bytes and :lines; without an argument, what both forms have.

XHDR and XPAT

XHDR and XPAT (RFC 2980) see the overview fields of every article and all headers of articles stored in the spool. The message-ID forms need no selected group.

Debugging

Command	Notes
XDEBUG help	Lists the subcommands
XDEBUG dump authorization	The client's access entry as NewsCache sees it (after a login: with the added rights)
XDEBUG dump configuration	The configuration, like newscache -p (upstream passwords hidden)

XDEBUG needs the debug right. It shows the configuration, so give it only to administrators. The replies of XDEBUG help and XDEBUG dump begin with 100; XDEBUG dump with an unknown argument gets 501. The dumps end their lines with CRLF like every other reply (up to 1.3.22 with a bare LF, which strict clients refuse).

Not supported

• IHAVE, CHECK, TAKETHIS (NewsCache is a reader cache, not a transit server), NEWNEWS, XGTITLE.
• Client-side STARTTLS on the plain NNTP port. Implicit TLS from the first byte is supported; see TLS for Clients.
• COMPRESS.

Unknown commands get 500 What?.