syslog Working Group R. Gerhards
Internet-Draft Adiscon GmbH
Expires: August 22, 2005 February 18, 2005
The syslog Protocol
draft-ietf-syslog-protocol-10.txt
Status of this Memo
This document is an Internet-Draft and is subject to all provisions
of Section 3 of RFC 3667. By submitting this Internet-Draft, each
author represents that any applicable patent or other IPR claims of
which he or she is aware have been or will be disclosed, and any of
which he or she become aware will be disclosed, in accordance with
RFC 3668.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on August 22, 2005.
Copyright Notice
Copyright (C) The Internet Society (2005).
Abstract
This document describes the syslog protocol which is used to convey
event notification messages. This protocol utilizes a layered
architecture, which enables use of any number of transport protocols
for transmission of syslog messages. It also provides a message
format which allows vendor-specific extensions to be provided in a
structured way.
Gerhards Expires August 22, 2005 [Page 1]
Internet-Draft The syslog Protocol February 2005
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Conventions Used in This Document . . . . . . . . . . . . . . 5
3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 6
4. Basic Principles . . . . . . . . . . . . . . . . . . . . . . . 7
4.1 Example Deployment Scenarios . . . . . . . . . . . . . . . 7
5. Transport Layer Protocol . . . . . . . . . . . . . . . . . . . 9
5.1 Minimum Required Transport Mapping . . . . . . . . . . . . 9
6. Required syslog Format . . . . . . . . . . . . . . . . . . . . 10
6.1 Message Length . . . . . . . . . . . . . . . . . . . . . . 11
6.2 HEADER . . . . . . . . . . . . . . . . . . . . . . . . . . 11
6.2.1 VERSION . . . . . . . . . . . . . . . . . . . . . . . 11
6.2.2 FACILITY . . . . . . . . . . . . . . . . . . . . . . . 11
6.2.3 SEVERITY . . . . . . . . . . . . . . . . . . . . . . . 12
6.2.4 TIMESTAMP . . . . . . . . . . . . . . . . . . . . . . 12
6.2.5 HOSTNAME . . . . . . . . . . . . . . . . . . . . . . . 14
6.2.6 SENDER-NAME . . . . . . . . . . . . . . . . . . . . . 14
6.2.7 SENDER-INST . . . . . . . . . . . . . . . . . . . . . 14
6.2.8 MSGID . . . . . . . . . . . . . . . . . . . . . . . . 15
6.3 STRUCTURED-DATA . . . . . . . . . . . . . . . . . . . . . 15
6.3.1 SD-ELEMENT . . . . . . . . . . . . . . . . . . . . . . 15
6.3.2 SD-ID . . . . . . . . . . . . . . . . . . . . . . . . 15
6.3.3 SD-PARAM . . . . . . . . . . . . . . . . . . . . . . . 16
6.3.4 Change Control . . . . . . . . . . . . . . . . . . . . 16
6.3.5 Examples . . . . . . . . . . . . . . . . . . . . . . . 16
6.4 MSG . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
6.5 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 18
7. Structured Data IDs . . . . . . . . . . . . . . . . . . . . . 20
7.1 timeQuality . . . . . . . . . . . . . . . . . . . . . . . 20
7.1.1 tzKnown . . . . . . . . . . . . . . . . . . . . . . . 20
7.1.2 isSynced . . . . . . . . . . . . . . . . . . . . . . . 20
7.1.3 syncAccuracy . . . . . . . . . . . . . . . . . . . . . 20
7.1.4 Examples . . . . . . . . . . . . . . . . . . . . . . . 21
7.2 origin . . . . . . . . . . . . . . . . . . . . . . . . . . 21
7.2.1 ip . . . . . . . . . . . . . . . . . . . . . . . . . . 21
7.2.2 enterpriseID . . . . . . . . . . . . . . . . . . . . . 22
7.2.3 software . . . . . . . . . . . . . . . . . . . . . . . 22
7.2.4 swVersion . . . . . . . . . . . . . . . . . . . . . . 22
7.2.5 Example . . . . . . . . . . . . . . . . . . . . . . . 22
8. Security Considerations . . . . . . . . . . . . . . . . . . . 23
8.1 Diagnostic Logging . . . . . . . . . . . . . . . . . . . . 23
8.2 Control Characters . . . . . . . . . . . . . . . . . . . . 23
8.3 More than Maximum Message Length . . . . . . . . . . . . . 24
8.4 Message Truncation . . . . . . . . . . . . . . . . . . . . 24
8.5 Single Source to a Destination . . . . . . . . . . . . . . 24
8.6 Multiple Sources to a Destination . . . . . . . . . . . . 25
8.7 Multiple Sources to Multiple Destinations . . . . . . . . 25
Gerhards Expires August 22, 2005 [Page 2]
Internet-Draft The syslog Protocol February 2005
8.8 Replaying . . . . . . . . . . . . . . . . . . . . . . . . 25
8.9 Reliable Delivery . . . . . . . . . . . . . . . . . . . . 26
8.10 Message Integrity . . . . . . . . . . . . . . . . . . . . 26
8.11 Message Observation . . . . . . . . . . . . . . . . . . . 26
8.12 Misconfiguration . . . . . . . . . . . . . . . . . . . . . 27
8.13 Forwarding Loop . . . . . . . . . . . . . . . . . . . . . 27
8.14 Load Considerations . . . . . . . . . . . . . . . . . . . 27
8.15 Denial of Service . . . . . . . . . . . . . . . . . . . . 28
9. Notice to RFC Editor . . . . . . . . . . . . . . . . . . . . . 29
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . 30
10.1 Version . . . . . . . . . . . . . . . . . . . . . . . . . 30
10.2 SD-IDs . . . . . . . . . . . . . . . . . . . . . . . . . . 30
11. Authors and Working Group Chair . . . . . . . . . . . . . . 31
12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 32
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 33
13.1 Normative . . . . . . . . . . . . . . . . . . . . . . . . 33
13.2 Informative . . . . . . . . . . . . . . . . . . . . . . . 33
Author's Address . . . . . . . . . . . . . . . . . . . . . . . 34
A. Implementor Guidelines . . . . . . . . . . . . . . . . . . . . 35
A.1 Relationship with BSD Syslog . . . . . . . . . . . . . . . 35
A.2 Message Length . . . . . . . . . . . . . . . . . . . . . . 36
A.3 HEADER Parsing . . . . . . . . . . . . . . . . . . . . . . 37
A.4 SEVERITY Values . . . . . . . . . . . . . . . . . . . . . 38
A.5 TIME-SECFRAC Precision . . . . . . . . . . . . . . . . . . 38
A.6 Case Convention for Names . . . . . . . . . . . . . . . . 38
A.7 Leap Seconds . . . . . . . . . . . . . . . . . . . . . . . 39
A.8 Syslog Senders Without Knowledge of Time . . . . . . . . . 39
A.9 Additional Information on SENDER-INST . . . . . . . . . . 39
A.10 Notes on the time SD-ID . . . . . . . . . . . . . . . . . 40
A.11 Recommendation for Diagnostic Logging . . . . . . . . . . 40
Intellectual Property and Copyright Statements . . . . . . . . 42
Gerhards Expires August 22, 2005 [Page 3]
Internet-Draft The syslog Protocol February 2005
1. Introduction
This document describes a layered architecture for syslog. The goal
of this architecture is to separate message content from message
transport while enabling easy extensibility for each layer.
This document describes the standard format for syslog messages and
outlines the concept of transport mappings. It also describes
structured data elements, which can be used to transmit easy
parsable, structured information and allows for vendor extensions.
This document does not describe any storage format for syslog
messages. This is beyond of its scope and not necessary for system
interoperability.
Gerhards Expires August 22, 2005 [Page 4]
Internet-Draft The syslog Protocol February 2005
2. Conventions Used in This Document
The keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT",
and "MAY" that appear in this document are to be interpreted as
described in RFC2119 [5].
Gerhards Expires August 22, 2005 [Page 5]
Internet-Draft The syslog Protocol February 2005
3. Definitions
The following definitions will be used in this document:
o An application that can generate a syslog message will be called a
"sender".
o An application that can receive a syslog message will be called a
"receiver".
o An application that can receive syslog messages and forward them
to another receiver will be called a relay.
o An application that receives messages and does not relay them to
any other receiver will be called a collector.
A single application can have multiple roles at the same time.
Gerhards Expires August 22, 2005 [Page 6]
Internet-Draft The syslog Protocol February 2005
4. Basic Principles
The following principles apply to syslog communication:
o Syslog protocol does not provide for any mechanism of
acknowledgement of message delivery. Though some transports may
provide status information, conceptionally syslog is pure simplex
communication.
o Senders send messages to receivers with no knowledge of whether
they are collectors or relays.
o Senders may be configured to send the same message to multiple
receivers.
o Relays may send all or some of the messages that they receive to a
subsequent relay or collector. They may also store - or otherwise
locally process - some or all messages without forwarding. In
those cases, they are acting as both a collector and a relay.
o Relays may also generate their own messages and send them on to
subsequent relays or collectors. In that case it is acting as a
sender and a relay.
o Sender and receiver may reside on the same or different system.
4.1 Example Deployment Scenarios
Sample deployment scenarios are shown in Diagram 1. Other
arrangements of these examples are also acceptable. As noted, in the
following diagram relays may pass along all or some of the messages
that they receive along with passing along messages that they
internally generate. The boxes represent syslog-enabled
applications.
+------+ +---------+
|Sender|---->----|Collector|
+------+ +---------+
+------+ +-----+ +---------+
|Sender|---->----|Relay|---->----|Collector|
+------+ +-----+ +---------+
+------+ +-----+ +-----+ +---------+
|Sender|-->--|Relay|-->--..-->--|Relay|-->--|Collector|
+------+ +-----+ +-----+ +---------+
+------+ +-----+ +---------+
|Sender|---->----|Relay|---->----|Collector|
| |-+ +-----+ +---------+
+------+ \
\ +-----+ +---------+
+->--|Relay|---->----|Collector|
+-----+ +---------+
Gerhards Expires August 22, 2005 [Page 7]
Internet-Draft The syslog Protocol February 2005
+------+ +---------+
|Sender|---->----|Collector|
| |-+ +---------+
+------+ \
\ +-----+ +---------+
+->--|Relay|---->----|Collector|
+-----+ +---------+
+------+ +-----+ +---------+
|Sender|---->----|Relay|---->-------|Collector|
| |-+ +-----+ +---| |
+------+ \ / +---------+
\ +-----+ /
+->--|Relay|-->--/
+-----+
+------+ +-----+ +---------+
|Sender|---->----|Relay|---->----------|Collector|
| |-+ +-----+ +--| |
+------+ \ / +---------+
\ +--------+ /
\ |+------+| /
+->-||Relay ||->---/
|+------|| /
||Sender||->-/
|+------+|
+--------+
Diagram 1. Some possible syslog deployment scenarios.
Gerhards Expires August 22, 2005 [Page 8]
Internet-Draft The syslog Protocol February 2005
5. Transport Layer Protocol
This document does not specify any transport layer protocol.
Instead, it describes the format of a syslog message in a transport
layer independent way. This requires that syslog transports be
defined in other documents. The first transport is defined in [11]
and is consistent with the traditional UDP transport.
Any syslog transport protocol MUST NOT deliberately alter the syslog
message. If the transport protocol needs to perform temporary
transformations, these transformations MUST be reversed by the
transport protocol at the receiver, so that the upper layer will see
an exact copy of the message sent from the originator. Otherwise
cryptographic verifiers (like signatures) will be broken. Of course,
message alteration might occur due to transmission or similar errors.
Guarding against such alterations is not the scope of this
requirement.
5.1 Minimum Required Transport Mapping
All syslog implementations MUST support a UDP-based transport as
described in [11]. This requirement ensures interoperability between
all systems implementing the protocol described in this document.
Gerhards Expires August 22, 2005 [Page 9]
Internet-Draft The syslog Protocol February 2005
6. Required syslog Format
The syslog message has the following ABNF [7] definition:
SYSLOG-MSG = HEADER SP STRUCTURED-DATA SP MSG
HEADER = VERSION SP FACILITY SP SEVERITY SP
TIMESTAMP SP HOSTNAME SP SENDER-NAME SP
SENDER-INST SP MSGID
VERSION = NONZERO-DIGIT 0*2DIGIT
FACILITY = "0" / (NONZERO-DIGIT 0*9DIGIT)
; range 0..2147483647
SEVERITY = "0" / "1" / "2" / "3" / "4" / "5" /
"6" / "7"
HOSTNAME = 1*255PRINTUSASCII ; a FQDN
SENDER-NAME = 1*48PRINTUSASCII
SENDER-INST = "-" / 1*16PRINTUSASCII
MSGID = "-" / 1*32PRINTUSASCII
TIMESTAMP = FULL-DATE "T" FULL-TIME
FULL-DATE = DATE-FULLYEAR "-" DATE-MONTH "-" DATE-MDAY
DATE-FULLYEAR = 4DIGIT
DATE-MONTH = 2DIGIT ; 01-12
DATE-MDAY = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on
; month/year
FULL-TIME = PARTIAL-TIME TIME-OFFSET
PARTIAL-TIME = TIME-HOUR ":" TIME-MINUTE ":" TIME-SECOND
[TIME-SECFRAC]
TIME-HOUR = 2DIGIT ; 00-23
TIME-MINUTE = 2DIGIT ; 00-59
TIME-SECOND = 2DIGIT ; 00-58, 00-59, 00-60 based on leap
; second rules
TIME-SECFRAC = "." 1*6DIGIT
TIME-OFFSET = "Z" / TIME-NUMOFFSET
TIME-NUMOFFSET = ("+" / "-") TIME-HOUR ":" TIME-MINUTE
STRUCTURED-DATA = *SD-ELEMENT
SD-ELEMENT = "[" SD-ID 0*(1*SP SD-PARAM) "]"
SD-PARAM = PARAM-NAME "=" %d34 PARAM-VALUE %d34
SD-ID = SD-NAME
PARAM-NAME = SD-NAME
PARAM-VALUE = UTF-8-STRING ; characters '"', '\' and
; ']' MUST be escaped.
SD-NAME = 1*32OCTET ; VALID UTF-8 String
; except '=', SP, ']', %d34 (")
Gerhards Expires August 22, 2005 [Page 10]
Internet-Draft The syslog Protocol February 2005
MSG = UTF-8-STRING
UTF-8-STRING = *OCTET ; Any VALID UTF-8 String
OCTET = %d00..255
SP = %d32
PRINTUSASCII = %d33-126
NONZERO-DIGIT = "1" / "2" / "3" / "4" / "5" /
"6" / "7" / "8" / "9"
DIGIT = "0" / NONZERO-DIGIT
6.1 Message Length
A receiver MUST be able to accept messages up to and including 480
octets in length. For interoperability reasons, all receiver
implementations SHOULD be able to accept messages up to and including
2,048 octets in length.
If a receiver receives a message with a length larger than 2,048
octets, or larger than it supports, the receiver MAY discard the
message or truncate the payload.
6.2 HEADER
The character set used in the HEADER MUST be seven-bit ASCII in an
eight-bit field as described in RFC 2234 [7]. These are the ASCII
codes as defined in "USA Standard Code for Information Interchange"
ANSI.X3-4.1968 [1].
The header format is designed to provide some interoperability with
older BSD-based syslog. For details on this, see Appendix A.1.
6.2.1 VERSION
The VERSION field denotes the version of the syslog protocol
specification. The version number MUST be incremented for any new
syslog protocol specification that changes any part of the HEADER
format. This document uses a VERSION value of "1". The VERSION
values are IANA-assigned (Section 10.1). VERSION "1" does only and
exactly support the HEADER as described in this format. No
modifications to HEADER syntax or semantics can be made if VERSION 1
is used. If this is done, a new VERSION value MUST be assigned.
6.2.2 FACILITY
FACILITY is an integer in the range from 0 to 2,147,483,647. It can
be used for filtering by the receiver. It is RECOMMENDED that the
facility reflects a type of subsystem, something that a number of
Gerhards Expires August 22, 2005 [Page 11]
Internet-Draft The syslog Protocol February 2005
different messages might be issued from. So it is a kind of corase
group. There exist some traditional FACILITY code semantics for the
codes in the range from 0 to 23. These semantics are not closely
followed by all senders, and practice has shown that common semantics
for message categories are hard to establish. Therefore, no specific
semantics for FACILITY codes are specified or implied in this
document.
6.2.3 SEVERITY
The SEVERITY field is used to indicate the severity that the sender
of a message assigned to it. It contains one of these values:
Numerical Severity
Code
0 Emergency: system is unusable
1 Alert: action must be taken immediately
2 Critical: critical conditions
3 Error: error conditions
4 Warning: warning conditions
5 Notice: normal but significant condition
6 Informational: informational messages
7 Debug: debug-level messages
6.2.4 TIMESTAMP
The TIMESTAMP field is a formalized timestamp derived from RFC 3339
[10].
While RFC 3339 [10] makes allowances for multiple syntaxes, this
document places further restrictions. The TIMESTAMP MUST follow
these restrictions:
o The "T" and "Z" characters in this syntax MUST be upper case.
o Usage of the "T" character is REQUIRED.
The sender SHOULD include TIME-SECFRAC if its clock accuracy and
performance permit. The "time" SD-ID described in Section 7.1 allows
to specify accuracy and trustworthyness of the timestamp.
6.2.4.1 Syslog Senders Without Knowledge of Time
A syslog sender being incapable of obtaining system time MUST use the
following TIMESTAMP:
2000-01-01T00:00:60Z
Gerhards Expires August 22, 2005 [Page 12]
Internet-Draft The syslog Protocol February 2005
This TIMESTAMP is in the past and it shows a time that never existed,
because 1 January 2000 had no leap second. So it can never occur in
a valid syslog message of a time-aware sender. A receiver receiving
this TIMESTAMP MUST treat this value as an undefined date and time.
6.2.4.2 Examples
Example 1
1985-04-12T23:20:50.52Z
This represents 20 minutes and 50.52 seconds after the 23rd hour of
12 April 1985 in UTC.
Example 2
1985-04-12T19:20:50.52-04:00
This represents the same time as in example 1, but expressed in the
eastern US time zone (daylight savings time being observed).
Example 3
2003-10-11T22:14:15.003Z
This represents 11 October 2003 at 10:14:15pm, 3 milliseconds into
the next second. The timestamp is in UTC. The timestamp provides
millisecond resolution. The creator may have actually had a better
resolution, but by providing just three digits for the fractional
settings, it does not tell us.
Example 4
2003-08-24T05:14:15.000003-07:00
This represents 24 August 2003 at 05:14:15am, 3 microseconds into the
next second. The microsecond resolution is indicated by the
additional digits in TIME-SECFRAC. The timestamp indicates that its
local time is -7 hours from UTC. This timestamp might be created in
the US Pacific time zone during daylight savings time.
Example 5 - An Invalid TIMESTAMP
2003-08-24T05:14:15.000000003-07:00
This example is nearly the same as Example 4, but it is specifying
TIME-SECFRAC in nanoseconds. This will result in TIME-SECFRAC to be
longer than the allowed 6 digits, which invalidates it.
Gerhards Expires August 22, 2005 [Page 13]
Internet-Draft The syslog Protocol February 2005
6.2.5 HOSTNAME
The HOSTNAME field identifies the machine that originally sent the
syslog message.
The HOSTNAME field SHOULD contain the host name and the domain name
of the originator in the format specified in STD 13 [3]. This format
will be referred to in this document as a Fully Qualified Domain Name
(FQDN).
In practice, not all senders are able to provide the FQDN. As such,
other values MAY also be present in HOSTNAME. This protocol makes
provisions for using other values in such situations. A sender
SHOULD provide the most specific available value first. The order of
preference for the contents of the HOSTNAME field is as follows:
1. FQDN
2. Static IP address
3. Hostname
4. Dynamic IP address
5. "0:0:0:0:0:0:0:0"
If an IPv4 address is used, it MUST be in the format of the dotted
decimal notation as used in STD 13 [4]. If an IPv6 address is used,
a valid textual representation described in RFC 2373 [8], Section 2
MUST be used.
If a sender has multiple IP addresses, it SHOULD consistently use the
same value in the HOSTNAME field for as long as possible. This value
SHOULD be one of its actual IP addresses. If a sender is running on
a machine which has both statically and dynamically assigned
addresses, then that value SHOULD be from the statically assigned
addresses. As an alternative, the sender MAY use the IP address of
the interface that is used to send the message.
6.2.6 SENDER-NAME
The SENDER-NAME SHOULD identify the device or application that
generated the message. It is a string without further semantics. It
is intended for filtering messages on the receiver.
6.2.7 SENDER-INST
The SENDER-INST field SHOULD identify a specific instance of the
sender. It is RECOMMENDED that SENDER-INST contains the operating
system process ID, if that exists and is obtainable. No specific
format is REQUIRED.
Gerhards Expires August 22, 2005 [Page 14]
Internet-Draft The syslog Protocol February 2005
The dash ("-") is a reserved SENDER-INST field value that MUST only
be used to indicate an unidentified instance.
6.2.8 MSGID
The MSGID SHOULD identify the type of message. For example, a
Firewall might use the MSGID "TCPIN" for incoming TCP traffic and the
MSGID "TCPOUT" for outgoing TCP traffic. Messages with the same
MSGID should reflect events of the same semantics. The MSGID itself
is a string without further semantics. It is intended for filtering
messages on the receiver.
The dash ("-") is a reserved MSGID field value that MUST only be used
to indicate that the message has no specific ID.
6.3 STRUCTURED-DATA
STRUCTURED-DATA transports data in a well defined, easily parsable
and interpretable format. There are multiple usage scenarios. For
example, it may transport meta-information about the syslog message
or application-specific information such as traffic counters or IP
addresses.
STRUCTURED-DATA can contain zero, one, or multiple structured data
elements, which are referred to as "SD-ELEMENT" in this document.
The character set used in STRUCTURED-DATA MUST be UNICODE, encoded
using UTF-8 as specified in RFC 3629 [6]. A sender MAY issue any
valid UTF-8 sequence. A receiver MUST accept any valid UTF-8
sequence. It MUST NOT fail if control characters are present in the
STRUCTURED-DATA part.
If STRUCTURED-DATA is malformed, a diagnostic entry SHOULD be logged.
A receiver MAY ignore malformed STRUCTURED-DATA elements.
6.3.1 SD-ELEMENT
A SD-ELEMENT consists of a name and parameter name-value pairs. The
name is referred to as SD-ID. The name-value pairs are referred to
as "SD-PARAM".
6.3.2 SD-ID
IANA controls ALL SD-IDs without a hyphen ('-') in the second
character position. SD-IDs are case-sensitive and uniquely identify
the type and purpose of the SD-ELEMENT. Experimental or
vendor-specific SD-ID MUST start with "x-". Anything that doesn't is
managed by IANA. The same SD-ID MUST NOT exist more than once in a
Gerhards Expires August 22, 2005 [Page 15]
Internet-Draft The syslog Protocol February 2005
message.
6.3.3 SD-PARAM
Each SD-PARAM consist of a name, referred to as PARAM-NAME, and a
value, referred to as PARAM-VALUE.
PARAM-NAME is case-sensitive.
Inside PARAM-VALUE, the characters '"', '\' and ']' MUST be escaped.
This is necessary to avoid parsing errors. Escaping ']' would not
strictly be necessary but is REQUIRED by this specification to avoid
parser implementation errors. Each of these three characters MUST be
escaped as '\"', '\\' and '\]' respectively.
A backslash ('\') followed by none of the three described characters
is considered an invalid escape sequence. Upon reception of such an
invalid escape sequence, the receiver SHOULD replace the
two-character sequence with only the second character received. It
is RECOMMENDED that the receiver logs a diagnostic in this case.
A SD-PARAM MAY be repeated multiple times inside a SD-ELEMENT.
6.3.4 Change Control
Once SD-IDs and PARAM-NAMEs are defined in a specification and their
IANA assignment has been done, syntax and semantics of these objects
MUST NOT be altered. So they begin to exist with their initial
definition and are never allowed to change. Should a change to an
existing object be needed, a new one MUST be created. It is advised
to use a name the reflects the close relationship between the two
objects. For example, if the semantics of the "tzKnown" PARAM-NAME
were to be changed, a good name for the new element would be
"tzKnown2".
6.3.5 Examples
All examples in this section only show the structured data part of
the message. Examples should be considered to be on one line. They
are wrapped on multiple lines for readability purposes only. A
description is given after each example.
Example 1 - Valid
[x-exampleSDID iut="3" eventSource="Application"
eventID="1011"]
This example is a structured data element with an experimental SD-ID
Gerhards Expires August 22, 2005 [Page 16]
Internet-Draft The syslog Protocol February 2005
of type "x-exampleSDID" which has three parameters.
Example 2 - Valid
[x-exampleSDID iut="3" eventSource="Application"
eventID="1011"][x-examplePriority class="high"]
This is the same example as in 1, but with a second structured data
element. Please note that the structured data element immediately
follows the first one (there is no SP between them).
Example 3 - Invalid
[x-exampleSDID iut="3" eventSource="Application"
eventID="1011"] [x-examplePriority class="high"]
This is nearly the same example as 2, but it has a subtle error.
Please note that there is a SP character between the two structured
data elements ("]SP["). This is invalid. It will cause the
STRUCTURED-DATA field to end after the first element. The second
element will be interpreted as part of the MSG field.
Example 4 - Invalid
[ x-exampleSDID iut="3" eventSource="Application"
eventID="1011"][x-examplePriority class="high"]
This example again is nearly the same as 2. It has another subtle
error. Please note the SP character after the initial bracket. A
structured data element SD-ID MUST immediately follow the beginning
bracket, so the SP character invalidates the STRUCTURED-DATA. Thus,
the receiver MAY discard this message.
Example 5 - Valid
[sigSig ver="1" rsID="1234" ... signature="......"]
Example 5 is a valid example. It shows a hypothetical IANA assigned
SD-ID. Please note that the dots denote missing content, which has
been left out for brevity.
6.4 MSG
The MSG part contains a free-form message that provides information
about the event.
The character set used in MSG MUST be UNICODE, encoded using UTF-8 as
specified in RFC 3629 [6]. A sender MAY issue any valid UTF-8
Gerhards Expires August 22, 2005 [Page 17]
Internet-Draft The syslog Protocol February 2005
sequence. A receiver MUST accept any valid UTF-8 sequence. It MUST
NOT fail if control characters are present in the MSG part.
6.5 Examples
The following are examples of valid syslog messages. A description
of each example can be found below it. The examples are based on
similar examples from RFC 3164 [12] and may be familiar to readers.
Example 1
1 888 4 2003-10-11T22:14:15.003Z mymachine.example.com
su - ID47 'su root' failed for lonvick on /dev/pts/8
In this example, the VERSION is 1 and the FACILITY has the value of
888. The severity is 4 ("Warning" semantics). The message was
created on October, 11th 2003 at 10:14:15pm UTC, 3 milliseconds into
the next second. The message originated from a host that identifies
itself as "mymachine.example.com". The SENDER-NAME is "su" and the
SENDER-INST is unknown. The MSGID is "ID47". Note the two SP
characters following MSGID. The second SP character is the
STRUCTURED-DATA delimiter. It tells that no STRUCTURED-DATA is
present in this message. The MSG is "'su root' failed for
lonvick...".
Example 2
1 20 6 2003-08-24T05:14:15.000003-07:00 192.0.2.1
myproc 10 - %% It's time to make the do-nuts.
In this example, the VERSION is again 1. The FACILITY is within the
legacy syslog range (20). The severity is 6 ("Notice" semantics).
It was created on 24 August 2003 at 5:14:15am, with a -7 hour offset
from UTC, 3 microseconds into the next second. The HOSTNAME is
"192.0.2.1", so the sender did not know its FQDN and used the IPv4
address instead. The SENDER-NAME is "myproc" and the SENDER-INST is
"10" (for example this could be the UNIX PID). There is no specific
MSGID and this is indicated by the "-" in the MSGID field. The
message is "%% It's time to make the do-nuts.".
Example 3 - with STRUCTURED-DATA
1 888 4 2003-10-11T22:14:15.003Z mymachine.example.com
evntslog - ID47 [x-exampleSDID iut="3" eventSource="Application"
eventID="1011"] An application event log entry...
This example is modeled after example 1. However, this time it
contains STRUCTURED-DATA, a single element with the value
Gerhards Expires August 22, 2005 [Page 18]
Internet-Draft The syslog Protocol February 2005
"[x-exampleSDID iut="3" eventSource="Application" eventID="1011"]".
The MSG itself is "An application event log entry..."
Example 4 - STRUCTURED-DATA Only
1 888 4 2003-10-11T22:14:15.003Z mymachine.example.com
evntslog - ID47 [x-exampleSDID iut="3" eventSource="Application"
eventID="1011"][x-examplePriority class="high"]
This example shows a message with only STRUCTURED-DATA and no MSG
part. This is a valid message.
Gerhards Expires August 22, 2005 [Page 19]
Internet-Draft The syslog Protocol February 2005
7. Structured Data IDs
This section defines the initial IANA-registered SD-IDs. See
Section 6.3 for a definition of structured data elements. All SD-IDs
are optional.
7.1 timeQuality
The SD-ID "timeQuality" MAY be used by the original sender to
describe its notion of system time. This SD-ID SHOULD be written if
the sender is not properly synchronized with a reliable external time
source or if it does not know whether or not its time zone
information is correct. The main use of this structured data element
is to provide some information on the level of trust of the TIMESTAMP
described in Section 6.2.4.
7.1.1 tzKnown
The "tzKnown" parameter indicates if the original sender knows its
time zone. If it does so, the value "1" SHOULD be used. If the time
zone information is in doubt, the value "0" SHOULD be used. If the
sender knows its time zone but decides to emit time in UTC, the value
"1" SHOULD be used (because the time zone is known).
7.1.2 isSynced
The "isSynced" parameter indicates if the original sender is
synchronized to a reliable external time source, e.g. via NTP. If
the original sender is time synchronized, the value "1" SHOULD be
used. If not, the value "0" SHOULD be used.
7.1.3 syncAccuracy
The "syncAccuracy" parameter indicates how accurate the original
sender thinks the time synchronization it participates in is. It is
an integer describing the maximum number of microseconds that the
clock may be off between synchronization intervals.
If the value "0" is used for "isSynced", this parameter SHOULD NOT be
specified. If the value "1" is used for "isSynced" but the
"syncAccuracy" parameter is absent, a receiver SHOULD assume that the
time information provided is accurate enough to be considered
correct. The "syncAccuracy" parameter SHOULD ONLY be written if the
original sender actually has knowledge of the reliability of the
external time source. In practice, in most cases, it will gain this
in-depth knowledge through operator configuration.
Gerhards Expires August 22, 2005 [Page 20]
Internet-Draft The syslog Protocol February 2005
7.1.4 Examples
The following is an example of a system that knows that it does
neither know its time zone nor if it is being synchronized:
[timeQuality tzKnown="0" isSynced="0"]
With this information, the sender indicates that its time information
cannot be trusted. This may be a hint for the receiver to use its
local time instead of the message-provided TIMESTAMP for correlation
of multiple messages from different senders.
The following is an example of a system that knows its time zone and
knows that it is properly synchronized to a reliable external source:
[timeQuality tzKnown="1" isSynced="1"]
The following is an example of a system that knows both its time zone
and that it is externally synchronized. It also knows the accuracy
of the external synchronization:
[timeQuality tzKnown="1" isSynced="1" syncAccuracy="60000000"]
The difference between this and the previous example is that the
sender expects that its clock will be kept within 60 seconds of the
official time. So if the sender reports it is 9:00:00, it is no
earlier than 8:59:00 and no later then 9:01:00.
7.2 origin
The SD-ID "origin" MAY be used to indicate the origin of a syslog
message. The following parameters can be used. All parameters are
optional.
Specifying any of these parameter is primarily an aid to log
analyzers and similar applications.
7.2.1 ip
The "ip" parameter denotes the IP address that the sender knows it
had at the time of sending the message. It MUST contain the textual
representation of an IP address as outlined in Section 6.2.5.
This parameter can be used to provide additional identifying
information to what is present in the HOSTNAME field. It might be
especially useful if the host's IP address shall be included in the
message while the HOSTNAME field still shall contain the FQDN. It is
also useful to describe all IP addresses of a multihomed host.
Gerhards Expires August 22, 2005 [Page 21]
Internet-Draft The syslog Protocol February 2005
If a sender has multiple IP addresses, it MAY either use a single of
its IP addresses in the "ip" parameter or it MAY include multiple
"ip" parameters in a single "origin" structured data element.
7.2.2 enterpriseID
The "enterpriseID" parameter MUST be an 'SMI Network Management
Private Enterprise Code', maintained by IANA, whose prefix is
iso.org.dod.internet.private.enterprise (1.3.6.1.4.1). The number
which follows is unique and may be registered by an on-line form at
<http://www.iana.org/>. Only that number MUST be specified in the
"enterpriseID" parameter. The complete up-to-date list of Enterprise
Numbers is maintained by IANA at
<http://www.iana.org/assignments/enterprise-numbers>.
By specifying an enterpriseID, the vendor allows more specific
parsing of the message.
7.2.3 software
The "software" parameter uniquely identifies the software that
generated the message. If it is used, "enterpriseID" SHOULD also be
specified, so that a specific vendor's software can be identified.
The "software" parameter is not the same as the SENDER-NAME header
field. It always contains the name of the generating software while
SENDER-NAME can contain anything else, including an
operator-configured value.
The "software" parameter is a string. It MUST NOT be longer than 48
characters.
7.2.4 swVersion
The "swVersion" parameter uniquely identifies the version of the
software that generated the message. If it is used, the "software"
and "enterpriseID" parameters SHOULD be provided, too.
The "swVersion" parameter is a string. It MUST NOT be longer than 32
characters.
7.2.5 Example
The following is an example with multiple IP addresses:
[origin ip="192.0.2.1" ip="192.0.2.129"]
In this example, the sender indicates that it has two ip addresses,
one being 192.0.2.1 and the other one being 192.0.2.129.
Gerhards Expires August 22, 2005 [Page 22]
Internet-Draft The syslog Protocol February 2005
8. Security Considerations
8.1 Diagnostic Logging
This document recommends that an implementation writes a diagnostic
message to indicate unusual situations or other things noteworthy.
Diagnostic messages are a useful tool in finding configuration issues
as well as a system penetration.
Unfortunately, diagnostic logging can cause issues by itself, for
example if an attacker tries to create a denial of service condition
by willingly sending malformed messages that will lead to the
creation of diagnostic log entries. Due to sheer volume, the
resulting diagnostic log entries may exhaust system resources, e.g.
processing power, I/O capability or simply storage space. For
example, an attacker could flood a system with messages generating
diagnostic log entries after he has compromised a system. If the log
entries are stored in a circular buffer, the flood of diagnostic log
entries would eventually overwrite useful previous diagnostics.
Besides this risk, diagnostic message, if they occur too frequently,
can become meaningless. Common practice is to turn off diagnostic
logging if it is too verbose. This potentially removes important
diagnostic information which could aid the operator.
8.2 Control Characters
This document does not impose any restrictions on the MSG or
STRUCTURED-DATA content. As such, they MAY contain control
characters, including the NUL character.
In some programming languages (most notably C and C++), the NUL
(0x00) character traditionally has a special significance as string
terminator. Most, if not all, implementations of these languages
assume that a string will not extend beyond the first NUL character.
This is primarily a restriction of the supporting run-time libraries.
Please note that this restriction is often carried over to programs
and script languages written in those languages. As such, NUL
characters must be considered with great care and be properly
handled. An attacker may deliberately include NUL characters to hide
information after them. Incorrect handling of the NUL character may
also invalidate cryptographic checksums that are transmitted inside
the message.
Many popular text editors are also written in languages with this
restriction. This means that NUL characters should not be written to
a file in an unencoded way - otherwise it would potentially render
the file unreadable.
Gerhards Expires August 22, 2005 [Page 23]
Internet-Draft The syslog Protocol February 2005
The same is true for other control characters. For example,
deliberately included backspace characters may be used by an attacker
to render parts of the log message unreadable. Similar approaches
exist for almost all control characters.
Finally, invalid UTF-8 sequences may be used by an attacker to inject
ASCII control characters.
8.3 More than Maximum Message Length
The message length MAY exceed the RECOMMENDED maximum value specified
in Section 6. Various problems may result if a sender sends messages
with a greater length. Also, an attacker might deliberately
introduce very large messages. As such, it is vital that each
receiver performs the necessary sanity checks to ensure that it will
gracefully discard or truncate messages of larger sizes than it
supports.
8.4 Message Truncation
Messages over the minimum to be supported size may be discarded or
truncated by the receiver or interim systems. As such, vital log
information may be lost. Even messages within that size may be lost
if a non-reliable transport mapping is used.
In order to prevent information loss, messages should be less then
the minimum supported size outlined in Section 6.1. For best
performance and reliability, messages SHOULD be as small as possible.
Important information SHOULD be placed as early in the message as
possible because information at the begin of the message is less
likely to be discarded by a size-limited receiver.
In case a sender includes user-supplied data within a syslog message,
it should limit the size of that data. Otherwise, an attacker may
provide large data in the hope to exploit this potential weakness.
8.5 Single Source to a Destination
The syslog messages are usually presented (placed in a file,
displayed on the console, etc) in the order in which they are
received. This is not always in accordance with the sequence in
which they were generated. As they are transmitted across an IP
network, some out of order receipt should be expected. This may lead
to some confusion as messages may be received that would indicate
that a process has stopped before it was started. This is somewhat
rectified by the TIMESTAMP. However, the accuracy of the TIMESTAMP
may not always be sufficiently enough.
Gerhards Expires August 22, 2005 [Page 24]
Internet-Draft The syslog Protocol February 2005
It is desirable to use a transport with guaranteed delivery, if one
is available.
8.6 Multiple Sources to a Destination
In syslog, there is no concept of unified event numbering. Single
senders are free to include a sequence number within the structured
data, but that can hardly be coordinated between multiple senders.
In such cases, multiple senders may report that each one is sending
message number one. Again, this may be rectified somewhat by the
TIMESTAMP. As has been noted, however, even messages from a single
sender to a single collector may be received out of order. This
situation is compounded when there are several senders configured to
send their syslog messages to a single collector. Messages from one
sender may be delayed so the collector receives messages from another
sender first even though the messages from the first sender were
generated before the messages from the second. If there is no
sufficiently-precise timestamp or coordinated sequence number, then
the messages may be presented in the order in which they were
received which may give an inaccurate view of the sequence of actual
events.
8.7 Multiple Sources to Multiple Destinations
The plethora of configuration options available to the network
administrators may further skew the perception of the order of
events. It is possible to configure a group of senders to send
status messages -or other informative messages- to one collector,
while sending messages of relatively higher importance to another
collector. Additionally, the messages may be sent to different files
on the same collector. If the messages do not contain
sufficiently-precise timestamps from the source, it may be difficult
to order the messages if they are kept in different places. An
administrator may not be able to determine if a record in one file
occurred before or after a record in a different file. This may be
somewhat alleviated by placing marking messages with a timestamp into
all destination files. If these have coordinated timestamps, then
there will be some indication of the time of receipt of the
individual messages. As such, it is highly recommended to use the
best available precision in the TIMESTAMP and use automatic time
synchronization on each systems (as, for example, can be done via
NTP).
8.8 Replaying
Messages may be recorded and replayed at a later time. An attacker
may record a set of messages that indicate normal activity of a
machine. At a later time, that attacker may remove that machine from
Gerhards Expires August 22, 2005 [Page 25]
Internet-Draft The syslog Protocol February 2005
the network and replay the syslog messages to the collector. Even
with a TIMESTAMP field in the HEADER part, an attacker may record the
packets and could simply modify them to reflect the current time
before retransmitting them. The administrators may find nothing
unusual in the received messages and their receipt would falsely
indicate normal activity of the machine.
Cryptographically signing messages could prevent the alteration of
TIMESTAMPs and thus the replay attack.
8.9 Reliable Delivery
As there is no mechanism described within this document to ensure
delivery, and since the underlying transport may be lossey (e.g.
UDP), some messages may be lost. They may either be dropped through
network congestion, or they may be maliciously intercepted and
discarded. The consequences of the drop of one or more syslog
messages cannot be determined. If the messages are simple status
updates, then their non-receipt may either not be noticed, or it may
cause an annoyance for the system operators. On the other hand, if
the messages are more critical, then the administrators may not
become aware of a developing and potentially serious problem.
Messages may also be intercepted and discarded by an attacker as a
way to hide unauthorized activities.
It is RECOMMENDED to use a reliable transport mapping to prevent this
problem.
8.10 Message Integrity
Besides being discarded, syslog messages may be damaged in transit,
or an attacker may maliciously modify them. In such cases, the
original contents of the message will not be delivered to the
collector. Additionally, if an attacker is positioned between the
sender and collector of syslog messages, they may be able to
intercept and modify those messages while in-transit to hide
unauthorized activities.
8.11 Message Observation
While there are no strict guidelines pertaining to the MSG format,
most syslog messages are generated in human readable form with the
assumption that capable administrators should be able to read them
and understand their meaning. Neither the syslog protocol nor the
syslog application have mechanisms to provide confidentiality of the
messages in transit. In most cases passing clear-text messages is a
benefit to the operations staff if they are sniffing the packets off
of the wire. The operations staff may be able to read the messages
Gerhards Expires August 22, 2005 [Page 26]
Internet-Draft The syslog Protocol February 2005
and associate them with other events seen from other packets crossing
the wire to track down and correct problems. Unfortunately, an
attacker may also be able to observe the human-readable contents of
syslog messages. The attacker may then use the knowledge gained from
those messages to compromise a machine or do other damage.
8.12 Misconfiguration
Since there is no control information distributed about any messages
or configurations, it is wholly the responsibility of the network
administrator to ensure that the messages are actually going to the
intended recipient. Cases have been noted where senders were
inadvertently configured to send syslog messages to the wrong
receiver. In many cases, the inadvertent receiver may not be
configured to receive syslog messages and it will probably discard
them. In certain other cases, the receipt of syslog messages has
been known to cause problems for the unintended recipient. If
messages are not going to the intended recipient, then they cannot be
reviewed or processed.
Using a reliable transport mapping can guard against these problems.
8.13 Forwarding Loop
As it is shown in Figure 1, machines may be configured to relay
syslog messages to subsequent relays before reaching a collector. In
one particular case, an administrator found that he had mistakenly
configured two relays to forward messages with certain SEVERITY
values to each other. When either of these machines either received
or generated that type of message, it would forward it to the other
relay. That relay would, in turn, forward it back. This cycle did
cause degradation to the intervening network as well as to the
processing availability on the two devices. Network administrators
must take care to not cause such a death spiral.
8.14 Load Considerations
Network administrators must take the time to estimate the appropriate
size of the syslog receivers. An attacker may perform a Denial of
Service attack by filling the disk of the collector with false
messages. Placing the records in a circular file may alleviate this
but that has the consequence of not ensuring that an administrator
will be able to review the records in the future. Along this line, a
receiver or collector must have a network interface capable of
receiving all messages sent to it.
Administrators and network planners must also critically review the
network paths between the devices, the relays, and the collectors.
Gerhards Expires August 22, 2005 [Page 27]
Internet-Draft The syslog Protocol February 2005
Generated syslog messages should not overwhelm any of the network
links.
In order to reduce the impact of this issue, it is recommended to use
transports with guaranteed delivery.
8.15 Denial of Service
As with any system, an attacker may just overwhelm a receiver by
sending more messages to it than can be handled by the infrastructure
or the device itself. Implementors should attempt to provide
features that minimize this threat. Such as only receiving syslog
messages from known IP addresses.
Gerhards Expires August 22, 2005 [Page 28]
Internet-Draft The syslog Protocol February 2005
9. Notice to RFC Editor
This is a note to the RFC editor. This ID is submitted along with ID
draft-ietf-syslog-transport-udp and they cross-reference each other.
When RFC numbers are determined for each of these IDs, these
references will be updated to use the RFC numbers. This section will
be removed at that time.
Gerhards Expires August 22, 2005 [Page 29]
Internet-Draft The syslog Protocol February 2005
10. IANA Considerations
10.1 Version
IANA must maintain a registry of VERSION values as described in
Section 6.2.1.
For this document, IANA must register the VERSION "1". New VERSION
numbers must monotonically increment (the next VERSION will be "2")
and will be registered via the Specification Required method as
described in RFC 2434 [9].
10.2 SD-IDs
IANA must maintain a registry of Structured Data ID (SD-ID) values as
described in Section 7. These are the SD-IDs which do NOT have a
hyphen ("-") in the second character position.
New SD-ID values may be registered through the Specification Required
method as described in RFC 2434 [9].
For this document, IANA must register the SD-IDs "time" and "origin".
Gerhards Expires August 22, 2005 [Page 30]
Internet-Draft The syslog Protocol February 2005
11. Authors and Working Group Chair
The working group can be contacted via the mailing list:
syslog-sec@employees.org
The current Chair of the Working Group may be contacted at:
Chris Lonvick
Cisco Systems
Email: clonvick@cisco.com
The author of this draft is:
Rainer Gerhards
Email: rgerhards@adiscon.com
Phone: +49-9349-92880
Fax: +49-9349-928820
Adiscon GmbH
Mozartstrasse 21
97950 Grossrinderfeld
Germany
Gerhards Expires August 22, 2005 [Page 31]
Internet-Draft The syslog Protocol February 2005
12. Acknowledgments
The authors wish to thank Chris Lonvick, Jon Callas, Andrew Ross,
Albert Mietus, Anton Okmianski, Tina Bird, Devin Kowatch, David
Harrington, Sharon Chisholm and all other people who commented on
various versions of this proposal.
Gerhards Expires August 22, 2005 [Page 32]
Internet-Draft The syslog Protocol February 2005
13. References
13.1 Normative
[1] American National Standards Institute, "USA Code for
Information Interchange", ANSI X3.4, 1968.
[2] Postel, J., "Internet Protocol", STD 5, RFC 791, September
1981.
[3] Mockapetris, P., "Domain names - concepts and facilities",
STD 13, RFC 1034, November 1987.
[4] Mockapetris, P., "Domain names - implementation and
specification", STD 13, RFC 1035, November 1987.
[5] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997.
[6] Yergeau, F., "UTF-8, a transformation format of ISO 10646",
RFC 3629, November 2003.
[7] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 2234, November 1997.
[8] Hinden, R. and S. Deering, "IP Version 6 Addressing
Architecture", RFC 2373, July 1998.
[9] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA
Considerations Section in RFCs", BCP 26, RFC 2434, October
1998.
[10] Klyne, G. and C. Newman, "Date and Time on the Internet:
Timestamps", RFC 3339, July 2002.
[11] Okmianski, A., "Transmission of syslog messages over UDP",
RFC 9999, August 2004.
13.2 Informative
[12] Lonvick, C., "The BSD Syslog Protocol", RFC 3164, August 2001.
[13] Malkin, G., "Internet Users' Glossary", RFC 1983, August 1996.
Gerhards Expires August 22, 2005 [Page 33]
Internet-Draft The syslog Protocol February 2005
Author's Address
Rainer Gerhards
Adiscon GmbH
Mozartstrasse 21
Grossrinderfeld, BW 97950
Germany
Email: rgerhards@adiscon.com
Gerhards Expires August 22, 2005 [Page 34]
Internet-Draft The syslog Protocol February 2005
Appendix A. Implementor Guidelines
Information in this section is given as an aid to implementors.
While this information is considered to be helpful, it is not
normative. As such, an implementation is NOT REQUIRED to implement
it in order to claim compliance to this specification.
A.1 Relationship with BSD Syslog
While BSD syslog is in widespread use, its format has never been
formally standardized. In RFC 3164 [12] observed formats were
specified. However, RFC 3164 is an informal document and practice
shows that there are many different implementations.
Consequently, RFC 3164 mandates no specific elements inside a syslog
message. It defines that any message format destined to the syslog
UDP port must be treated as a syslog message - no matter what its
content is. However, in almost all cases observed in practice, a BSD
syslog message starts with a priority value, which is a number
between brackets. An example is "<133>". This document uses that
known convention to provide some minimal version detection. It has
deliberately changed the syslog message header so that it will never
contain a less-than sign as the first character of the message. This
has two advantages:
If an older receiver receives a message that does not start with a
less-than sign, it still assumes this is a valid syslog message.
However, it does not try to parse any header fields, at least if it
obeys to the rule outlined in RFC 3164. This prevents the receiver
from parsing the message invalidly. It should be noted, however,
that at least some of the older implementations will experience
problems if the message received is larger than 1024 octets. Most of
the implementations will truncate a message after the first 1024
octets. So it is wise to not send messages larger than 1024 octets
to receivers which are known to be older.
If a receiver compliant to this document receives a message generated
by a non-compliant, older, sender, it notices that the message does
not have a proper header and thus is not formatted according to this
document. This enables the receiver to take appropriate action.
Please also see the description on header parsing in Appendix A.3 for
more information on this scenario.
RFC 3164 mandates UDP as transport protocol for syslog. This
document places no restrictions on the transport.
RFC 3164 specifies relay behaviour. This document does not specify
relay behaviour. This might be done in a separate document.
Gerhards Expires August 22, 2005 [Page 35]
Internet-Draft The syslog Protocol February 2005
The PRI part in RFC 3164 is split into two fields - FACILITY and
SEVERITY - in this document. These new fields support the RFC 3164
values but also allow additional values.
The TIMESTAMP in RFC 3164 offers less precision and lacks the year
and timezone information. If a message formatted according to this
document needs to be reformatted to be RFC 3164 compliant, it is
suggested that the senders local time zone is used, and the time zone
information and the year being dropped. If a RFC 3164 formatted
message is received and must be transformed to be compliant to this
document, the current year should be added and the receivers time
zone be assumed.
The HOSTNAME in RFC 3164 is less specific, but this format is still
supported in this document as one of the alternate HOSTNAME
representations.
The MSG part of the message is defined as TAG and CONTENT in RFC
3164. In this document, MSG is what was called CONTENT in RFC 3164.
The TAG is now part of the header, but not as a single field. The
TAG has been split into SENDER-NAME, SENDER-INST and MSGID. This
does not totally resemble the usage of TAG, but provides the same
functionality for most of the cases.
In RFC 3164, STRUCTURED-DATA was not defined. If a message compliant
to this document contains STRUCTURED-DATA and must be reformatted
compliant to RFC 3164, the STRUCTURED-DATA simply becomes part of the
RFC 3164 CONTENT freeform text.
In general, this document tries to provide an easily parsable header
with clear field separations whereas traditional BSD syslog suffers
from some historically developed, hard to parse field seperation
rules.
A.2 Message Length
Implementors should note the message size limitations outlined in
Section 6.1 and try to keep the most important parts early in the
message (within the minimum guaranteed length). This ensures they
will be seen by the receiver even if it (or a relay on the message
path) truncates the message.
The reason syslog receivers must only support receiving up to and
including 480 octets has, among others, to do with difficult delivery
problems in a broken network. Syslog messages may use an UDP
transport mapping and have this 480 restriction to avoid session
overhead and message fragmentation. In a network being
troubleshooted, the likelihood of getting one single-packet message
Gerhards Expires August 22, 2005 [Page 36]
Internet-Draft The syslog Protocol February 2005
delivered successfully is higher than getting two message fragments
delivered successfully. So using a larger size may prevent the
operator from getting some critical information about the problem,
whereas keeping with that limit might get that information to the
operator. As such, messages intended for troubleshooting purposes
should not be larger than 480 octets. To further strengthen this
point, it has also been observed that some UDP implementations
generally do not support message sizes of more then 480 octets.
iChar = szVarName[2] - 'a'; There are other use cases where syslog
messages are used to transmit inherently lengthy information, e.g.
audit data. By not enforcing any upper limit on the message size,
syslog senders and receivers can be implemented with any size needed
and still be compliant to this document. In such cases, it is the
operator's responsibility to ensure that all components in a syslog
infrastructure support the required message sizes. Transport
mappings may recommend specific message size limits that must be
enforced.
Implementors are reminded that the message length is specified in
octets. There is a potentially large difference between the length
in characters and the length in octets for UTF-8 strings.
A.3 HEADER Parsing
The section recommends a message header parsing method based on the
VERSION field described in Section 6.2.1.
The receiver should check the VERSION. If the VERSION is within the
set of versions supported by the receiver, it should parse the
message according to the correct syslog protocol specification.
If the receiver does not support the specified VERSION, it should log
a diagnostic message. It should not parse beyond the VERSION field.
This is because the header format may have changed in a newer
version. The receiver should not try to process the message, but it
MAY try this if the administrator has configured the receiver to do
so. In the latter case, the results may be undefined. If the
administrator has configured the receiver to parse a non-supported
version, it should assume that these messages are legacy syslog
messages and parse and process them with respect to RFC 3164 [12].
To be precise, a receiver receiving an unknown VERSION number, or a
message without a valid VERSION, should discard the message by
default. However, the administrator may configure it to not discard
these messages. If that happens, the receiver may parse it according
to RFC 3164 [12]. The administrator may again override this setting
and configure the receiver to parse the messages in any way.
Gerhards Expires August 22, 2005 [Page 37]
Internet-Draft The syslog Protocol February 2005
The spirit behind these guidelines is that the administrator may
sometime need the power to allow overriding of version-specific
parsing, but this should be done in the most secure and reliable way.
Therefore, the receiver should use the appropriate defaults specified
above. This document is specific on this point because it is common
experience that parsing unknown formats often leads to security
issues.
A.4 SEVERITY Values
This section describes guidelines for using SEVERITY as outlined in
Section 6.2.3.
All implementations should try to assign the most appropriate
severity to their message. Most importantly, messages designed to
enable debugging or testing of software should be assigned severity
7. Severity 0 should be reserved for messages of very high
importance (like serious hardware failures or imminent power
failure). An implementation may use severities 0 and 7 for other
purposes if this is configured by the administrator.
Since severities are very subjective, the receiver should not assume
that all senders have the same definition of severity.
A.5 TIME-SECFRAC Precision
The TIMESTAMP described in Section 6.2.4 supports fractional seconds.
This provides ground for a very common coding error, where leading
zeros are removed from the fractional seconds. For example, the
TIMESTAMP "2003-10-11T22:13:14.003" may be erroneously written as
"2003-10-11T22:13:14.3". This would indicate 300 milliseconds
instead of the 3 milliseconds actually meant.
A.6 Case Convention for Names
Names are used at various places in this document, for example for
SD-IDs and PARAM-NAME. This document uses "camel case" consistently.
With that, each name begins with a lower case letter and each new
word starts with an upper case letter, but no hyphen or other
delimiter. An example of this is "timeQuality".
While an implementation is free to use any other case convention for
experimental names, but it is suggested that the case convention
outlined above is followed.
There is one exception from this convention in this document itself.
That is that experimental SD-IDs start with "x-", so they are
hyphenated. While this looks like an inconsistency, it was done
Gerhards Expires August 22, 2005 [Page 38]
Internet-Draft The syslog Protocol February 2005
because it is common practice (e.g. in SMTP) to prefix experimental
headers with "x-".
A.7 Leap Seconds
The TIMESTAMP described in Section 6.2.4 permits leap seconds, as
described in RFC 3339 [10].
The value "60" in the TIME-SECOND field is used to indicate a leap
second. This must not be misinterpreted. Implementors are advised
to replace the value "60" if seen in the header, with the value "59"
if it otherwise can not be processed, e.g. stored to a database. It
should not be converted to the first second of the next minute.
Please note that such a conversion, if done on the message text
itself, will cause cryptographic signatures to become invalid. As
such, it is suggested that the adjustment is not performed when the
plain message text is to be stored (e.g. for later verification of
signatures).
A.8 Syslog Senders Without Knowledge of Time
In Section 6.2.4.1, a specific TIMESTAMP for usage by senders without
knowledge of time is defined. This is done to support a special case
when a sender is not aware of time at all. It can be argued if such
a sender can actually be found in today's IT infrastructure.
However, discussion has indicated that those things may exist in
practice and as such there should be a guideline established for this
case.
However, an implementation SHOULD emit a valid TIMESTAMP if the
underlying operating system, programming system and hardware supports
the clock function. A proper TIMESTAMP should be emitted even if it
is difficult, but doable, to obtain the system time. The TIMESTAMP
described in Section 6.2.4.1 should only be used when it is actually
impossible to obtain time information. This rule should not be used
as an excuse for lazy implementations.
If a receiver receives that special TIMESTAMP, it should know that
the sender had no idea of what the time actually is and act
accordingly.
A.9 Additional Information on SENDER-INST
The objective behind SENDER-INST (Section 6.2.7) is to provide a
quick way to detect a new instance of the same sender. It must be
noted that this is not reliable as a second incarnation of a
SENDER-INST may actually be able to use the same SENDER-INST value as
the prior one. Properly used, the SENDER-INST can be helpful for
Gerhards Expires August 22, 2005 [Page 39]
Internet-Draft The syslog Protocol February 2005
analysis purposes.
A.10 Notes on the time SD-ID
It is recommended that the value of "0" be the default for the
"tzKnown" (Section 7.1.1) parameter. It should only be changed to
"1" after the administrator has specifically configured the time
zone. The value "1" may be used as the default if the underlying
operating system provides accurate time zone information. It is
still advised that the administrator explicitly acknowledges the
correctness of the time zone information.
It is important not to create a false impression of accuracy with the
time SD-ID (Section 7.1). A sender should only indicate a given
accuracy if it actually knows it is within these bounds. It is
generally assumed that the sender gains this in-depth knowledge
through operator configuration. As such, by default, an accuracy
should not be provided.
A.11 Recommendation for Diagnostic Logging
In Section 8.1, this document describes the need as well as potential
problems of diagnostic logging. In this section, a real-world
approach to useful diagnostic logging is recommended.
While this document recommends to write meaningful diagnostic logs,
it also recommends to allow an operator to limit the amount of
diagnostic logging. At least, an implementation should differentiate
between critical, informational and debugging diagnostic message.
Critical messages should only be issued in real critical states, e.g.
expected or happening malfunction of the application or parts of it.
A strong indication of an ongoing attack may also be considered
critical. As a guideline, there should be very few critical
messages. Informational messages should indicate all conditions not
fully correct, but still within the bounds of normal processing. A
diagnostic message logging the fact that a malformed message has been
received is a good example of this category. A debug diagnostic
message should not be needed during normal operation, but merely as a
tool for setting up or testing a system (which includes the process
of an operator configuring multiple syslog applications in a complex
environment). An application may decide to not provide any debugging
diagnostic messages.
An administrator should be able to configure the level for which
diagnostic messages will be written. Non-configured diagnostic
should not be written but discarded. An implementor may create as
many different levels of diagnostic messages as he see useful - the
above recommendation is just based on real-world experience of what
Gerhards Expires August 22, 2005 [Page 40]
Internet-Draft The syslog Protocol February 2005
is considered useful. Please note that experience shows that too
many levels of diagnostics typically do no good, because the typical
administrator may no longer be able to understand what each level
means.
Even with this categorization, a single diagnostic (or a set of them)
may frequently be generated when a specific condition exists (or a
system is being attacked). It will lead to the security issues
outlined at the beginning of Section 8.1. To solve this, it is
recommended that an implementation be allowed to set a limit of how
many duplicate diagnostic messages will be generated within a limited
amount of time. For example, an administrator should be able to
configure that groups of 50 identical messages are logged within a
specified time period with only a single diagnostic message. All
subsequent identical messages will be discarded until the next time
interval. It is usually considered good form to generate a
subsequent message identifying the number of duplicate messages that
were discarded. While this causes some information loss, it is
considered a good compromise between avoiding overruns and providing
most in-depth diagnostic information. An implementation offering
this feature should allow the administrator to configure the number
of duplicate messages as well as the time interval to whatever the
administrator thinks to be reasonable for his needs. It is up to the
implementor of what the term "duplicate" means. Some may decide that
only totally identical (in byte-to-byte comparison) messages are
actually duplicate, some other may say that a message which is of
identical type but with just some changed parameter (e.g. changed
remote host address) is also considered to be a duplicate. Both
approaches have their advantages and disadvantages. Probably, it is
best to also leave this configurable and allow the administrator to
set the parameters.
Gerhards Expires August 22, 2005 [Page 41]
Internet-Draft The syslog Protocol February 2005
Intellectual Property Statement
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Disclaimer of Validity
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Copyright Statement
Copyright (C) The Internet Society (2005). This document is subject
to the rights, licenses and restrictions contained in BCP 78, and
except as set forth therein, the authors retain all their rights.
Acknowledgment
Funding for the RFC Editor function is currently provided by the
Internet Society.
Gerhards Expires August 22, 2005 [Page 42]
