Syntax10.Scn.FntParcElemsAlloc Syntax16.Scn.Fnt Syntax12.Scn.FntSyntax8.Scn.Fnt! Z Syntax10b.Scn.Fnt LinkElemsAlloc*N *R*v *A*L*Z+*"*§!**&MarkElemsAllocNP[StyleElemsAlloc Normal[*6 *LRUvwFirstIndented1A# NormalDSyntax10m.Scn.FntwFirstIndented1Syntax10i.Scn.Fnt NormalwFirstIndented1 y Normal)LSg   § eFirstIndent1?T[ v oe     +{P Z  Z+ Z &{ .;€ٓ ௛ c9TableElemsAlloc#Syntax10.Scn.Fnt/columns "llll" /table key valid values default remark HeaderLength ALL, NORMAL, SHORT NORMAL length of shown header StandardFont Oberon Font Name Syntax10.Scn.Fnt font of article QuotedFont Oberon Font Name Syntax10i.Scn.Fnt font of quotations in article KeyWordFont Oberon Font Name Syntax10b.Scn.Fnt font of key words in article StdFile Oberon File Name Client.News standard text to work with Signature Oberon File Name Signature.Text appended to text before posting AllArticles TRUE, FALSE FALSE show all articles / only new ones ThreadArticles TRUE, FALSE TRUE show articles in hierachical order ShowFromEntry TRUE, FALSE FALSE show From entry in article elems UseConnection TRUE, FALSE TRUE enables / disables offline reading ReplyTo Oberon String "n@o.o.n.e" address a reply should be sent to From Oberon String "n@o.o.n.e" e-mail of the sender Organization Oberon String "NONE" name of organization StdHost Oberon String "news.uni-linz.ac.at" standard host StdDir Oberon String "" directory to store files to / read files from StdPort INTEGER 119 port, the client tries to connect to MaxArticles INTEGER 100 num. of article infos processed at a time ResponseTimeout INTEGER 50 (seconds) ConnectTimeout INTEGER 10000 (milliseconds) _b Z   Z  %Η;T    * < --* 8 ,  !# *(8 $-#!8 3,(.5#&.)0:>45IC'R:7~"oZ% PL5#&)]+1,.)R  Z  4b Z   +  %0,' 1I'&*  %$(:2/LIKA_A_IcQb$+#Z<:P9ENHNPRXG(A++ZN9CNCNKRSG$@.iQ,420264 #/7'& '."8!i54JU6GKGKOOWDw Zw $T7J0rqats'%&A Z  6GCourier10.Scn.Fnt Z ? Courier8.Scn.Fnt* K *  Zr   Z k !_wШ   +  Z  L Courier10b.Scn.Fntw oNetNews A NNTP Client For Oberon by Hamader Peter '97 RELEASE 1.2  Contents Introduction Changes Installation The graphical user interface Posting Files the NetNews distribution consists of Fomat of the file NetNews.Profile Interface description of NetNews Interface description of NNTP Interface Description of NetNewsElems Introduction NetNews is a client for the retrieval and sending of usenet news articles in compliance to [RFC977] and [RFC1036]. See these papers for any further detail on the NNTP protocol and header format, respectively. NetNews is equiped with an intuitive graphical user interface. A sample working environment is included with this distribution called 'MyClient.News'. Changes + Release 1.0 to 1.1: - ArticleElems / GroupElems / ServerElems can be switched by clicking between a logical pair - handling of old article was completely rewritten + Release 1.1 to 1.2: - articles are no longer inserted twice or more often into the hierarchy but LinkElems are inserted instead to indicate a reference Installation + Add the NetNews directory to your path + Set the standard directory in NetNews.Profile (see below) + Open NetNews.Tool + Open the file NNTP.Mod and switch the VersionElem at the top to the computer system you use. Save the file. + Open the file NetNewsElems.Mod and switch the VersionElem at the top to whether you installed the web browser or not (default is web browser installed). Save the file. + Compile the client using the command from NetNews.Tool + Edit the file NetNews.Profile to your needs. See APPENDIX for a description of the file format and possible options + Start the news client by executing the command NetNews.Open MyClient.News GUI - The graphical user interface  The GUI is built on text elements. The NNE's (NetNewsElems) are derived from FoldElems. A NNE logically consists of two parts, a left one which contains all the information and a right one which acts like a closing brace. It is vitally important NOT to erase one part or to exchange a right by a left one, otherwhise the behaviour of the NNE is unpredictable. There are three kinds of NNE: + ServerElems + GroupElems + ArticleElems As only ServerElems contain a logical connection to a NNTP host, it is necessary to have GroupElems or ArticleElems embraced by an open ServerElem. It is not possible to retrieve or send articles without an open ServerElem. Every attempt would lead to a trap. All NNE's are opened and closed by simply clicking with the middle mouse button on either the left or the right element of a logical pair. CHANGES (version 1.0x to version 1.1): the NNE's can also be opened (closed) by clicking BETWEEN the left and the right element. ServerElems or GroupElems may be inserted into a text by the commands NetNews.InsertServerElem and NetNews.InsertGroupElem respectively, after having selected a text which serves as a name to the text elem and setting the caret to the insert position. When inserting a ServerElem, an optional port number may be specified separated from the name by a blank, overiding the default port which is set to 119 according to [RFC977]. The names of ServerElems as well as GroupElems (also the port number of ServerElems) may be changed after the insertion by simply editing the text immediately right to the left part of a NNE pair. CAUTION: + When editing the name of a ServerElem the GroupElems associated with the ServerElem whose name and/or port was altered are erased. + When editing the name of a GroupElem the persistent articles associated with the GroupElem whose name was altered are erased. There are three kinds of ArticleElems: + new articles + persistent articles + old (read) articles The text between a logical ArticleElem pair shows the subject of the article. It doesn't make sense to alter this text. New articles have to be fetched from the NNTP host. Old ones have already been fetched and their contents are stored in their buffer. Clicking on an old article with the middle mouse button causes the state of the article to change to unread again. It is possible to mark articles as persistent with the NetNews.MakePersistent command. This means that the article associated with the ArticleElem is fetched if necessary and stored locally. To display an article simply click on it with the middle mouse button. CAUTION: As NNE's are text elements and are stored within a text, persistent articles as well as new inserted ServerElems and GroupElems are only stored if the text which contains them is stored. If persistent articles are marked as read, the text has also to be stored before closing, otherwhise the persistent articles are not deleted and shown again the next time the text is opened. It is recommended that texts containing NNE's be opened with the NetNews.Open command, which adds appropriate commands to the menu bar of the viewer. NOTE: status messages are written to System.Log. Posting Posting means sending an article to a NNTP host. After opening a connection, a status response is displayed, indicating whether posting to this host is allowed or prohibited. If it is allowed in general, it may still be not allowed for certain groups. So, if you are allowed to post, prepare the article you would like to send. You may insert at the beginning a set of header entries, most important a subject entry. The header entries have to be formatted as follows: Header = Key ":" Value CR. Key = Letter {Letter | Digit | "-"}. Value = {Char}. context assertion: ORD(Char) >= 32 NOTE: Entries inserted in the text to be posted override the standard settings from the file NetNews.Profile To send the article, select the GroupElem of the group you'd like to send the article to, mark the viewer containing the article with the star shaped pointer and select NetNews.Post from the menu item NetNews. A status response will indicate whether posting was successful or not. NOTE: Prior to posting, a text called a signiture may be appended automatically to the article; see the de- scription of the file NetNews.Profiel for further detail APPENDIX NetNews NetNews.Close [*] close the current or the star marked viewer, respectively CHANGES (version 1.0x to version 1.1): text is saved automatically after closing NetNews.Open [^] Name open a text named Name (may be taken from the most recent selection) NetNews.MarkAsRead usage: first select ArticleElems, then issue the command; the selected ArticleElems will be marked as read NetNews.MakePersistent usage: first select ArticleElems, then issue the command; the selected ArticleElems will be fetched and made persistent NetNews.NextArticles usage: first select open GroupElem, then issue the command; the next few of articles will be fetched and shown NOTE: the value of the entry MaxArticles in the file specifies how many articles will be fetched at one go NetNews.AllGroups usage: first select ServerElem, then issue the command; a viewer will be opened containing all groups of the server with additional information NetNews.InsertGroup usage: select the name of the group to be inserted; select the insert position, then issue the command; the GroupElem will be inserted NetNews.InsertServer usage: select the name of the server to be inserted; select the insert position, then issue the command; the GroupElem will be inserted NetNews.Post usage: mark the viewer containing the text to post with the star shaped pointer and select the GroupElem you wish to post the article to, then issue the command; the article is sent if allowed NetNews.NewArticle usage: mark the ArticleElem you want to reply to, then issue the command; the article is fetched, prepared as a response, and shown in a viewer. Edit the article to your needs and send it with the NetNews.Post command. If you mark no ArticleElem, an empty article is prepared for posting NetNews.UpdatePreferences usage: edit the file NetNews.Profile, then issue the command; the new preferences are loaded and used from now on NetNews.ToggleConnectionUsage usage: simply issue this command toggles between offline and online mode (use offline mode to read persistent articles without establishing a connection to the news server) NOTE: close GroupElems / ServerElems prior to switching between offline / online mode  Files the NetNews distribution consists of NNTP.Mod: implements the NNTP protocol NetNewsElems.Mod: implements the GUI of the netnews client NetNews.Mod: exports the commands for the netnews client NetNews.Menu.Text: the menu for the netnews client NetNews.Tool the tool for the netnews client MyClient.News a sample working environment NetNews.Profile the initialization file of the netnews client NetNews.Text this documentation NetNews.Profile File Format in EBNF: File = {(NameEntry | StringEntry | IntEntry) CR}. NameEntry = NameKey "=" OberonName. StringEntry = StringKey "=" OberonString. IntEntry = IntKey "=" INTEGER. NameKey = "HeaderLength" | "StandardFont" | "QuotedFont" | "KeyWordFont" | "Signature" | "StdFile" | "AllArticles" | "ThreadNews" | "ShowFromEntry". StringKey = "ReplyTo" | "From" | "Organization" | "StdHost" | "StdDir". IntKey = "StdPort" | "MaxArticles" | "ResponseTimeout" | "ConnectTimeout".  NOTE: the entries in NetNews.Profile are case sensitive, meaning that 'TRUE' is NOT equal to 'TrUe' NOTE: ThreadArticles, AllArticles as well as ShowFromEntry are applied to fresh inserted articles only NNTP DEFINITION NNTP; IMPORT Texts, Oberon; CONST (* valid requests; for a description of the syntax of the requests see [RFC977] *) article = 0; (* fetch article + header *) body = 1; (* fetch body of article *) group = 2; (* change current group *) head = 3; (* fetch head of article *) help = 4; (* send info about supported requests *) last = 5; (* set current article pointer to the last in the group *) list = 6; (* list all groups of the current server *) newGroups = 7; (* list new groups of the current server *) newNews = 8; (* list new news of the current group *) next = 9; (* setr current article pointer to the next article *) post = 10; (* post an article to the current group *) quit = 11; (* close connection *) stat = 12; (* get info about an article *) connect = 13; (* trying to connect to a host *) xover = 14; (* get info about a range of articles *) sResponseOnly = {2, 5, 9, 11, 12, 13}; (* req. to which a status response only is returned *) (* states of a request *) done = 6; (* request is done *) prepareArticle = 5; (* preparing article to be sent *) readPostResponse = 3; (* reading the response to a try to post *) readStatusResponse = 1; (* reading the status response *) readTextResponse = 2; (* reading the text response *) sendArticle = 4; (* sending the article *) sendRequest = 0; (* sending the request *) reqLen = 511; (* length of a request string (including closing 0X) *) stdConnectTimeout = 10000; (* standard connection timeout in milliseconds *) stdResponseTimeout = 50; (* standard response timeout in seconds *) stdPort = 119 (* standard port *) TYPE Buffer = POINTER TO BufferDesc; (* buffer, data is written to / read from *) BufferDesc = RECORD PROCEDURE (b: Buffer) Reset; (* reset buffer to length zero *) END ; Data = POINTER TO DataDesc; (* additional data which may be needed by *) DataDesc = RECORD END ; (* call back procedures *) Request = POINTER TO RequestDesc; RequestDesc = RECORD (TaskDesc) sResponse-: ARRAY 511 OF CHAR; tmpText-: Texts.Text; (* text a text response is stored to *) op-, state-: SHORTINT; (* operation and current state of operation *) data: Data; (* additional data *) END ; CallBackProc = PROCEDURE (req: Request) ; Connection = POINTER TO ConnectionDesc; ConnectionDesc = RECORD busy-: BOOLEAN; (* to determine whether the connection is busy or not *) buf-: Buffer; (* buffer, the transmitted data is temporarily stored to *) PROCEDURE (currC: Connection) CancelAllRequests; (* stops all requests and resets the buffer *) PROCEDURE (currC: Connection) Connect (data: Data; sh: CallBackProc); (* try to connect to the server associated with this 'currC'; NOTE: the server has to be set before using SetServer; ''data' is additional data which can be used by 'sh' which is called when the request is done *) PROCEDURE (currC: Connection) Init; (* initialize the connection; has to be called before using the connection *) PROCEDURE (currC: Connection) IsConnected (): BOOLEAN; (* determine whether a connection exists or not *) PROCEDURE (currC: Connection) Req (reqStr: ARRAY OF CHAR; tmpText: Texts.Text; data: Data; th, sh: CallBackProc); (* send a request to 'currC'; NOTE: a connection has to be opened before usage; 'reqStr' is the command which will be sent to the NNTP host;  'tmpText' is the text, a text response is written to or the article to be posted is read from, respectively; 'data' is additional data which may be used be the two call back procedures 'sh', 'th'; 'th' is the text call back procedure which is called, when a text response was returned by the NNTP host; 'sh' is the status call back procedure which is called, when a status response was returned by the NNTP host;*) PROCEDURE (currC: Connection) SetServer (host: ARRAY OF CHAR; port: INTEGER); (* set the hostname of 'currC' to 'host' and the port number to 'port' *) END ; VAR connectTimeout-: LONGINT; (* (milliseconds) currently set connect timeout *) responseTimeout-: LONGINT; (* (seconds) currently set respnose timeout *) PROCEDURE GetCode (c: ARRAY OF CHAR): INTEGER; (* extract a return code from a status response *) PROCEDURE Msg (s: ARRAY OF CHAR); (* write a message to Oberon.Log *) PROCEDURE SCallBackProc (req: Request); (* standard status call back procedure; appends the text of the response to Oberon.Log *) PROCEDURE SetConnectTimeout (n: LONGINT); (* set connection timeout (in milliseconds) *) PROCEDURE SetResponseTimeout (n: LONGINT); (* set the response timeout (in seconds) *) PROCEDURE TCallBackProc (req: Request); (* standard text callback procedure; appends the text response to Oberon.Log *) END NNTP. NetNewsElems NOTE: NetNewsElems is not designed or meant to be extended DEFINITION NetNewsElems; IMPORT FoldElems, Texts, Files, NNTP, Fonts, Display, Oberon; CONST  black = 15; (* colors of an ArticleElem *) green = 8; red = 7; new = 0; (* types of ArticleElems *) old = 1; persistent = 2; nameLen = 128; (* max. Length of a name *) numLen = 16; (* DEC(numLen) is max. number of digits *) refLen = 2048; (* max. Length of a reference list *) subjectLen = 256; (* max. Length of a subject *) colMode = {0, 1}; (* modes additional to the ones of FoldElems *) leftMode = {0, 3}; tempMode = {4, 5}; iniFile = "NetNews.Profile"; (* name of the initialization file *) xMailer = "NetNews for Oberon V1.0"; (* name / version of the news client *) normalHD = 0; (* medium length of header *) fullHD = 1; (* show all header contents *) shortHD = 2; (* show subject header line only *) TYPE Elem = POINTER TO ElemDesc; (* abstract base class of all NNE's *) ElemDesc = RECORD (FoldElems.ElemDesc) name-: String; (* name of the elem *) numTabs-: INTEGER; (* number of TAB's to the left of the element *) PROCEDURE (e: Elem) CanSwitch (): BOOLEAN; (* determines whether elem should be switched or not; abstract method *) PROCEDURE (e: Elem) Display (col, mode, x, y, displayMode: INTEGER); (* displays the elem 'e'; is called by the handler; abstract method *) PROCEDURE (e: Elem) HandleCopyMsg (VAR m: Texts.CopyMsg); (* handles the copy message for text elements; is called by the handler; abstract method *) PROCEDURE (e: Elem) HandleFileMsg (VAR m: Texts.FileMsg); (* handles the file message for text elements; is called by the handler; abstract method *) PROCEDURE (e: Elem) HandleIdentifyMsg (VAR m: Texts.IdentifyMsg); (* handles the identify message for text elements; is called by the handler; abstract method *) PROCEDURE (e: Elem) HandlePrepSwitchMsg (VAR m: FoldElems.PrepSwitchMsg); (* handles te PrepSwitchMsg implemented in FoldElems; is called by handler; abstract method *) PROCEDURE (e: Elem) Prepare; (* prepares the elem 'e' for display *) PROCEDURE (e: Elem) Switch; (* switches the elem 'e' *) END ; ArticleElem = POINTER TO ArticleElemDesc; ArticleElemDesc = RECORD PROCEDURE (e: ArticleElem) CanSwitch (): BOOLEAN; (* determines, whether the elem should be switched or not; is called by the handler *) PROCEDURE (e: ArticleElem) ChangeType (type: SHORTINT); (* change the type of 'e' to old, new or persistent *) PROCEDURE (e: ArticleElem) Display (col, mode, x, y, displayMode: INTEGER); (* displays the elem 'e'; is called by the handler *) PROCEDURE (e: ArticleElem) HandleCopyMsg (VAR m: Texts.CopyMsg); (* handles the copy message for text elements; is called by the handler *) PROCEDURE (e: ArticleElem) HandleFileMsg (VAR m: Texts.FileMsg); (* handles the file message for text elements; is called by the handler *) PROCEDURE (e: ArticleElem) HandleIdentifyMsg (VAR m: Texts.IdentifyMsg); (* handles the identify message for text elements; is called by the handler *) PROCEDURE (e: ArticleElem) HandlePrepSwitchMsg (VAR m: FoldElems.PrepSwitchMsg); (* prepares the elem 'e' for switching; is called by the handler *) PROCEDURE (e: ArticleElem) Init; (* initializes the elem 'e'; has to be called before usage *) PROCEDURE (e: ArticleElem) Prepare; (* prepares the elem 'e' for display *) END ; Data = POINTER TO DataDesc; DataDesc = RECORD (NNTP.DataDesc) elem: Elem; END ; GroupElem = POINTER TO GroupElemDesc; GroupElemDesc = RECORD noArticles-, firstArticle-, lastArticle-: LONGINT; PROCEDURE (e: GroupElem) CanSwitch (): BOOLEAN; (* determines, whether the elem should be switched or not; is called by the handler *) PROCEDURE (e: GroupElem) Display (col, mode, x, y, displayMode: INTEGER); (* displays the elem 'e'; is called by the handler *) PROCEDURE (e: GroupElem) HandleCopyMsg (VAR m: Texts.CopyMsg); (* handles the copy message for text elements; is called by the handler *) PROCEDURE (e: GroupElem) HandleFileMsg (VAR m: Texts.FileMsg); (* handles the file message for text elements; is called by the handler *) PROCEDURE (e: GroupElem) HandleIdentifyMsg (VAR m: Texts.IdentifyMsg); (* handles the identify message for text elements; is called by the handler *) PROCEDURE (e: GroupElem) HandlePrepSwitchMsg (VAR m: FoldElems.PrepSwitchMsg); (* prepares the elem 'e' for switching; is called by the handler *) PROCEDURE (e: GroupElem) Init; (* initializes the elem 'e'; has to be called before usage *) PROCEDURE (e: GroupElem) NextArticles; (* fetches the information of the next 'pref.server.maxArticles' articles and display the articles *) END ; Preferences = POINTER TO PreferencesDesc; PreferencesDesc = RECORD (* stores the preferences of the client *) allArticles-: BOOLEAN; (* whether to show all articles or only the new *) server-: RECORD stdHost-: ARRAY 64 OF CHAR; (* standard host; needed by the news Scheme *) stdPort-, (* standard port *) maxArticles-: INTEGER; (* number of article infos to fetch at a time *) END ; article-: RECORD headerLen-: SHORTINT; (* length of header (normalHD, shortHD, fullHD) *) font-, (* font of a displayed article *) keyWordFnt-, (* font of keywords in a displayed article *) quotedFnt-: Fonts.Font; (* font used for quotations in a displayed article *) END ; posting-: RECORD from-, (* by whom was the article posted *) replyTo-, (* where should a reply be sent to *) organization-, (* what is the organization of the sender *) signature-: ARRAY 256 OF CHAR; (* name of a text file to be appended automatically *) END ; (* before posting an article *) END ; ServerElem = POINTER TO ServerElemDesc; ServerElemDesc = RECORD conn-: NNTP.Connection; (* connection associated with the ServerElem *) PROCEDURE (e: ServerElem) CanSwitch (): BOOLEAN; (* returns whether 'e' can be switched (i.e. if e.conn is NOT busy) *) PROCEDURE (e: ServerElem) Display (col, mode, x, y, displayMode: INTEGER); (* displays the elem 'e'; is called by the handler *) PROCEDURE (e: ServerElem) HandleCopyMsg (VAR m: Texts.CopyMsg); (* handles the copy message for text elements; is called by the handler *) PROCEDURE (e: ServerElem) HandleFileMsg (VAR m: Texts.FileMsg); (* handles the file message for text elements; is called by the handler *) PROCEDURE (e: ServerElem) HandleIdentifyMsg (VAR m: Texts.IdentifyMsg); (* handles the identify message for text elements; is called by the handler *) PROCEDURE (e: ServerElem) HandlePrepSwitchMsg (VAR m: FoldElems.PrepSwitchMsg); (* prepares the elem 'e' for switching; is called by the handler *) END ; String = POINTER TO ARRAY OF CHAR; (* dynamically allocatable ARRAY OF CHAR *) VAR pref-: Preferences; (* current preferences *)  PROCEDURE ComputeTabNum (e: Elem); (* computes the number of TAB's to the left of 'e' and stores it in e.numTabs *) PROCEDURE Copy (src: ARRAY OF CHAR; VAR dst: String); (* copies src to a dynamically allocated String with minimal length *) PROCEDURE GetServerElem (e: Elem): ServerElem; (* returns the left ServerElem of the logical NNE pair which embrace 'e'; if there is none, NIL is returned *) PROCEDURE InsertArticleElem1 (t: Texts.Text; pos: LONGINT; name, subject, references: ARRAY OF CHAR; num: LONGINT; numTabs: INTEGER; type: SHORTINT; valid: BOOLEAN); (* inserts an ArticleElem pair with Message-ID 'nam', subject 'subject', references 'references', article number 'num', and type 'type' in text 't' at position 'pos' with 'numTabs' TAB's in front of it; valid is for internal use only *) PROCEDURE InsertArticleElem2 (t: Texts.Text; pos: LONGINT; numTabs: INTEGER; e: ArticleElem; valid: BOOLEAN); (* inserts an ArticleElem pair with 'e' as left ArticleElem into text 't' at position 'pos' with 'numTabs' TAB's in front of it; valid is for internal use only *) PROCEDURE InsertGroupElem (t: Texts.Text; pos: LONGINT; numTabs: INTEGER; name: ARRAY OF CHAR); (* inserts a GroupElem pair with name 'name into text 't' at position 'pos' with 'numTabs' TAB's in fromt of it *) PROCEDURE InsertServerElem (t: Texts.Text; pos: LONGINT; numTabs: INTEGER; host: ARRAY OF CHAR; port: INTEGER); (* inserts a ServerElem with name 'host' and port number 'port' into text 't' at position 'pos' with 'numTabs' TAB's in front of it *) PROCEDURE NewArticleElem; (* used for loading ArticleElems *) PROCEDURE NewGroupElem; (* used for loading GroupElems *) PROCEDURE NewServerElem; (* used for loading ServerElems *) PROCEDURE UpdatePreferences; (* loads new preferences from file NetNews.Profile to pref *) END NetNewsElem. RFC977 (written by Brian Kantor (U.C. San Diego), Phil Lapsley (U.C. Berkeley); shortened and extended (by the XOVER command and protocol in EBNF) by Hamader Peter) NOTE: by NetNews unimplemented commands (IHAVE, SLAVE) are not mentioned here 1. the NNTP Protocol in EBNF Session = Connect {Post | Other} Close. Other = Request StatusResponse [TextResponse]. Post = Request StatusResponse [Article StatusResponse]. Connect = "CONNECT" Server [Port]. -- Default-Port: 119 Close = "CLOSE". Request = Command CR-LF. CA: |Request| <= 512 Response = StatusResponse | TextResponse. Command = CommandWord ParamList. CA: IF CommandWord IN {"ARTICLE", "BODY", "STAT", "HEAD"} THEN ParamSeq = "<" MessageID ">" | [Number] ELSIF CommandWord = "GROUP" THEN ParamSeq = Group ELSIF CommandWord IN {"HELP", "LAST", "LIST", "NEXT", "POST", "QUIT"} THEN ParamSeq = empty ELSIF CommandWord = "NEWGROUPS" THEN ParamSeq = Date Time [GMT] ELSIF CommandWord = "NEWNEWS" THEN ParamSeq = NewsGroups Date Time [GMT] ["<" Distribution ">"] ELSIF CommandWord = "XOVER" THEN ParamSeq = Number "-" Number ENDParamList = {WhiteSpace {WhiteSpace} Param}. CommandWord = "ARTICLE" | "BODY" | "STAT" | "HEAD" | "HELP" | "GROUP" | "LAST" | "LIST" | "POST" | "NEWGROUPS" | "NEWNEWS" | "NEXT" | "QUIT" | "XOVER". WhiteSpace = SPACE | TAB. StatusResponse = Success Digit Digit {SPACE Param}. Success = "1" | _ | "5". TextResponse = {Line CR-LF} "." CR-LF. Line = Char {Char}. CA: Line must not contain CR-LF Param = "<" MessageID ">" | Number. MessageID = Unique @ Name. Date = YYMMDD. Time = HHMMSS. Distribution = DistributionGroup {"," DistributionGroup}. NewsGroups = Group {"," Group}. NOTE: CA = context assertion 2. The NNTP Specification 2.1. Overview The news server specified by this document uses a stream connection (such as TCP) and SMTP-like commands and responses. It is designed to accept connections from hosts, and to provide a simple interface to the news database. This server is only an interface between programs and the news databases. It does not perform any user interaction or presentation- level functions. These "user-friendly" functions are better left to the client programs, which have a better understanding of the environment in which they are operating. When used via Internet TCP, the contact port assigned for this service is 119. 2.2. Character Codes Commands and replies are composed of characters from the ASCII character set. When the transport service provides an 8-bit byte (octet) transmission channel, each 7-bit character is transmitted right justified in an octet with the high order bit cleared to zero. 2.3. Commands Commands consist of a command word, which in some cases may be followed by a parameter. Commands with parameters must separate the parameters from each other and from the command by one or more space or tab characters. Command lines must be complete with all required parameters, and may not contain more than one command. Commands and command parameters are not case sensitive. That is, a command or parameter word may be upper case, lower case, or any mixture of upper and lower case. Each command line must be terminated by a CR-LF (Carriage Return - Line Feed) pair. Command lines shall not exceed 512 characters in length, counting all characters including spaces, separators, punctuation, and the trailing CR-LF (thus there are 510 characters maximum allowed for the command and its parameters). There is no provision for continuation command lines. 2.4. Responses Responses are of two kinds, textual and status. 2.4.1. Text Responses Text is sent only after a numeric status response line has been sent that indicates that text will follow. Text is sent as a series of successive lines of textual matter, each terminated with CR-LF pair. A single line containing only a period (.) is sent to indicate the end of the text (i.e., the server will send a CR-LF pair at the end of the last line of text, a period, and another CR-LF pair). If the text contained a period as the first character of the text line in the original, that first period is doubled. Therefore, the client must examine the first character of each line received, and for those beginning with a period, determine either that this is the end of the text or whether to collapse the doubled period to a single one. The intention is that text messages will usually be displayed on the user's terminal whereas command/status responses will be interpreted by the client program before any possible display is done. 2.4.2. Status Responses These are status reports from the server and indicate the response to the last command received from the client. Status response lines begin with a 3 digit numeric code which is sufficient to distinguish all responses. Some of these may herald the subsequent transmission of text. The first digit of the response broadly indicates the success, failure, or progress of the previous command. 1xx - Informative message 2xx - Command ok 3xx - Command ok so far, send the rest of it. 4xx - Command was correct, but couldn't be performed for some reason. 5xx - Command unimplemented, or incorrect, or a serious program error occurred. The next digit in the code indicates the function response category. x0x - Connection, setup, and miscellaneous messages x1x - Newsgroup selection x2x - Article selection x3x - Distribution functions x4x - Posting x8x - Nonstandard (private implementation) extensions x9x - Debugging output The exact response codes that should be expected from each command are detailed in the description of that command. In addition, below is listed a general set of response codes that may be received at any time. Certain status responses contain parameters such as numbers and names. The number and type of such parameters is fixed for each response code to simplify interpretation of the response. Parameters are separated from the numeric response code and from each other by a single space. All numeric parameters are decimal, and may have leading zeros. All string parameters begin after the separating space, and end before the following separating space or the CR-LF pair at the end of the line. (String parameters may not, therefore, contain spaces.) All text, if any, in the response which is not a parameter of the response must follow and be separated from the last parameter by a space. Also, note that the text following a response number may vary in different implementations of the server. The 3-digit numeric code should be used to determine what response was sent. Response codes not specified in this standard may be used for any installation-specific additional commands also not specified. These should be chosen to fit the pattern of x8x specified above. (Note that debugging is provided for explicitly in the x9x response codes.) The use of unspecified response codes for standard commands is prohibited. We have provided a response pattern x9x for debugging. Since much debugging output may be classed as "informative messages", we would expect, therefore, that responses 190 through 199 would be used for various debugging outputs. There is no requirement in this specification for debugging output, but if such is provided over the connected stream, it must use these response codes. If appropriate to a specific implementation, other x9x codes may be used for debugging. (An example might be to use e.g., 290 to acknowledge a remote debugging request.) 2.4.3. General Responses The following is a list of general response codes that may be sent by the NNTP server. These are not specific to any one command, but may be returned as the result of a connection, a failure, or some unusual condition. In general, 1xx codes may be ignored or displayed as desired; code 200 or 201 is sent upon initial connection to the NNTP server depending upon posting permission; code 400 will be sent when the NNTP server discontinues service (by operator request, for example); and 5xx codes indicate that the command could not be performed for some unusual reason. 100 help text 190 through 199 debug output 200 server ready - posting allowed 201 server ready - no posting allowed 400 service discontinued 500 command not recognized 501 command syntax error 502 access restriction or permission denied 503 program fault - command not performed 3. Command and Response Details On the following pages are descriptions of each command recognized by the NNTP server and the responses which will be returned by those commands. Each command is shown in upper case for clarity, although case is ignored in the interpretation of commands by the NNTP server. Any parameters are shown in lower case. A parameter shown in [square brackets] is optional. For example, [GMT] indicates that the triglyph GMT may present or omitted. Every command described in this section must be implemented by all NNTP servers. There is no prohibition against additional commands being added; however, it is recommended that any such unspecified command begin with the letter "X" to avoid conflict with later revisions of this specification. Implementors are reminded that such additional commands may not redefine specified status response codes. Using additional unspecified responses for standard commands is also prohibited. 3.1. The ARTICLE, BODY, HEAD, and STAT commands There are two forms to the ARTICLE command (and the related BODY, HEAD, and STAT commands), each using a different method of specifying which article is to be retrieved. When the ARTICLE command is followed by a message-id in angle brackets ("<" and ">"), the first form of the command is used; when a numeric parameter or no parameter is supplied, the second form is invoked. The text of the article is returned as a textual response, as described earlier in this document. The HEAD and BODY commands are identical to the ARTICLE command except that they respectively return only the header lines or text body of the article. The STAT command is similar to the ARTICLE command except that no text is returned. When selecting by message number within a group, the STAT command serves to set the current article pointer without sending text. The returned acknowledgement response will contain the message-id, which may be of some value. Using the STAT command to select by message-id is valid but of questionable value, since a selection by message-id does NOT alter the "current article pointer". 3.1.1. ARTICLE (selection by message-id) ARTICLE Display the header, a blank line, then the body (text) of the specified article. Message-id is the message id of an article as shown in that article's header. It is anticipated that the client will obtain the message-id from a list provided by the NEWNEWS command, from references contained within another article, or from the message-id provided in the response to some other commands. Please note that the internally-maintained "current article pointer" is NOT ALTERED by this command. This is both to facilitate the presentation of articles that may be referenced within an article being read, and because of the semantic difficulties of determining the proper sequence and membership of an article which may have been posted to more than one newsgroup. 3.1.2. ARTICLE (selection by number) ARTICLE [nnn] Displays the header, a blank line, then the body (text) of the current or specified article. The optional parameter nnn is the numeric id of an article in the current newsgroup and must be chosen from the range of articles provided when the newsgroup was selected. If it is omitted, the current article is assumed. The internally-maintained "current article pointer" is set by this command if a valid article number is specified. [the following applies to both forms of the article command.] A response indicating the current article number, a message-id string, and that text is to follow will be returned. The message-id string returned is an identification string contained within angle brackets ("<" and ">"), which is derived from the header of the article itself. The Message-ID header line (required by RFC850) from the article must be used to supply this information. If the message-id header line is missing from the article, a single digit "0" (zero) should be supplied within the angle brackets. Since the message-id field is unique with each article, it may be used by a news reading program to skip duplicate displays of articles that have been posted more than once, or to more than one newsgroup. 3.1.3. Responses 220 n article retrieved - head and body follow (n = article number, = message-id) 221 n article retrieved - head follows 222 n article retrieved - body follows 223 n article retrieved - request text separately 412 no newsgroup has been selected 420 no current article has been selected 423 no such article number in this group 430 no such article found 3.2. The GROUP command 3.2.1. GROUP GROUP ggg The required parameter ggg is the name of the newsgroup to be selected (e.g. "net.news"). A list of valid newsgroups may be obtained from the LIST command. The successful selection response will return the article numbers of the first and last articles in the group, and an estimate of the number of articles on file in the group. It is not necessary that the estimate be correct, although that is helpful; it must only be equal to or larger than the actual number of articles on file. (Some implementations will actually count the number of articles on file. Others will just subtract first article number from last to get an estimate.) When a valid group is selected by means of this command, the internally maintained "current article pointer" is set to the first article in the group. If an invalid group is specified, the previously selected group and article remain selected. If an empty newsgroup is selected, the "current article pointer" is in an indeterminate state and should not be used. Note that the name of the newsgroup is not case-dependent. It must otherwise match a newsgroup obtained from the LIST command or an error will result. 3.2.2. Responses 211 n f l s group selected (n = estimated number of articles in group, f = first article number in the group, l = last article number in the group, s = name of the group.) 411 no such news group 3.3. The HELP command 3.3.1. HELP HELP Provides a short summary of commands that are understood by this implementation of the server. The help text will be presented as a textual response, terminated by a single period on a line by itself. 3.3.2. Responses 100 help text follows 3.5.1. LAST LAST The internally maintained "current article pointer" is set to the previous article in the current newsgroup. If already positioned at the first article of the newsgroup, an error message is returned and the current article remains selected. The internally-maintained "current article pointer" is set by this command. A response indicating the current article number, and a message-id string will be returned. No text is sent in response to this command. 3.5.2. Responses 223 n a article retrieved - request text separately (n = article number, a = unique article id) 412 no newsgroup selected 420 no current article has been selected 422 no previous article in this group 3.6. The LIST command 3.6.1. LIST LIST Returns a list of valid newsgroups and associated information. Each newsgroup is sent as a line of text in the following format: group last first p where is the name of the newsgroup, is the number of the last known article currently in that newsgroup, is the number of the first article currently in the newsgroup, and

