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	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 HEADERS NEWSGROUPS OVERVIEW.FMT with the read right, POST with the post right, AUTHINFO USER before a login
MODE READER	200	Accepted for compatibility (also MODE QUERY); NewsCache is always a reader server
AUTHINFO USER name / AUTHINFO PASS password	381, then 281	Login, see Access and Authentication; wrong order 482
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 no such group; 480/502 if the client may not read it
LISTGROUP [name [range]]	211 count first last name, then the numbers	Passes the upstream server's list on as it arrives; the read check comes before the group is selected
LIST [ACTIVE [wildmat]]	215	Groups in the client's List
LIST ACTIVE.TIMES [wildmat]	215	Creation times
LIST NEWSGROUPS	215	Descriptions from SpoolDirectory/.newsgroups, which you create yourself
LIST OVERVIEW.FMT	215	NewsCache's overview format
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] [wildmat]	231	Groups created since then

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
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
HDR field [range|<id>]	225	See below
XHDR header [range|<id>]	221	n value lines, or <id> value; (none) for a missing header
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	441 invalid article or a group not in PostTo; 440 posting not allowed

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.

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.

Not supported

• IHAVE, CHECK, TAKETHIS (NewsCache is a reader cache, not a transit server), NEWNEWS, XGTITLE.
• TLS for clients (STARTTLS from the client side); use a TLS proxy in front of NewsCache, see Upstream Servers and TLS.
• COMPRESS.

Unknown commands get 500 What?.