Brad Templeton Internal Page
Error ReportingError Reporting
Preliminary talking draft. This draft describes the "Errors" header
and the "error" control message, a means to allow optional reporting of
errors generated at remote sites by USENET postings.
Both messages use standard MIME parameter-list format.
Errors
If an "Errors" header is present, the poster is requesting that errors
generated by the posting be reported back in some fashion. Sites
which inject, relay or store messages SHOULD attempt to report back any
errors according to the rules of this header. Client (newsreading) tools
MUST NOT report errors unless explicitly requested to do so.
The following parameters are defined for the "Errors" header.
Method = [control | email]
Default is "control". This specifies the method by which the error should
be reported.
control
The error should be reported by generating a control message of type "error".
The control message MUST use a Message-id which is created by taking the
original message-id (without angle brackets) of the message which generated
the error, and appending the exact string ".ERROR" to the end before
re-enclosing in angle brackets. It is essential that all systems reporting
errors by this means generate the same message-id so that multiple errors
generated by the same message do not overwhelm the net or the recipient.
It is of course possible that one message might generate two different
errors. It is up to the sender to, in further efforts, eliminate the first
error they receive, then check for further ones.
In the event that the error is a malformed or missing message-id, the
system MUST NOT generate an error control message.
An error control message retains the Newsgroups and Distribution headers
from the original message, to best assure it returns to the originating
site. The control message SHOULD contain a "References" header naming
only the original Message-ID of the error-generating message.
The From line MUST point to a contact address for the error generating
entity. The Date line MUST be the time the error was generated. The
Subject line SHOULD be a one-line error message. Other headers MAY be
preserved.
The body of the error message is described below.
email
This mode indicates the error message SHOULD be E-mailed to the provided
target address. To avoid mailbomb attacks, any use of this mode must
include authentication that the poster of the message is authorized to
direct mail to the specified E-mail address. (Ie. the message MUST be
signed with digital certificate indicating rights to use the address.)
In the event of E-mail headers may be included in the E-mail header, or
detailed in the body.
Systems emailing errors MUST assure they do not mail errors below the
requested error or warning level. For E-mail error reporting, the default
level is "fatal" -- ie. only report errors that cause the message to be
discarded and not stored or forwarded.
email=<address>
Provides an E-mail address for use in reporting errors, or for inclusion
on the error message control line. Default is the E-mail address
from the Sender line, or failing that the From line. The Reply-to line
is not used.
site=<path-entry>
The USENET path-entry name for the site that will be responsible for
handling the error.
level=<number>
Specifies a level of error message or warning desired. Errors with
an "error level" above the specified number MUST NOT be reported. The
default is "2" (serious) for control mode and "1" (fatal) for E-mail mode.
Here are the levels:
- 0 - Critical
- The message caused processing software to fail (for example, to dump core)
in some critical manner. As a matter of course, this means the error was
also fatal.
- 1 - Fatal
- The message violates the USENET format standard in a fashion which caused
the system to discard the message, and neither store it locally nor forward
it onwards.
- 2 - Serious
- The message violates the USENET format standard but the violation was
tolerable, and the message has been stored locally, but not forwarded.
- 3 - Major
- The message violations the USENET format standard but the violation was
tolerable, and the message was forwarded (possibly with modifications) and
stored.
- 4 - Obsolete
- The message uses forms which, though legal, are deprecated and planned for
obsolesence. It was processed normally.
- 5 - Signature
- The message failed authentication tests and was discarded.
- 6 - Policy
- The message was discarded because it failed to meet policy criteria.
- 10 - Warning
- The message has generated a warning
pattern=string
This parameter may appear multiple times. If any are present, the error
SHOULD NOT be generated unless the subject line or body of the error message
contains one of the specified strings. This allows posters to request
errors only from certain software agents, or certain types of errors.
Control Error message
The "error" Control message takes parameters, MIME extended header
stile. They are:
email=<address>
This is the target E-mail address for the error, taken either from the
Errors header or the Sender or From line of the original message.
site=<path-entry>
The path-entry element from the "site" parameter on the Errors header.
agent=string
A unique identifying string for the software agent that generated the
error. Any alphanumeric string the agent chooses is fine.
party=user|admin|injection|poster
This optional parameter MAY be provided if the generator of the error
feels it has some knowledge about who at the originating end should be
informed about the error. The normal field is the user. Other options
include "admin," the administrator of the injecting site, "injection", the
author/maintainer of the injecting or gateway software and "poster", the
author/maintainer of the USENET posting/authoring software.
Error Message Body
The body of an error message SHOULD be an error message with sufficient
detail to diagnose the error. It MUST contain an identifier for the
software generating the error, including any version number.
It MUST also contain contact information,
in the form of E-mail, web or other addresses for the site generating the
error and the party maintaining the software generating the error.
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. The contents of the original message generally are not
included, though they MAY be if they do not exceed this length limit.
Handling Errors
News database/relay systems SHOULD handle incoming Control: error messages
as follows. If they detect an error message with a "site" parameter that
matches their site, they should extract any E-mail address from the
message, and forward the error message through some local means, typically
E-mail, to the user. However, if the error message also has a "party"
field which indicates the error may be due to software maintained by
local admins, the system SHOULD attempt to first report the error to
such administrators before forwarding it to the user. However, it MAY send
such errors to both. The complete contents of the error message SHOULD
be forwarded. If a copy of the original message is still on hand
locally, as a courtesy systems SHOULD append a copy to the reported error.
Central watching
Though not part of this spec, it is anticipated that daemons will watch
control messages to note patterns in errors. In partiuclar, if one
particular site is generating too many errors this can be detected. If
a particular injecting package is generating the same error all the time,
this may be reported to the author of the package.
It's also possible that the author of a news posting or injecting
package, particularly in the beta phase, may wish to have some fraction
of the articles include an Errors header directing errors not to the user or
user's site but to the author or author's site. However, due to
Newsgroups/Distribution rules, the author will only see errors in postings
to newsgroups and distributions to which her site subscribes.