Brad Templeton Internal Page

Error Control Message and Errors-to header

Error Control Message and Errors-to header

Preliminary talking draft.

The special "Error" control message allows for the efficient and unique reporting of errors in USENET postings to the source of the posting.

When a transport or database system encounters an error in an article which should be reported to the generator of the article, the message should be sent using this special control message.

Errors MUST NOT be generated on error messages. Errors on error messages SHOULD be logged and/or reported to local site admins.

The control line has the form:

Control: error code=sysname.integer site=<site> [party=user|admin|injection|poster path=<path>] 
sysname	=	1*alpha 

The site is the injection site from the original, error-causing article.

The message also MUST contain a copy of the "Errors-to" header from the message which generated the error. As errors on not reported on error messages, this Errors-to header changes meaning when on an error.

This message reports an error in a previous posting. It MUST not be propagated to other sites, other than to sites known to be the direct route to the site in question.

The Newsgroups: line of the error message should be the line from the original posting, or a subset of those groups if the error only applies to some groups.

The body of the error message should consist of any diagnostic message, and the header and optionally the body of the offending message. The header and body MAY be truncated so as to keep the message of reasonable size, though efforts SHOULD be made to include the section which triggered the error.

The "From" line of the error message should identify the party who maintains the system which generated the error. Systems MUST NOT generate automatic email to this address. It is for use only so that parties which receive an error message and have questions or complaints about it may manually reach the generator of the error.

The code field consists of a unique system name for the software system generating the error. Sample names might be "cnews" or "inn" or similar. The integer must be a unique integer different for every error message.

Special Feeding Rules

An error message is not to be fed to all sites that receive the Newsgroups line like a normal message. Instead the "path" field from the error control line should be extracted. Any material to the left of the local site's path-identity should be ignored. The system should scan the sites to the right of its own path-identity, and scan to the right until it finds a site which it feeds articles to. Normally this will be the site immediately to the right. If it finds no site in the list it should log the error and redirect the message to a local place for later analysis.

The site SHOULD feed the article ONLY to the site found by the above process. It MAY also feed it to other sites to the right of it in the path field.

Reporting the Error

If the site is the injecting site in the path field (which is to say the site to the immediate left of a '%', since the site, if conformant to this specification only generates a new-format Path field on injection) or is responsible for the injecting site, it should not forward the error message. Instead it is responsible for handling the error message by delivering it to the appropriate party.

The optional "party" field indicates that the author of the diagnostic message felt it was more likely that the error should be brought to the attention of the named party. If the field "injection" is used, it is meant to indicate the problem is likely to be a bug in the injection software rather than a human error. If the field "poster" is used, it is meant to indicate the problem is likely to be the fault of the author of the posting software. In both of these cases, the error MUST NOT be automatically reported to said software author, unless that author has given explicit consent to receive such errors.

"admin" and "injector" errors SHOULD be reported to an appropriate system administrator for the injection site. It is acceptable if this reporting process results strictly in collection and statistical monitoring. It is not required that the error necesarrily be delivered as E-mail.

"user" and "poster" errors SHOULD be reported to the party that posted the original sending message. Normally this would be done by E-mail. The system MAY also report them to the local administrator.

If there is no "party" field, the system MAY select where to report the error at its discretion, or based on the class. The system MAY choose how to handle the error even when a "party" field is present.

Reports sent by E-mail should include a pointer to an explanation of the error system, and in particular if sent to users, advice on what to do about the error and how to report bugs to the authors of software.

class fields

The following <class> fields are defined. More may be defined but must be registered with the USENET error class registration authority.

The message violated group or hierarchy-specific rules, such as size, mime-type, crossposting or similar restrictions. Generally to be issued only by watch-daemons, not by relay agents.

The header in question is in violation of the specification. If more than one header is in violation, chose the one that comes first when they are sorted in ASCII order.

A problem with the body of the article

General catch-all error class

(Other suggestions welcome).

Error message limits

Any program that generates errors MUST keep track all errors it sends in a 48 hour period to check for possible over-sending of errors. If the program detects it is issuing errors on more than a certain fraction of messages in a given group, or the entire net, it MUST suspend sending error messages until an administrator has determined that the problem is not in the local error-detection software, and that the articles truly have errors.

The threshold may be tuned based on typical fractions of messages with errors on the net or in specific groups. A system MUST not send out errors on more than 10% of all incoming articles, and MUST not send out an error to the same sender/poster/site more than once per day.

Error messages MUST be under 10 kilobytes in length, and SHOULD usually be much shorter. As noted, the contents of the original message MAY, and sometimes MUST be truncated.

Messages on which an error was reported SHOULD NOT be propagated to other sites.

Message ID of error message

The control message MUST have a special message-id, derived from the original message-id by appending ".<class>.ERROR" to the end of the ID, after the domain part, where "<class>" is the class of error as described below.

This assures that only one copy of an error for each class will be delivered to the destination machine.

If the error is to report that the message-ID is malformed, the message MUST be constructed from the base64 encoding of the SHA-1 hash of the invariant parts of the article. This hash is to be calculated as for the "Signed" header, if the article is signed. If it is not signed, it should be calculated as though the list of headers to sign consists of the following: From, Message-id, Newsgroups, Subject, Date. The error message's message-id should be in the form "<hash-base64@@Head-Message-ID.ERROR>"

One-Way news feeds

Errors will not propagate back via one-way news feeds. Sites are strongly encouraged, if they have a one-way news feed, to make a back feed only for error messages, even if other articles are not expected to flow. Transport systems SHOULD provide a facility to feed only errors to a destination site.

Errors-to header

Other than at the injection site, errors MUST not be reported unless there is an Errors-to header present on the article. This header specifies the parties to whom the message is to be delivered.

Errorsto	=	1*field 
field		=	fieldname '=' value | fieldname | !'"'regexp'"' | 
			'!' sysname.integer | '!' sysname 
fieldname	=	1*alpha 
value		=	e-mail-address | keyword 

The injection site is responsible for reading the Errors-to header from the error message and reporting the error.

Field names with optional values:

The E-mail address to report errors meant for the user.

The E-mail address to report errors meant for the admin.

The E-mail address to report errors meant for the author/maintainer of the injection software.

The E-mail address to report errors meant for the author/maintainer of the posting software.

If the field is of the form '!"regexp"' then this indicates any site whose path identity matches the regular expression MUST NOT generate an error message on this message. If the field is of the form '!sysname' then that software system MUST NOT generate errors on this message. If the field is of the form '!sysname.integer' then the specific error named by the software system and integer MUST not be generated.

If the poster of the original message which generated the error is not authorized to use the E-mail address, the error MUST NOT be generated.

However, any poster shall be considered authorized to use an address where "usenet-err" is the first (innermost) component of the domain name. This allows software authors to have their software insert, either all the time or at random intervals, their own error reporting address into messages they generate.

(It is noted that software authors using this feature should take care lest they be inundanted with error messages. They should program their systems to only put these tags on a small number of messages, and if the software is run by users out of their control, to arrange that after a certain date the tags will not be added.)