Hi WG,
as agreed upon, I have written some wording of how the concept of the
cookie may be described within the syslog format itself. Although it
looks quite straightforward on the first look, there are some nasty
things to consider when it comes to nested cookies and keeping the
namespace clean. I think it is not actually complicated, but it is quite
lengthy.
I would appreciate any feedback on the wording. So far, I suggest:
####
ABNF(excerpt):
SYSLOG-MSG = PRI HEADER MSG
COOKIE = "@#" (COOKIE-IANA / COOKIE-VENDOR /
COOKIE-EXPER)
COOKIE-IANA = COOKIE-ID ; IANA-Assigned
COOKIE-EXPER = "X-" COOKIE-ID ; experimental
COOKIE-VENDOR = "V-" VENDORURI "-" COOKIE-ID
VENDORURI = 1*64PRINTUSASCII
; a valid domain name owned by the vendor
COOKIE-ID = 4*6PRINTUSASCII ; MUST NOT begin with "V-" or
"X-"
MSG = (COOKIE SP [COOKIE-PARAMS SP] MSG) / PAYLOAD
PAYLOAD = *((%d32-126) / (%d128-254))
; VALID UTF-8 String of PRINTABLE characters
COOKIE-PARAMS = *(PRINTUSASCII / %d32)
; parameters defined by the extension using the
cookie
PRINTUSASCII = %d33-126
Text following it:
2.1 MSG
The MSG part can optionally contain a cookie. If it does, optional
cookie parameters follow after the cookie and after that the original
message.
NOTE WELL: MSG is a recursive structure. As such, a MSG may contain a
COOKIE and another MSG which in turn also contains a COOKIE and yet
another MSG. To clarify things, we call a MSG that does not contain
any COOKIE the actual PAYLOAD.
There is no hard limit of how many levels of COOKIE/MSG constructs
are used inside a single message. The only limit is that the whole
construct must fit within the syslog size limitations. Practically,
however, it is recommended to limit nesting to those cases where it
absolutely must be done and there is good reasoning for it.
NOTE WELL: there is an inherant risk with the nesting of COOKIES: As
specified, a receiver must assume a valid cookie only if he knows the
full COOKIE, including COOKIE-ID. If he does not know that specific
cookie, it MUST be treated as ordinary data, thus turning the message
from MSG to PAYLOAD. As such, no parsing for further COOKIES in
PAYLOAD is allowed nor desired. In consequence, COOKIES nested in
deeper layers will not be seen and processed.
The author beliefes this potential shortcomming is acceptable. If
inner-layer cookies would be tried to parse, this would potentially
conflict with existing syslog data as well as introduce a number of
potential bugs, as the format and thus validity of the outer level
cookie is not know. It is assumed that if the outer layer cookie is
not know, the receiver will most probably not understand the
inner-layer cookie.
To minimize this risk, more generic cookies should be at the outer
layers and less specific cookies on the inner layers.
If the fragmentation features of syslog-international are used, the
syslog-international COOKIE MUST be the outermost COOKIE. If the
fragmentation features are not used, it SHOULD be the outermost
COOKIE, but MAY appear inside another COOKIES' MSG.
2.2 PAYLOAD Part
The PAYLOAD part contains the details of the message. This has
traditionally been a freeform message that gives some detailed
information of the event. The PAYLOAD part of the syslog packet MUST
contain visible (printing) characters.
If the syslog-international COOKIE is NOT used, the code set used
MUST be seven-bit ASCII in an eight-bit field like that used in the
PRI part. In this code set, the only allowable characters are the
ABNF VCHAR values (%d33-126) and spaces (SP value %d32).
If the syslog-international COOKIE is used, the code set is specified
inside the cookie. In this case, other code sets MAY be used as long
as the characters used in the MSG are exclusively visible characters
and spaces similar to those described above. For details, see the
syslog-international charset parameter. [or should we say "it *is*
UTF-8"?]
2.3 COOKIE
The cookie is an optional part of the message. It is used to identify
optional features inside a syslog message. A cookie can either be
assigned via IANA (COOKIE-IANA), be experimental but intended to be
vendor-neutral (COOKIE-EXPER) or be vendor-specific (COOKIE-VENDOR).
If there is a cookie present, it MUST start with the sequence "@#" at
the first character of the payload block. The COOKIE-ID must be at
least 4 characters, so that the overall minumum COOKIE size is 6
characters. These requirements makes it highly unlikely that a string
sequence in an "old-style" syslog message will be misinterpreted as a
cookie. However, there is a slight chance that this may happen. It
may also be deliberatly done as part of a malicous message. As such,
an implementation MUST NOT rely soley on the "@#" sequence to judge
whether it is a valid cookie or not. It MUST parse the whole cookie
to see if it is known or not and then act accordingly. Unknown
cookies should be treated as ordinary data and not be acted upon.
This implies that an implementation MUST not attempt to find further
cookies inside the MSG.
2.3.1 COOKIE-ID
The cookie ID uniquely identifies the cookie. It is a 4 to 6
character wide string of printable characters. It is case-sensitive.
The 4 character minimum size requirement is introduced to reduce the
likelyhood that a cookie is mistakenly being recognized. The
COOKIE-ID alone MUST NOT be used to detect a cookie. It can, however,
be handy for human discussion.
The COOKIE-ID MUST NOT begin with "V-" or "X-".
2.3.2 IANA and Experimental Cookies
These are vendor-neutral cookies. IANA-assigned cookie values have
undergone the concensus process and are well-defined. Experimental
cookies are for vendor-neutral functionality that is currently in
development. A syslog extension that is expected to be
vendor-specific SHOULD NOT use experimental cookies, it SHOULD use
vendor-specific cookies instead. As a rule of thumb, only cookies
used for functionalites discussed on IETF mailing lists should be
treated as vendor-neutral.
When new experiemental cookies are designed, they SHOULD use a
COOKIE-ID not yet assgined by IANA. This will facilitate the later
transistion as the experiemental COOKIED-ID could eventually be used
as an IANA COOKIE-ID once concensus has been reached and the
dicusssed functionality is mature enough.
2.3.3 Vendor specific Cookies
These cookie values are reserved for vendor extensions. A general
issue with namespaces and vendor extensions is that multiple vendors
may (accidently) decide to use the same value as their extension ID.
To avoid this, we prefix each vendor-specific COOKIE-ID with a
VENDORURI. This should be a long-lasting internet domain name that
the vendor owns.
An example: "Example Inc" has two software products called
"GreatestSyslog" and "EvenGreaterSyslog". It owns the domains
"example.com", "GreatestSyslog.example" and
"EvenGreaterSyslog.example". Now, "Example Inc" decides to introduce
a new cookie for exclusive use by "EvenGreaterSyslog". It is
recommended that the company's main domain is used for building the
vendor cookie. If they used the COOKIE-ID "MyTag", the complete
vendor cookie would look like this: "@#V-example.com-MyTag".
The VENDOR-URI is case-insensitve. However, it is good practice to
send it consistently in the same case. It SHOULD be sent in lower
case.
If cookies are nested, vendor cookies MUST be used on the innermost
layer, only.
####
I am interested in all feedback on this proposal. Most importantly I am
interested in feedback on the nesting of cookies, especially in respect
to undetected outer layers.
And, yes, I am trying to define the syslog format in ABNF, which I think
is very helpful when building parsers. As it looks, the whole ABNF for
the general message format as well as the syslog-internatonal extension
will fit within 2 pages.
Rainer