is either 'y' or 'n' indicating whether posting to this newsgroup is allowed ('y') or prohibited ('n'). The and fields will always be numeric. They may have leading zeros. If the field evaluates to less than the field, there are no articles currently on file in the newsgroup. Note that posting may still be prohibited to a client even though the LIST command indicates that posting is permitted to a particular newsgroup. See the POST command for an explanation of client prohibitions. The posting flag exists for each newsgroup because some newsgroups are moderated or are digests, and therefore cannot be posted to; that is, articles posted to them must be mailed to a moderator who will post them for the submitter. This is independent of the posting permission granted to a client by the NNTP server. Please note that an empty list (i.e., the text body returned by this command consists only of the terminating period) is a possible valid response, and indicates that there are currently no valid newsgroups. 3.6.2. Responses 215 list of newsgroups follows 3.7. The NEWGROUPS command 3.7.1. NEWGROUPS NEWGROUPS date time [GMT] [] A list of newsgroups created since will be listed in the same format as the LIST command. The date is sent as 6 digits in the format YYMMDD, where YY is the last two digits of the year, MM is the two digits of the month (with leading zero, if appropriate), and DD is the day of the month (with leading zero, if appropriate). The closest century is assumed as part of the year (i.e., 86 specifies 1986, 30 specifies 2030, 99 is 1999, 00 is 2000). Time must also be specified. It must be as 6 digits HHMMSS with HH being hours on the 24-hour clock, MM minutes 00-59, and SS seconds 00-59. The time is assumed to be in the server's timezone unless the token "GMT" appears, in which case both time and date are evaluated at the 0 meridian. The optional parameter "distributions" is a list of distribution groups, enclosed in angle brackets. If specified, the distribution portion of a new newsgroup (e.g, 'net' in 'net.wombat') will be examined for a match with the distribution categories listed, and only those new newsgroups which match will be listed. If more than one distribution group is to be listed, they must be separated by commas within the angle brackets. Please note that an empty list (i.e., the text body returned by this command consists only of the terminating period) is a possible valid response, and indicates that there are currently no new newsgroups. 3.7.2. Responses 231 list of new newsgroups follows 3.8. The NEWNEWS command 3.8.1. NEWNEWS NEWNEWS newsgroups date time [GMT] [] A list of message-ids of articles posted or received to the specified newsgroup since "date" will be listed. The format of the listing will be one message-id per line, as though text were being sent. A single line consisting solely of one period followed by CR-LF will terminate the list. Date and time are in the same format as the NEWGROUPS command. A newsgroup name containing a "*" (an asterisk) may be specified to broaden the article search to some or all newsgroups. The asterisk will be extended to match any part of a newsgroup name (e.g., net.micro* will match net.micro.wombat, net.micro.apple, etc). Thus if only an asterisk is given as the newsgroup name, all newsgroups will be searched for new news. (Please note that the asterisk "*" expansion is a general replacement; in particular, the specification of e.g., net.*.unix should be correctly expanded to embrace names such as net.wombat.unix and net.whocares.unix.) Conversely, if no asterisk appears in a given newsgroup name, only the specified newsgroup will be searched for new articles. Newsgroup names must be chosen from those returned in the listing of available groups. Multiple newsgroup names (including a "*") may be specified in this command, separated by a comma. No comma shall appear after the last newsgroup in the list. [Implementors are cautioned to keep the 512 character command length limit in mind.] The exclamation point ("!") may be used to negate a match. This can be used to selectively omit certain newsgroups from an otherwise larger list. For example, a newsgroups specification of "net.*,mod.*,!mod.map.*" would specify that all net. and all mod. EXCEPT mod.map. newsgroup names would be matched. If used, the exclamation point must appear as the first character of the given newsgroup name or pattern. The optional parameter "distributions" is a list of distribution groups, enclosed in angle brackets. If specified, the distribution portion of an article's newsgroup (e.g, 'net' in 'net.wombat') will be examined for a match with the distribution categories listed, and only those articles which have at least one newsgroup belonging to the list of distributions will be listed. If more than one distribution group is to be supplied, they must be separated by commas within the angle brackets. The use of the IHAVE, NEWNEWS, and NEWGROUPS commands to distribute news is discussed in an earlier part of this document. Please note that an empty list (i.e., the text body returned by this command consists only of the terminating period) is a possible valid response, and indicates that there is currently no new news. 3.8.2. Responses 230 list of new articles by message-id follows 3.9. The NEXT command 3.9.1. NEXT NEXT The internally maintained "current article pointer" is advanced to the next article in the current newsgroup. If no more articles remain in the current group, an error message is returned and the current article remains selected. The internally-maintained "current article pointer" is set by this command. A response indicating the current article number, and the message-id string will be returned. No text is sent in response to this command. 3.9.2. Responses 223 n a article retrieved - request text separately (n = article number, a = unique article id) 412 no newsgroup selected 420 no current article has been selected 421 no next article in this group 3.10. The POST command 3.10.1. POST POST If posting is allowed, response code 340 is returned to indicate that the article to be posted should be sent. Response code 440 indicates that posting is prohibited for some installation-dependent reason. If posting is permitted, the article should be presented in the format specified by RFC850, and should include all required header lines. After the article's header and body have been completely sent by the client to the server, a further response code will be returned to indicate success or failure of the posting attempt. The text forming the header and body of the message to be posted should be sent by the client using the conventions for text received from the news server: A single period (".") on a line indicates the end of the text, with lines starting with a period in the original text having that period doubled during transmission. No attempt shall be made by the server to filter characters, fold or limit lines, or otherwise process incoming text. It is our intent that the server just pass the incoming message to be posted to the server installation's news posting software, which is separate from this specification. See RFC850 for more details. Since most installations will want the client news program to allow the user to prepare his message using some sort of text editor, and transmit it to the server for posting only after it is composed, the client program should take note of the herald message that greeted it when the connection was first established. This message indicates whether postings from that client are permitted or not, and can be used to caution the user that his access is read-only if that is the case. This will prevent the user from wasting a good deal of time composing a message only to find posting of the message was denied. The method and determination of which clients and hosts may post is installation dependent and is not covered by this specification. 3.10.2. Responses 240 article posted ok 340 send article to be posted. End with . 440 posting not allowed 441 posting failed (for reference, one of the following codes will be sent upon initial connection; the client program should determine whether posting is generally permitted from these:) 200 server ready - posting allowed 201 server ready - no posting allowed 3.11. The QUIT command 3.11.1. QUIT QUIT The server process acknowledges the QUIT command and then closes the connection to the client. This is the preferred method for a client to indicate that it has finished all its transactions with the NNTP server. If a client simply disconnects (or the connection times out, or some other fault occurs), the server should gracefully cease its attempts to service the client. 3.11.2. Responses 205 closing connection - goodbye! 3.12 The XOVER Command 3.12.1. XOVER XOVER firstArticle - lastArticle  Fetches an overview of the articles in the current group beginning with the article with number firstArticle and ending with the article with number lastArticle. The text response takes the following form: Each article is represented by a single line. Entries in a line are seperated by a TAB. A line contains (in the following order): Subject, From, Date, Time, Message-ID, References, number of bytes, number of lines (see RFC1036 for a closer description of these header entries and their meaning). Omitted information may be detected by two consecutive TAB's. 3.13.2. Responses 224 data follows 4.7.1. Commands ARTICLE BODY GROUP HEAD HELP LAST LIST NEWGROUPS NEWNEWS NEXT POST QUIT STAT XOVER 4.7.2. Responses 100 help text follows 199 debug output 200 server ready - posting allowed 201 server ready - no posting allowed 202 slave status noted 205 closing connection - goodbye! 211 n f l s group selected 215 list of newsgroups follows 220 n article retrieved - head and body follow 221 n article retrieved - head follows 222 n article retrieved - body follows 223 n article retrieved - request text separately 230 list of new articles by message-id follows 231 list of new newsgroups follows 235 article transferred ok 240 article posted ok 335 send article to be transferred. End with . 340 send article to be posted. End with . 400 service discontinued 411 no such news group 412 no newsgroup has been selected 420 no current article has been selected 421 no next article in this group 422 no previous article in this group 423 no such article number in this group 430 no such article found 435 article not wanted - do not send it 436 transfer failed - try again later 437 article rejected - do not try again. 440 posting not allowed 441 posting failed 500 command not recognized 501 command syntax error 502 access restriction or permission denied 503 program fault - command not performed 5. References [1] Crocker, D., "Standard for the Format of ARPA Internet Text Messages", RFC-822, Department of Electrical Engineering, University of Delaware, August, 1982. [2] Horton, M., "Standard for Interchange of USENET Messages", RFC-850, USENET Project, June, 1983. [3] Postel, J., "Transmission Control Protocol- DARPA Internet Program Protocol Specification", RFC-793, USC/Information Sciences Institute, September, 1981. [4] Postel, J., "Simple Mail Transfer Protocol", RFC-821, USC/Information Sciences Institute, August, 1982. 6. Acknowledgements The authors wish to express their heartfelt thanks to those many people who contributed to this specification, and especially to Erik Fair and Chuq von Rospach, without whose inspiration this whole thing would not have been necessary. 7. Notes <1> UNIX is a trademark of Bell Laboratories.  RFC1036 (written by M. Horton (AT&T Bell Laboratories) and R. Adams (Center for Seismic Studies) shortened by Hamader Peter) Standard for Interchange of USENET Messages 2. Message Format The primary consideration in choosing a message format is that it fit in with existing tools as well as possible. Existing tools include implementations of both mail and news. (The notesfiles system from the University of Illinois is considered a news implementation.) A standard format for mail messages has existed for many years on the Internet, and this format meets most of the needs of USENET. Since the Internet format is extensible, extensions to meet the additional needs of USENET are easily made within the Internet standard. Therefore, the rule is adopted that all USENET news messages must be formatted as valid Internet mail messages, according to the Internet standard RFC-822. The USENET News standard is more restrictive than the Internet standard, placing additional requirements on each message and forbidding use of certain Internet features. However, it should always be possible to use a tool expecting an Internet message to process a news message. In any situation where this standard conflicts with the Internet standard, RFC-822 should be considered correct and this standard in error. Here is an example USENET message to illustrate the fields. From: jerry@eagle.ATT.COM (Jerry Schwarz) Path: cbosgd!mhuxj!mhuxt!eagle!jerry Newsgroups: news.announce Subject: Usenet Etiquette -- Please Read Message-ID: <642@eagle.ATT.COM> Date: Fri, 19 Nov 82 16:14:55 GMT Followup-To: news.misc Expires: Sat, 1 Jan 83 00:00:00 -0500 Organization: AT&T Bell Laboratories, Murray Hill The body of the message comes here, after a blank line. Here is an example of a message in the old format (before the existence of this standard). It is recommended that implementations also accept messages in this format to ease upward conversion. From: cbosgd!mhuxj!mhuxt!eagle!jerry (Jerry Schwarz) Newsgroups: news.misc Title: Usenet Etiquette -- Please Read Article-I.D.: eagle.642 Posted: Fri Nov 19 16:14:55 1982 Received: Fri Nov 19 16:59:30 1982 Expires: Mon Jan 1 00:00:00 1990 The body of the message comes here, after a blank line. Some news systems transmit news in the A format, which looks like this: Aeagle.642 news.misc cbosgd!mhuxj!mhuxt!eagle!jerry Fri Nov 19 16:14:55 1982 Usenet Etiquette - Please Read The body of the message comes here, with no blank line. A standard USENET message consists of several header lines, followed by a blank line, followed by the body of the message. Each header line consist of a keyword, a colon, a blank, and some additional information. This is a subset of the Internet standard, simplified to allow simpler software to handle it. The "From" line may optionally include a full name, in the format above, or use the Internet angle bracket syntax. To keep the implementations simple, other formats (for example, with part of the machine address after the close parenthesis) are not allowed. The Internet convention of continuation header lines (beginning with a blank or tab) is allowed. Certain headers are required, and certain other headers are optional. Any unrecognized headers are allowed, and will be passed through unchanged. The required header lines are "From", "Date", "Newsgroups", "Subject", "Message-ID", and "Path". The optional header lines are "Followup-To", "Expires", "Reply-To", "Sender", "References", "Control", "Distribution", "Keywords", "Summary", "Approved", "Lines", "Xref", and "Organization". Each of these header lines will be described below. 2.1. Required Header lines 2.1.1. From The "From" line contains the electronic mailing address of the person who sent the message, in the Internet syntax. It may optionally also contain the full name of the person, in parentheses, after the electronic address. The electronic address is the same as the entity responsible for originating the message, unless the "Sender" header is present, in which case the "From" header might not be verified. Note that in all host and domain names, upper and lower case are considered the same, thus "mark@cbosgd.ATT.COM", "mark@cbosgd.att.com", and "mark@CBosgD.ATt.COm" are all equivalent. User names may or may not be case sensitive, for example, "Billy@cbosgd.ATT.COM" might be different from "BillY@cbosgd.ATT.COM". Programs should avoid changing the case of electronic addresses when forwarding news or mail. RFC-822 specifies that all text in parentheses is to be interpreted as a comment. It is common in Internet mail to place the full name of the user in a comment at the end of the "From" line. This standard specifies a more rigid syntax. The full name is not considered a comment, but an optional part of the header line. Either the full name is omitted, or it appears in parentheses after the electronic address of the person posting the message, or it appears before an electronic address which is enclosed in angle brackets. Thus, the three permissible forms are: From: mark@cbosgd.ATT.COM From: mark@cbosgd.ATT.COM (Mark Horton) From: Mark Horton Full names may contain any printing ASCII characters from space through tilde, except that they may not contain "(" (left parenthesis), ")" (right parenthesis), "<" (left angle bracket), or ">" (right angle bracket). Additional restrictions may be placed on full names by the mail standard, in particular, the characters "," (comma), ":" (colon), "@" (at), "!" (bang), "/" (slash), "=" (equal), and ";" (semicolon) are inadvisable in full names. 2.1.2. Date The "Date" line (formerly "Posted") is the date that the message was originally posted to the network. Its format must be acceptable both in RFC-822 and to the getdate(3) routine that is provided with the Usenet software. This date remains unchanged as the message is propagated throughout the network. One format that is acceptable to both is: Wdy, DD Mon YY HH:MM:SS TIMEZONE Several examples of valid dates appear in the sample message above. Note in particular that ctime(3) format: Wdy Mon DD HH:MM:SS YYYY is not acceptable because it is not a valid RFC-822 date. However, since older software still generates this format, news implementations are encouraged to accept this format and translate it into an acceptable format. There is no hope of having a complete list of timezones. Universal Time (GMT), the North American timezones (PST, PDT, MST, MDT, CST, CDT, EST, EDT) and the +/-hhmm offset specifed in RFC-822 should be supported. It is recommended that times in message headers be transmitted in GMT and displayed in the local time zone. 2.1.3. Newsgroups The "Newsgroups" line specifies the newsgroup or newsgroups in which the message belongs. Multiple newsgroups may be specified, separated by a comma. Newsgroups specified must all be the names of existing newsgroups, as no new newsgroups will be created by simply posting to them. Wildcards (e.g., the word "all") are never allowed in a "News- groups" line. For example, a newsgroup comp.all is illegal, although a newsgroup rec.sport.football is permitted. If a message is received with a "Newsgroups" line listing some valid newsgroups and some invalid newsgroups, a host should not remove invalid newsgroups from the list. Instead, the invalid newsgroups should be ignored. For example, suppose host A subscribes to the classes btl.all and comp.all, and exchanges news messages with host B, which subscribes to comp.all but not btl.all. Suppose A receives a message with Newsgroups: comp.unix,btl.general. This message is passed on to B because B receives comp.unix, but B does not receive btl.general. A must leave the "Newsgroups" line unchanged. If it were to remove btl.general, the edited header could eventually re-enter the btl.all class, resulting in a message that is not shown to users subscribing to btl.general. Also, follow-ups from outside btl.all would not be shown to such users. 2.1.4. Subject The "Subject" line (formerly "Title") tells what the message is about. It should be suggestive enough of the contents of the message to enable a reader to make a decision whether to read the message based on the subject alone. If the message is submitted in response to another message (e.g., is a follow-up) the default subject should begin with the four characters "Re:", and the "References" line is required. For follow-ups, the use of the "Summary" line is encouraged. 2.1.5. Message-ID The "Message-ID" line gives the message a unique identifier. The Message-ID may not be reused during the lifetime of any previous message with the same Message-ID. (It is recommended that no Message-ID be reused for at least two years.) Message-ID's have the syntax: "> In order to conform to RFC-822, the Message-ID must have the format: where full_domain_name is the full name of the host at which the message entered the network, including a domain that host is in, and unique is any string of printing ASCII characters, not including "<" (left angle bracket), ">" (right angle bracket), or "@" (at sign). For example, the unique part could be an integer representing a sequence number for messages submitted to the network, or a short string derived from the date and time the message was created. For example, a valid Message-ID for a message submitted from host ucbvax in domain "Berkeley.EDU" would be "<4123@ucbvax.Berkeley.EDU>". Programmers are urged not to make assumptions about the content of Message-ID fields from other hosts, but to treat them as unknown character strings. It is not safe, for example, to assume that a Message-ID will be under 14 characters, that it is unique in the first 14 characters, nor that is does not contain a "/". The angle brackets are considered part of the Message-ID. Thus, in references to the Message-ID, such as the ihave/sendme and cancel control messages, the angle brackets are included. White space characters (e.g., blank and tab) are not allowed in a Message-ID. Slashes ("/") are strongly discouraged. All characters between the angle brackets must be printing ASCII characters. 2.1.6. Path This line shows the path the message took to reach the current system. When a system forwards the message, it should add its own name to the list of systems in the "Path" line. The names may be separated by any punctuation character or characters (except "." which is considered part of the hostname). Thus, the following are valid entries: cbosgd!mhuxj!mhuxt cbosgd, mhuxj, mhuxt @cbosgd.ATT.COM,@mhuxj.ATT.COM,@mhuxt.ATT.COM teklabs, zehntel, sri-unix@cca!decvax (The latter path indicates a message that passed through decvax, cca, sri-unix, zehntel, and teklabs, in that order.) Additional names should be added from the left. For example, the most recently added name in the fourth example was teklabs. Letters, digits, periods and hyphens are considered part of host names; other punctuation, including blanks, are considered separators. Normally, the rightmost name will be the name of the originating system. However, it is also permissible to include an extra entry on the right, which is the name of the sender. This is for upward compatibility with older systems. The "Path" line is not used for replies, and should not be taken as a mailing address. It is intended to show the route the message traveled to reach the local host. There are several uses for this information. One is to monitor USENET routing for performance reasons. Another is to establish a path to reach new hosts. Perhaps the most important use is to cut down on redundant USENET traffic by failing to forward a message to a host that is known to have already received it. In particular, when host A sends a message to host B, the "Path" line includes A, so that host B will not immediately send the message back to host A. The name each host uses to identify itself should be the same as the name by which its neighbors know it, in order to make this optimization possible. A host adds its own name to the front of a path when it receives a message from another host. Thus, if a message with path "A!X!Y!Z" is passed from host A to host B, B will add its own name to the path when it receives the message from A, e.g., "B!A!X!Y!Z". If B then passes the message on to C, the message sent to C will contain the path "B!A!X!Y!Z", and when C receives it, C will change it to "C!B!A!X!Y!Z". Special upward compatibility note: Since the "From", "Sender", and "Reply-To" lines are in Internet format, and since many USENET hosts do not yet have mailers capable of understanding Internet format, it would break the reply capability to completely sever the connection between the "Path" header and the reply function. It is recognized that the path is not always a valid reply string in older implementations, and no requirement to fix this problem is placed on implementations. However, the existing convention of placing the host name and an "!" at the front of the path, and of starting the path with the host name, an "!", and the user name, should be maintained when possible. 2.2. Optional Headers 2.2.1. Reply-To This line has the same format as "From". If present, mailed replies to the author should be sent to the name given here. Otherwise, replies are mailed to the name on the "From" line. (This does not prevent additional copies from being sent to recipients named by the replier, or on "To" or "Cc" lines.) The full name may be optionally given, in parentheses, as in the "From" line. 2.2.2. Sender This field is present only if the submitter manually enters a "From" line. It is intended to record the entity responsible for submitting the message to the network. It should be verified by the software at the submitting host. For example, if John Smith is visiting CCA and wishes to post a message to the network, using friend Sarah Jones' account, the message might read: From: smith@ucbvax.Berkeley.EDU (John Smith) Sender: jones@cca.COM (Sarah Jones) If a gateway program enters a mail message into the network at host unix.SRI.COM, the lines might read: From: John.Doe@A.CS.CMU.EDU Sender: network@unix.SRI.COM The primary purpose of this field is to be able to track down messages to determine how they were entered into the network. The full name may be optionally given, in parentheses, as in the "From" line. 2.2.3. Followup-To This line has the same format as "Newsgroups". If present, follow- up messages are to be posted to the newsgroup or newsgroups listed here. If this line is not present, follow-ups are posted to the newsgroup or newsgroups listed in the "Newsgroups" line. If the keyword poster is present, follow-up messages are not permitted. The message should be mailed to the submitter of the message via mail. 2.2.4. Expires This line, if present, is in a legal USENET date format. It specifies a suggested expiration date for the message. If not present, the local default expiration date is used. This field is intended to be used to clean up messages with a limited usefulness, or to keep important messages around for longer than usual. For example, a message announcing an upcoming seminar could have an expiration date the day after the seminar, since the message is not useful after the seminar is over. Since local hosts have local policies for expiration of news (depending on available disk space, for instance), users are discouraged from providing expiration dates for messages unless there is a natural expiration date associated with the topic. System software should almost never provide a default "Expires" line. Leave it out and allow local policies to be used unless there is a good reason not to. 2.2.5. References This field lists the Message-ID's of any messages prompting the submission of this message. It is required for all follow-up messages, and forbidden when a new subject is raised. Implementations should provide a follow-up command, which allows a user to post a follow-up message. This command should generate a "Subject" line which is the same as the original message, except that if the original subject does not begin with "Re:" or "re:", the four characters "Re:" are inserted before the subject. If there is no "References" line on the original header, the "References" line should contain the Message-ID of the original message (including the angle brackets). If the original message does have a "References" line, the follow-up message should have a "References" line containing the text of the original "References" line, a blank, and the Message-ID of the original message. The purpose of the "References" header is to allow messages to be grouped into conversations by the user interface program. This allows conversations within a newsgroup to be kept together, and potentially users might shut off entire conversations without unsubscribing to a newsgroup. User interfaces need not make use of this header, but all automatically generated follow-ups should generate the "References" line for the benefit of systems that do use it, and manually generated follow-ups (e.g., typed in well after the original message has been printed by the machine) should be encouraged to include them as well. It is permissible to not include the entire previous "References" line if it is too long. An attempt should be made to include a reasonable number of backwards references. 2.2.6. Control If a message contains a "Control" line, the message is a control message. Control messages are used for communication among USENET host machines, not to be read by users. Control messages are distributed by the same newsgroup mechanism as ordinary messages. The body of the "Control" header line is the message to the host. For upward compatibility, messages that match the newsgroup pattern "all.all.ctl" should also be interpreted as control messages. If no "Control" header is present on such messages, the subject is used as the control message. However, messages on newsgroups matching this pattern do not conform to this standard. Also for upward compatibility, if the first 4 characters of the "Subject:" line are "cmsg", the rest of the "Subject:" line should be interpreted as a control message. 2.2.7. Distribution This line is used to alter the distribution scope of the message. It is a comma separated list similar to the "Newsgroups" line. User subscriptions are still controlled by "Newsgroups", but the message is sent to all systems subscribing to the newsgroups on the "Distribution" line in addition to the "Newsgroups" line. For the message to be transmitted, the receiving site must normally receive one of the specified newsgroups AND must receive one of the specified distributions. Thus, a message concerning a car for sale in New Jersey might have headers including: Newsgroups: rec.auto,misc.forsale Distribution: nj,ny so that it would only go to persons subscribing to rec.auto or misc. for sale within New Jersey or New York. The intent of this header is to restrict the distribution of a newsgroup further, not to increase it. A local newsgroup, such as nj.crazy-eddie, will probably not be propagated by hosts outside New Jersey that do not show such a newsgroup as valid. A follow-up message should default to the same "Distribution" line as the original message, but the user can change it to a more limited one, or escalate the distribution if it was originally restricted and a more widely distributed reply is appropriate. 2.2.8. Organization The text of this line is a short phrase describing the organization to which the sender belongs, or to which the machine belongs. The intent of this line is to help identify the person posting the message, since host names are often cryptic enough to make it hard to recognize the organization by the electronic address. 2.2.9. Keywords A few well-selected keywords identifying the message should be on this line. This is used as an aid in determining if this message is interesting to the reader. 2.2.10. Summary This line should contain a brief summary of the message. It is usually used as part of a follow-up to another message. Again, it is very useful to the reader in determining whether to read the message. 2.2.11. Approved This line is required for any message posted to a moderated newsgroup. It should be added by the moderator and consist of his mail address. It is also required with certain control messages. 2.2.12. Lines This contains a count of the number of lines in the body of the message. 2.2.13. Xref This line contains the name of the host (with domains omitted) and a white space separated list of colon-separated pairs of newsgroup names and message numbers. These are the newsgroups listed in the "Newsgroups" line and the corresponding message numbers from the spool directory. This is only of value to the local system, so it should not be transmitted. For example, in: Path: seismo!lll-crg!lll-lcc!pyramid!decwrl!reid From: reid@decwrl.DEC.COM (Brian Reid) Newsgroups: news.lists,news.groups Subject: USENET READERSHIP SUMMARY REPORT FOR SEP 86 Message-ID: <5658@decwrl.DEC.COM> Date: 1 Oct 86 11:26:15 GMT Organization: DEC Western Research Laboratory Lines: 441 Approved: reid@decwrl.UUCP Xref: seismo news.lists:461 news.groups:6378 the "Xref" line shows that the message is message number 461 in the newsgroup news.lists, and message number 6378 in the newsgroup news.groups, on host seismo. This information may be used by certain user interfaces. 3. Control Messages This section lists the control messages currently defined. The body of the "Control" header line is the control message. Messages are a sequence of zero or more words, separated by white space (blanks or tabs). The first word is the name of the control message, remaining words are parameters to the message. The remainder of the header and the body of the message are also potential parameters; for example, the "From" line might suggest an address to which a response is to be mailed. Implementors and administrators may choose to allow control messages to be carried out automatically, or to queue them for annual processing. However, manually processed messages should be dealt with promptly. Failed control messages should NOT be mailed to the originator of the message, but to the local "usenet" account. 3.1. Cancel cancel If a message with the given Message-ID is present on the local system, the message is cancelled. This mechanism allows a user to cancel a message after the message has been distributed over the network. If the system is unable to cancel the message as requested, it should not forward the cancellation request to its neighbor systems. Only the author of the message or the local news administrator is allowed to send this message. The verified sender of a message is the "Sender" line, or if no "Sender" line is present, the "From" line. The verified sender of the cancel message must be the same as either the "Sender" or "From" field of the original message. A verified sender in the cancel message is allowed to match an unverified "From" in the original message. 3.2. Ihave/Sendme ihave [] sendme [] This message is part of the ihave/sendme protocol, which allows one host (say A) to tell another host (B) that a particular message has been received on A. Suppose that host A receives message "<1234@ucbvax.Berkeley.edu>", and wishes to transmit the message to host B. A sends the control message "ihave <1234@ucbvax.Berkeley.edu> A" to host B (by posting it to newsgroup to.B). B responds with the control message "sendme <1234@ucbvax.Berkeley.edu> B" (on newsgroup to.A), if it has not already received the message. Upon receiving the sendme message, A sends the message to B. This protocol can be used to cut down on redundant traffic between hosts. It is optional and should be used only if the particular situation makes it worthwhile. Frequently, the outcome is that, since most original messages are short, and since there is a high overhead to start sending a new message with UUCP, it costs as much to send the ihave as it would cost to send the message itself. One possible solution to this overhead problem is to batch requests. Several Message-ID's may be announced or requested in one message. If no Message-ID's are listed in the control message, the body of the message should be scanned for Message-ID's, one per line. 3.3. Newgroup newgroup [moderated] This control message creates a new newsgroup with the given name. Since no messages may be posted or forwarded until a newsgroup is created, this message is required before a newsgroup can be used. The body of the message is expected to be a short paragraph describing the intended use of the newsgroup. If the second argument is present and it is the keyword moderated, the group should be created moderated instead of the default of unmoderated. The newgroup message should be ignored unless there is an "Approved" line in the same message header. 3.4. Rmgroup rmgroup This message removes a newsgroup with the given name. Since the newsgroup is removed from every host on the network, this command should be used carefully by a responsible administrator. The rmgroup message should be ignored unless there is an "Approved:" line in the same message header. 3.5. Sendsys sendsys (no arguments) The sys file, listing all neighbors and the newsgroups to be sent to each neighbor, will be mailed to the author of the control message ("Reply-To", if present, otherwise "From"). This information is considered public information, and it is a requirement of membership in USENET that this information be provided on request, either automatically in response to this control message, or manually, by mailing the requested information to the author of the message. This information is used to keep the map of USENET up to date, and to determine where netnews is sent. The format of the file mailed back to the author should be the same as that of the sys file. This format has one line per neighboring host (plus one line for the local host), containing four colon separated fields. The first field has the host name of the neighbor, the second field has a newsgroup pattern describing the newsgroups sent to the neighbor. The third and fourth fields are not defined by this standard. The sys file is not the same as the UUCP L.sys file. A sample response is: From: cbosgd!mark (Mark Horton) Date: Sun, 27 Mar 83 20:39:37 -0500 Subject: response to your sendsys request To: mark@cbosgd.ATT.COM Responding-System: cbosgd.ATT.COM cbosgd:osg,cb,btl,bell,world,comp,sci,rec,talk,misc,news,soc,to, test ucbvax:world,comp,to.ucbvax:L: cbosg:world,comp,bell,btl,cb,osg,to.cbosg:F:/usr/spool/outnews /cbosg cbosgb:osg,to.cbosgb:F:/usr/spool/outnews/cbosgb sescent:world,comp,bell,btl,cb,to.sescent:F:/usr/spool/outnews /sescent npois:world,comp,bell,btl,ug,to.npois:F:/usr/spool/outnews/npois mhuxi:world,comp,bell,btl,ug,to.mhuxi:F:/usr/spool/outnews/mhuxi 3.6. Version version (no arguments) The name and version of the software running on the local system is to be mailed back to the author of the message ("Reply-to" if present, otherwise "From"). 3.7. Checkgroups The message body is a list of "official" newsgroups and their description, one group per line. They are compared against the list of active newsgroups on the current host. The names of any obsolete or new newsgroups are mailed to the user "usenet" and descriptions of the new newsgroups are added to the help file used when posting news. 4. Transmission Methods USENET is not a physical network, but rather a logical network resting on top of several existing physical networks. These networks include, but are not limited to, UUCP, the Internet, an Ethernet, the BLICN network, an NSC Hyperchannel, and a BERKNET. What is important is that two neighboring systems on USENET have some method to get a new message, in the format listed here, from one system to the other, and once on the receiving system, processed by the netnews software on that system. (On UNIX systems, this usually means the rnews program being run with the message on the standard input. <1>) It is not a requirement that USENET hosts have mail systems capable of understanding the Internet mail syntax, but it is strongly recommended. Since "From", "Reply-To", and "Sender" lines use the Internet syntax, replies will be difficult or impossible without an Internet mailer. A host without an Internet mailer can attempt to use the "Path" header line for replies, but this field is not guaranteed to be a working path for replies. In any event, any host generating or forwarding news messages must have an Internet address that allows them to receive mail from hosts with Internet mailers, and they must include their Internet address on their From line. 4.1. Remote Execution Some networks permit direct remote command execution. On these networks, news may be forwarded by spooling the rnews command with the message on the standard input. For example, if the remote system is called remote, news would be sent over a UUCP link with the command: uux - remote!rnews and on a Berknet: net -mremote rnews It is important that the message be sent via a reliable mechanism, normally involving the possibility of spooling, rather than direct real-time remote execution. This is because, if the remote system is down, a direct execution command will fail, and the message will never be delivered. If the message is spooled, it will eventually be delivered when both systems are up. 4.2. Transfer by Mail On some systems, direct remote spooled execution is not possible. However, most systems support electronic mail, and a news message can be sent as mail. One approach is to send a mail message which is identical to the news message: the mail headers are the news headers, and the mail body is the news body. By convention, this mail is sent to the user newsmail on the remote machine. One problem with this method is that it may not be possible to convince the mail system that the "From" line of the message is valid, since the mail message was generated by a program on a system different from the source of the news message. Another problem is that error messages caused by the mail transmission would be sent to the originator of the news message, who has no control over news transmission between two cooperating hosts and does not know whom to contact. Transmission error messages should be directed to a responsible contact person on the sending machine. A solution to this problem is to encapsulate the news message into a mail message, such that the entire message (headers and body) are part of the body of the mail message. The convention here is that such mail is sent to user rnews on the remote system. A mail message body is generated by prepending the letter N to each line of the news message, and then attaching whatever mail headers are convenient to generate. The N's are attached to prevent any special lines in the news message from interfering with mail transmission, and to prevent any extra lines inserted by the mailer (headers, blank lines, etc.) from becoming part of the news message. A program on the receiving machine receives mail to rnews, extracting the message itself and invoking the rnews program. An example in this format might look like this: Date: Mon, 3 Jan 83 08:33:47 MST From: news@cbosgd.ATT.COM Subject: network news message To: rnews@npois.ATT.COM NPath: cbosgd!mhuxj!harpo!utah-cs!sask!derek NFrom: derek@sask.UUCP (Derek Andrew) NNewsgroups: misc.test NSubject: necessary test NMessage-ID: <176@sask.UUCP> NDate: Mon, 3 Jan 83 00:59:15 MST N NThis really is a test. If anyone out there more than 6 Nhops away would kindly confirm this note I would Nappreciate it. We suspect that our news postings Nare not getting out into the world. N Using mail solves the spooling problem, since mail must always be spooled if the destination host is down. However, it adds more overhead to the transmission process (to encapsulate and extract the message) and makes it harder for software to give different priorities to news and mail. 4.3. Batching Since news messages are usually short, and since a large number of messages are often sent between two hosts in a day, it may make sense to batch news messages. Several messages can be combined into one large message, using conventions agreed upon in advance by the two hosts. One such batching scheme is described here; its use is highly recommended. News messages are combined into a script, separated by a header of the form: #! rnews 1234 where 1234 is the length of the message in bytes. Each such line is followed by a message containing the given number of bytes. (The newline at the end of each line of the message is counted as one byte, for purposes of this count, even if it is stored as .) For example, a batch of message might look like this: #! rnews 239 From: jerry@eagle.ATT.COM (Jerry Schwarz) Path: cbosgd!mhuxj!mhuxt!eagle!jerry Newsgroups: news.announce Subject: Usenet Etiquette -- Please Read Message-ID: <642@eagle.ATT.COM> Date: Fri, 19 Nov 82 16:14:55 EST Approved: mark@cbosgd.ATT.COM Here is an important message about USENET Etiquette. #! rnews 234 From: jerry@eagle.ATT.COM (Jerry Schwarz) Path: cbosgd!mhuxj!mhuxt!eagle!jerry Newsgroups: news.announce Subject: Notes on Etiquette message Message-ID: <643@eagle.ATT.COM> Date: Fri, 19 Nov 82 17:24:12 EST Approved: mark@cbosgd.ATT.COM There was something I forgot to mention in the last message. Batched news is recognized because the first character in the message is #. The message is then passed to the unbatcher for interpretation. The second argument (in this example rnews) determines which batching scheme is being used. Cooperating hosts may use whatever scheme is appropriate for them. 5. The News Propagation Algorithm This section describes the overall scheme of USENET and the algorithm followed by hosts in propagating news to the entire logical network. Since all hosts are affected by incorrectly formatted messages and by propagation errors, it is important for the method to be standardized. USENET is a directed graph. Each node in the graph is a host computer, and each arc in the graph is a transmission path from one host to another host. Each arc is labeled with a newsgroup pattern, specifying which newsgroup classes are forwarded along that link. Most arcs are bidirectional, that is, if host A sends a class of newsgroups to host B, then host B usually sends the same class of newsgroups to host A. This bidirectionality is not, however, required. USENET is made up of many subnetworks. Each subnet has a name, such as comp or btl. Each subnet is a connected graph, that is, a path exists from every node to every other node in the subnet. In addition, the entire graph is (theoretically) connected. (In practice, some political considerations have caused some hosts to be unable to post messages reaching the rest of the network.) A message is posted on one machine to a list of newsgroups. That machine accepts it locally, then forwards it to all its neighbors that are interested in at least one of the newsgroups of the message. (Site A deems host B to be "interested" in a newsgroup if the newsgroup matches the pattern on the arc from A to B. This pattern is stored in a file on the A machine.) The hosts receiving the incoming message examine it to make sure they really want the message, accept it locally, and then in turn forward the message to all their interested neighbors. This process continues until the entire network has seen the message. An important part of the algorithm is the prevention of loops. The above process would cause a message to loop along a cycle forever. In particular, when host A sends a message to host B, host B will send it back to host A, which will send it to host B, and so on. One solution to this is the history mechanism. Each host keeps track of all messages it has seen (by their Message-ID) and whenever a message comes in that it has already seen, the incoming message is discarded immediately. This solution is sufficient to prevent loops, but additional optimizations can be made to avoid sending messages to hosts that will simply throw them away. One optimization is that a message should never be sent to a machine listed in the "Path" line of the header. When a machine name is in the "Path" line, the message is known to have passed through the machine. Another optimization is that, if the message originated on host A, then host A has already seen the message. Thus, if a message is posted to newsgroup misc.misc, it will match the pattern misc.all (where all is a metasymbol that matches any string), and will be forwarded to all hosts that subscribe to misc.all (as determined by what their neighbors send them). These hosts make up the misc subnetwork. A message posted to btl.general will reach all hosts receiving btl.all, but will not reach hosts that do not get btl.all. In effect, the messages reaches the btl subnetwork. A messages posted to newsgroups misc.misc,btl.general will reach all hosts subscribing to either of the two classes. Notes <1> UNIX is a registered trademark of AT&T.