idnits 2.17.1 draft-ietf-syslog-protocol-17.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 14. -- Found old boilerplate from RFC 3978, Section 5.5 on line 1667. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1644. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1651. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1657. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. -- The document has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year -- The exact meaning of the all-uppercase expression 'NOT REQUIRED' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 14, 2006) is 6527 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: '2' is defined on line 1378, but no explicit reference was found in the text == Unused Reference: '17' is defined on line 1427, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. '1' ** Obsolete normative reference: RFC 2234 (ref. '7') (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 2434 (ref. '9') (Obsoleted by RFC 5226) ** Obsolete normative reference: RFC 3513 (ref. '10') (Obsoleted by RFC 4291) -- Possible downref: Non-RFC (?) normative reference: ref. '13' -- Possible downref: Non-RFC (?) normative reference: ref. '14' -- Possible downref: Non-RFC (?) normative reference: ref. '15' -- Obsolete informational reference (is this intentional?): RFC 3164 (ref. '16') (Obsoleted by RFC 5424) Summary: 6 errors (**), 0 flaws (~~), 5 warnings (==), 14 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 syslog Working Group R. Gerhards 3 Internet-Draft Adiscon GmbH 4 Expires: December 16, 2006 June 14, 2006 6 The syslog Protocol 7 draft-ietf-syslog-protocol-17.txt 9 Status of this Memo 11 By submitting this Internet-Draft, each author represents that any 12 applicable patent or other IPR claims of which he or she is aware 13 have been or will be disclosed, and any of which he or she becomes 14 aware will be disclosed, in accordance with Section 6 of BCP 79. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as Internet- 19 Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt. 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 This Internet-Draft will expire on December 16, 2006. 34 Copyright Notice 36 Copyright (C) The Internet Society (2006). 38 Abstract 40 This document describes the syslog protocol, which is used to convey 41 event notification messages. This protocol utilizes a layered 42 architecture, which allows the use of any number of transport 43 protocols for transmission of syslog messages. It also provides a 44 message format that allows vendor-specific extensions to be provided 45 in a structured way. 47 This document has been written with the spirit of traditional syslog 48 in mind. The reason for a new layered specification has arisen 49 because standardization efforts for reliable, and secure syslog 50 extensions suffer from the lack of a standards-track and transport 51 independent RFC. Without this document, each other standard needs to 52 define its own syslog packet format and transport mechanism, which 53 over time will introduce subtle compatibility issues. This document 54 tries to provide a foundation that syslog extensions can build on. 55 This layered architecture approach also provides a solid basis that 56 allows code to be written once for each syslog feature rather than 57 once for each transport. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 62 2. Conventions Used in This Document . . . . . . . . . . . . . . 5 63 3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 6 64 4. Basic Principles . . . . . . . . . . . . . . . . . . . . . . . 7 65 4.1. Example Deployment Scenarios . . . . . . . . . . . . . . . 7 66 5. Transport Layer Protocol . . . . . . . . . . . . . . . . . . . 9 67 5.1. Minimum Required Transport Mapping . . . . . . . . . . . . 9 68 6. Required syslog Format . . . . . . . . . . . . . . . . . . . . 10 69 6.1. Message Length . . . . . . . . . . . . . . . . . . . . . . 11 70 6.2. HEADER . . . . . . . . . . . . . . . . . . . . . . . . . . 11 71 6.2.1. PRI . . . . . . . . . . . . . . . . . . . . . . . . . 11 72 6.2.2. VERSION . . . . . . . . . . . . . . . . . . . . . . . 13 73 6.2.3. TIMESTAMP . . . . . . . . . . . . . . . . . . . . . . 14 74 6.2.4. HOSTNAME . . . . . . . . . . . . . . . . . . . . . . . 15 75 6.2.5. APP-NAME . . . . . . . . . . . . . . . . . . . . . . . 16 76 6.2.6. PROCID . . . . . . . . . . . . . . . . . . . . . . . . 16 77 6.2.7. MSGID . . . . . . . . . . . . . . . . . . . . . . . . 16 78 6.3. STRUCTURED-DATA . . . . . . . . . . . . . . . . . . . . . 17 79 6.3.1. SD-ELEMENT . . . . . . . . . . . . . . . . . . . . . . 17 80 6.3.2. SD-ID . . . . . . . . . . . . . . . . . . . . . . . . 17 81 6.3.3. SD-PARAM . . . . . . . . . . . . . . . . . . . . . . . 18 82 6.3.4. Change Control . . . . . . . . . . . . . . . . . . . . 19 83 6.3.5. Examples . . . . . . . . . . . . . . . . . . . . . . . 19 84 6.4. MSG . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 85 6.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 21 86 7. Structured Data IDs . . . . . . . . . . . . . . . . . . . . . 23 87 7.1. timeQuality . . . . . . . . . . . . . . . . . . . . . . . 23 88 7.1.1. tzKnown . . . . . . . . . . . . . . . . . . . . . . . 23 89 7.1.2. isSynced . . . . . . . . . . . . . . . . . . . . . . . 23 90 7.1.3. syncAccuracy . . . . . . . . . . . . . . . . . . . . . 23 91 7.1.4. Examples . . . . . . . . . . . . . . . . . . . . . . . 24 92 7.2. origin . . . . . . . . . . . . . . . . . . . . . . . . . . 24 93 7.2.1. ip . . . . . . . . . . . . . . . . . . . . . . . . . . 24 94 7.2.2. enterpriseId . . . . . . . . . . . . . . . . . . . . . 25 95 7.2.3. software . . . . . . . . . . . . . . . . . . . . . . . 25 96 7.2.4. swVersion . . . . . . . . . . . . . . . . . . . . . . 25 97 7.2.5. Example . . . . . . . . . . . . . . . . . . . . . . . 25 98 7.3. meta . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 99 7.3.1. sequenceId . . . . . . . . . . . . . . . . . . . . . . 26 100 7.3.2. sysUpTime . . . . . . . . . . . . . . . . . . . . . . 26 101 7.3.3. enc . . . . . . . . . . . . . . . . . . . . . . . . . 26 102 7.3.4. language . . . . . . . . . . . . . . . . . . . . . . . 26 103 8. Security Considerations . . . . . . . . . . . . . . . . . . . 28 104 8.1. UNICODE . . . . . . . . . . . . . . . . . . . . . . . . . 28 105 8.2. Control Characters . . . . . . . . . . . . . . . . . . . . 28 106 8.3. Message Truncation . . . . . . . . . . . . . . . . . . . . 29 107 8.4. Replaying . . . . . . . . . . . . . . . . . . . . . . . . 29 108 8.5. Reliable Delivery . . . . . . . . . . . . . . . . . . . . 29 109 8.6. Message Integrity . . . . . . . . . . . . . . . . . . . . 30 110 8.7. Message Observation . . . . . . . . . . . . . . . . . . . 30 111 8.8. Misconfiguration . . . . . . . . . . . . . . . . . . . . . 30 112 8.9. Forwarding Loop . . . . . . . . . . . . . . . . . . . . . 31 113 8.10. Load Considerations . . . . . . . . . . . . . . . . . . . 31 114 8.11. Denial of Service . . . . . . . . . . . . . . . . . . . . 31 115 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 116 9.1. VERSION . . . . . . . . . . . . . . . . . . . . . . . . . 32 117 9.2. SD-IDs . . . . . . . . . . . . . . . . . . . . . . . . . . 32 118 10. Authors and Working Group Chair . . . . . . . . . . . . . . . 34 119 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 35 120 12. Notes to the RFC Editor . . . . . . . . . . . . . . . . . . . 36 121 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 37 122 13.1. Normative . . . . . . . . . . . . . . . . . . . . . . . . 37 123 13.2. Informative . . . . . . . . . . . . . . . . . . . . . . . 38 124 Appendix A. Implementor Guidelines . . . . . . . . . . . . . . . 39 125 A.1. Relationship with BSD Syslog . . . . . . . . . . . . . . . 39 126 A.2. Message Length . . . . . . . . . . . . . . . . . . . . . . 40 127 A.3. Severity Values . . . . . . . . . . . . . . . . . . . . . 41 128 A.4. TIME-SECFRAC Precision . . . . . . . . . . . . . . . . . . 41 129 A.5. Case Convention for Names . . . . . . . . . . . . . . . . 41 130 A.6. Syslog Senders Without Knowledge of Time . . . . . . . . . 41 131 A.7. Additional Information on PROCID . . . . . . . . . . . . . 42 132 A.8. Notes on the timeQuality SD-ID . . . . . . . . . . . . . . 42 133 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 44 134 Intellectual Property and Copyright Statements . . . . . . . . . . 45 136 1. Introduction 138 This document describes a layered architecture for syslog. The goal 139 of this architecture is to separate message content from message 140 transport while enabling easy extensibility for each layer. 142 This document describes the standard format for syslog messages and 143 outlines the concept of transport mappings. It also describes 144 structured data elements, which can be used to transmit easily 145 parsable, structured information and allows for vendor extensions. 147 This document does not describe any storage format for syslog 148 messages. It is beyond of the scope of the syslog protocol and is 149 not necessary for system interoperability. 151 This document has been written with the spirit of RFC 3164 [16] in 152 mind. The reason for a new layered specification has arisen because 153 standardization efforts for reliable, and secure syslog extensions 154 suffer from the lack of a standards-track and transport independent 155 RFC. Without this document, each other standard would need to define 156 its own syslog packet format and transport mechanism which, over time 157 will introduce subtle compatibility issues. This document tries to 158 provide a foundation that syslog extensions can build on. This 159 layered architecture approach also provides a solid basis that allows 160 code to be written once instead of multiple times; once for each 161 syslog feature. 163 2. Conventions Used in This Document 165 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 166 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 167 document are to be interpreted as described in RFC 2119 [5]. 169 3. Definitions 171 The following definitions are used in this document: 173 o An application that can generate a syslog message is called a 174 "sender". 176 o An application that can receive a syslog message is called a 177 "receiver". 179 o An application that can receive syslog messages and forward them 180 to another receiver is called a "relay". 182 o An application that receives messages and does not relay them to 183 any other receiver is called a "collector". 185 A single application can have multiple roles at the same time. 187 4. Basic Principles 189 The following principles apply to syslog communication: 191 o The syslog protocol does not provide for any mechanism of 192 acknowledgement of message delivery. Though some transports may 193 provide status information, conceptionally, syslog is a pure 194 simplex communications protocol. 196 o Senders send messages to receivers with no knowledge of whether 197 they are collectors or relays. 199 o Senders may be configured to send the same message to multiple 200 receivers. 202 o Relays may send all or some of the messages that they receive to a 203 subsequent relay or collector. They may also store or otherwise 204 locally process some or all messages without forwarding. In the 205 case where a receiver stores some messages and relays some 206 messages, it is acting as both a collector and a relay. 208 o Relays may also generate their own messages and send them on to 209 subsequent relays or collectors. In that case they are acting as 210 senders and a relay. 212 o Sender and receiver may reside on the same or different systems. 214 4.1. Example Deployment Scenarios 216 Sample deployment scenarios are shown in Diagram 1. Other 217 arrangements of these examples are also acceptable. As noted, in the 218 following diagram, relays may pass along all or some of the messages 219 that they receive and also pass along messages that they generate 220 internally. The boxes represent syslog-enabled applications. 222 +------+ +---------+ 223 |Sender|---->----|Collector| 224 +------+ +---------+ 226 +------+ +-----+ +---------+ 227 |Sender|---->----|Relay|---->----|Collector| 228 +------+ +-----+ +---------+ 230 +------+ +-----+ +-----+ +---------+ 231 |Sender|-->--|Relay|-->--..-->--|Relay|-->--|Collector| 232 +------+ +-----+ +-----+ +---------+ 234 +------+ +-----+ +---------+ 235 |Sender|---->----|Relay|---->----|Collector| 236 | |-+ +-----+ +---------+ 237 +------+ \ 238 \ +-----+ +---------+ 239 +->--|Relay|---->----|Collector| 240 +-----+ +---------+ 242 +------+ +---------+ 243 |Sender|---->----|Collector| 244 | |-+ +---------+ 245 +------+ \ 246 \ +-----+ +---------+ 247 +->--|Relay|---->----|Collector| 248 +-----+ +---------+ 250 +------+ +-----+ +---------+ 251 |Sender|---->----|Relay|---->-------|Collector| 252 | |-+ +-----+ +---| | 253 +------+ \ / +---------+ 254 \ +-----+ / 255 +->--|Relay|-->--/ 256 +-----+ 257 +------+ +-----+ +---------+ 258 |Sender|---->----|Relay|---->----------|Collector| 259 | |-+ +-----+ +--| | 260 +------+ \ / +---------+ 261 \ +--------+ / 262 \ |+------+| / 263 +->-||Relay ||->---/ 264 |+------|| / 265 ||Sender||->-/ 266 |+------+| 267 +--------+ 269 Diagram 1. Some possible syslog deployment scenarios. 271 5. Transport Layer Protocol 273 This document does not specify any transport layer protocol. 274 Instead, it describes the format of a syslog message in a transport 275 layer independent way. This requires that syslog transports be 276 defined in other documents. The first transport is defined in [15] 277 and is consistent with the traditional UDP transport. This transport 278 is REQUIRED for interoperability as the UDP transport has 279 historically been used for the transmission of syslog messages. 281 Any syslog transport protocol MUST NOT deliberately alter the syslog 282 message. If the transport protocol needs to perform temporary 283 transformations, these transformations MUST be reversed by the 284 transport protocol at the receiver, so that the upper layer will see 285 an exact copy of the message sent from the originator. Otherwise 286 cryptographic verifiers (such as signatures) will be broken. Of 287 course, message alteration might occur due to transmission or similar 288 errors. Guarding against such alterations is not within the scope of 289 this effort. 291 5.1. Minimum Required Transport Mapping 293 All syslog implementations MUST support a UDP-based transport as 294 described in [15]. This ensures interoperability between all systems 295 implementing the protocol described in this document. 297 6. Required syslog Format 299 The syslog message has the following ABNF [7] definition: 301 SYSLOG-MSG = HEADER SP STRUCTURED-DATA [SP MSG] 303 HEADER = PRI VERSION SP TIMESTAMP SP HOSTNAME 304 SP APP-NAME SP PROCID SP MSGID 305 PRI = "<" PRIVAL ">" 306 PRIVAL = 1*3DIGIT ; range 0 .. 191 307 VERSION = NONZERO-DIGIT 0*2DIGIT 308 HOSTNAME = NILVALUE / 1*255PRINTUSASCII 310 APP-NAME = NILVALUE / 1*48PRINTUSASCII 311 PROCID = NILVALUE / 1*128PRINTUSASCII 312 MSGID = NILVALUE / 1*32PRINTUSASCII 314 TIMESTAMP = NILVALUE / FULL-DATE "T" FULL-TIME 315 FULL-DATE = DATE-FULLYEAR "-" DATE-MONTH "-" DATE-MDAY 316 DATE-FULLYEAR = 4DIGIT 317 DATE-MONTH = 2DIGIT ; 01-12 318 DATE-MDAY = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on 319 ; month/year 320 FULL-TIME = PARTIAL-TIME TIME-OFFSET 321 PARTIAL-TIME = TIME-HOUR ":" TIME-MINUTE ":" TIME-SECOND 322 [TIME-SECFRAC] 323 TIME-HOUR = 2DIGIT ; 00-23 324 TIME-MINUTE = 2DIGIT ; 00-59 325 TIME-SECOND = 2DIGIT ; 00-59 326 TIME-SECFRAC = "." 1*6DIGIT 327 TIME-OFFSET = "Z" / TIME-NUMOFFSET 328 TIME-NUMOFFSET = ("+" / "-") TIME-HOUR ":" TIME-MINUTE 330 STRUCTURED-DATA = NILVALUE / 1*SD-ELEMENT 331 SD-ELEMENT = "[" SD-ID *(SP SD-PARAM) "]" 332 SD-PARAM = PARAM-NAME "=" %d34 PARAM-VALUE %d34 333 SD-ID = SD-NAME 334 PARAM-NAME = SD-NAME 335 PARAM-VALUE = UTF-8-STRING ; characters '"', '\' and 336 ; ']' MUST be escaped. 337 SD-NAME = 1*32PRINTUSASCII 338 ; except '=', SP, ']', %d34 (") 340 MSG = MSG-ANY / MSG-UTF8 341 MSG-ANY = *OCTET ; not starting with BOM 342 MSG-UTF8 = BOM UTF-8-STRING 343 BOM = %xEF.BB.BF 344 UTF-8-STRING = *OCTET ; Any VALID UTF-8 String 345 ; "shortest form" MUST be used 347 OCTET = %d00-255 348 SP = %d32 349 PRINTUSASCII = %d33-126 350 NONZERO-DIGIT = %d49-57 351 DIGIT = %d48 / NONZERO-DIGIT 352 NILVALUE = "-" 354 6.1. Message Length 356 Syslog message size limits are dictated by the syslog transport 357 mapping in use. There is no upper limit per se. Each transport 358 mapping MUST define the minimum required message length support. Any 359 syslog transport mapping MUST support messages of up to and including 360 480 octets in length. 362 Any syslog receiver MUST be able to accept messages of up to and 363 including 480 octets in length. All receiver implementations SHOULD 364 be able to accept messages of up to and including 2048 octets in 365 length. Receivers MAY receive messages larger than 2048 octets in 366 length. If a receiver receives a message with a length larger than 367 it supports, the receiver MAY discard the message or truncate the 368 payload. 370 If a receiver truncates messages, the truncation MUST occur at the 371 end of the message. After trucation, the message MAY contain invalid 372 UTF-8 encoding or invalid STRUCTURED-DATA. 374 6.2. HEADER 376 The character set used in the HEADER MUST be seven-bit ASCII in an 377 eight-bit field as described in RFC 2234 [7]. These are the ASCII 378 codes as defined in "USA Standard Code for Information Interchange" 379 ANSI.X3-4.1968 [1]. 381 The header format is designed to provide some interoperability with 382 older BSD-based syslog. For details on this, see Appendix A.1. 384 6.2.1. PRI 386 The PRI part MUST have three, four, or five characters and will be 387 bound with angle brackets as the first and last characters. The PRI 388 part starts with a leading "<" ('less-than' character, %d60), 389 followed by a number, which is followed by a ">" ('greater-than' 390 character, %d62). The number contained within these angle brackets 391 is known as the Priority value (PRIVAL) and represents both the 392 Facility and Severity as described below. The Priority value 393 consists of one, two, or three decimal integers (ABNF DIGITS) using 394 values of %d48 (for "0") through %d57 (for "9"). 396 The Facilities and Severities are as follows: 398 Numerical Facility 399 Code 401 0 kernel messages 402 1 user-level messages 403 2 mail system 404 3 system daemons 405 4 security/authorization messages (note 1) 406 5 messages generated internally by syslogd 407 6 line printer subsystem 408 7 network news subsystem 409 8 UUCP subsystem 410 9 clock daemon (note 2) 411 10 security/authorization messages (note 1) 412 11 FTP daemon 413 12 NTP subsystem 414 13 log audit (note 1) 415 14 log alert (note 1) 416 15 clock daemon (note 2) 417 16 local use 0 (local0) 418 17 local use 1 (local1) 419 18 local use 2 (local2) 420 19 local use 3 (local3) 421 20 local use 4 (local4) 422 21 local use 5 (local5) 423 22 local use 6 (local6) 424 23 local use 7 (local7) 426 Table 1. syslog Message Facilities 428 The above semantics for Facility values are not normative but often 429 used. A receiver MUST NOT assume any specific semantics by default. 431 Each message Priority also has a decimal Severity level indicator. 432 These are described in the following table along with their numerical 433 values. 435 Numerical Severity 436 Code 438 0 Emergency: system is unusable 439 1 Alert: action must be taken immediately 440 2 Critical: critical conditions 441 3 Error: error conditions 442 4 Warning: warning conditions 443 5 Notice: normal but significant condition 444 6 Informational: informational messages 445 7 Debug: debug-level messages 447 Table 2. syslog Message Severities 449 The Priority value is calculated by first multiplying the Facility 450 number by 8 and then adding the numerical value of the Severity. For 451 example, a kernel message (Facility=0) with a Severity of Emergency 452 (Severity=0) would have a Priority value of 0. Also, a "local use 4" 453 message (Facility=20) with a Severity of Notice (Severity=5) would 454 have a Priority value of 165. In the PRI of a syslog message, these 455 values would be placed between the angle brackets as <0> and <165> 456 respectively. The only time a value of "0" follows the "<" is for 457 the Priority value of "0". Otherwise, leading "0"s MUST NOT be used. 459 6.2.1.1. Relation to Alarm MIB 461 The Alarm MIB RFC3877 [11] defines ITU perceived severities which are 462 useful to be able to relate to the syslog severities, particularly in 463 the case where alarms are being logged. The ITUPerceivedSeverity 464 corresponds to a syslog Severity as shown in table 2 below. 466 ITU Perceived Severity syslog SEVERITY 467 Critical Alert 468 Major Critical 469 Minor Error 470 Warning Warning 471 Indeterminate Notice 472 Cleared Notice 474 Table 3. ITUPerceivedSeverity to syslog SEVERITY mapping. 476 6.2.2. VERSION 478 The VERSION field denotes the version of the syslog protocol 479 specification. The version number MUST be incremented for any new 480 syslog protocol specification that changes any part of the HEADER 481 format. Changes include the addition or removal of fields, or a 482 change of syntax or semantics of existing fields. This document uses 483 a VERSION value of "1". The VERSION values are IANA-assigned 484 (Section 9.1) via the Standards Action method as described in RFC 485 2434 [9]. 487 6.2.3. TIMESTAMP 489 The TIMESTAMP field is a formalized timestamp derived from RFC 3339 490 [8]. 492 Whereas RFC 3339 [8] makes allowances for multiple syntaxes, this 493 document imposes further restrictions. The TIMESTAMP value MUST 494 follow these restrictions: 496 o The "T" and "Z" characters in this syntax MUST be upper case. 498 o Usage of the "T" character is REQUIRED. 500 o Leap seconds MUST NOT be used. 502 The sender SHOULD include TIME-SECFRAC if its clock accuracy and 503 performance permit. The "timeQuality" SD-ID described in Section 7.1 504 allows the sender to specify accuracy and trustworthiness of the 505 timestamp. 507 A syslog sender incapable of obtaining system time MUST use the 508 NILVALUE as TIMESTAMP. 510 6.2.3.1. Examples 512 Example 1 514 1985-04-12T23:20:50.52Z 516 This represents 20 minutes and 50.52 seconds after the 23rd hour of 517 12 April 1985 in UTC. 519 Example 2 521 1985-04-12T19:20:50.52-04:00 523 This represents the same time as in example 1, but expressed in the 524 Eastern US time zone (daylight savings time being observed). 526 Example 3 528 2003-10-11T22:14:15.003Z 530 This represents 11 October 2003 at 10:14:15pm, 3 milliseconds into 531 the next second. The timestamp is in UTC. The timestamp provides 532 millisecond resolution. The creator may have actually had a better 533 resolution, but by providing just three digits for the fractional 534 part of a second, it does not tell us. 536 Example 4 538 2003-08-24T05:14:15.000003-07:00 540 This represents 24 August 2003 at 05:14:15am, 3 microseconds into the 541 next second. The microsecond resolution is indicated by the 542 additional digits in TIME-SECFRAC. The timestamp indicates that its 543 local time is -7 hours from UTC. This timestamp might be created in 544 the US Pacific time zone during daylight savings time. 546 Example 5 - An Invalid TIMESTAMP 548 2003-08-24T05:14:15.000000003-07:00 550 This example is nearly the same as Example 4, but it is specifying 551 TIME-SECFRAC in nanoseconds. This results in TIME-SECFRAC being 552 longer than the allowed 6 digits, which invalidates it. 554 6.2.4. HOSTNAME 556 The HOSTNAME field identifies the machine that originally sent the 557 syslog message. 559 The HOSTNAME field SHOULD contain the host name and the domain name 560 of the originator in the format specified in STD 13 [3]. This format 561 is called a Fully Qualified Domain Name (FQDN) in this document. 563 In practice, not all senders are able to provide a FQDN. As such, 564 other values MAY also be present in HOSTNAME. This document makes 565 provisions for using other values in such situations. A sender 566 SHOULD provide the most specific available value first. The order of 567 preference for the contents of the HOSTNAME field is as follows: 569 1. FQDN 571 2. Static IP address 573 3. Hostname 575 4. Dynamic IP address 577 5. the NILVALUE 578 If an IPv4 address is used, it MUST be in the format of the dotted 579 decimal notation as used in STD 13 [4]. If an IPv6 address is used, 580 a valid textual representation described in RFC 3513 [10], Section 581 2.2, MUST be used. 583 Senders SHOULD consistently use the same value in the HOSTNAME field 584 for as long as possible. If the sender is multihomed, this value 585 SHOULD be one of its actual IP addresses. If a sender is running on 586 a machine that has both statically and dynamically assigned 587 addresses, then that value SHOULD be from the statically assigned 588 addresses. As an alternative, the sender MAY use the IP address of 589 the interface that is used to send the message. 591 The NILVALUE SHOULD only be used when the sender has no way to obtain 592 its real hostname. This situation is considered highly unlikely. 594 6.2.5. APP-NAME 596 The APP-NAME field SHOULD identify the device or application that 597 generated the message. It is a string without further semantics. It 598 is intended for filtering messages on the receiver. 600 The NILVALUE MAY be used when the sender has no idea of its APP-NAME 601 or cannot provide that information. It may be that a device may not 602 be able to provide that information either because of a local policy 603 decision, or because the information is not available, or not 604 applicable, on the device. 606 6.2.6. PROCID 608 The PROCID field SHOULD be used to provide the sender's process name 609 or process ID. The field does not have any specific syntax. 611 The NILVALUE MAY be used when the sender can not obtain its PROCID or 612 cannot provide it. 614 PROCID is primarily meaningful for analysis tools. Properly used, it 615 can enable log analyzers to detect which messages were generated by 616 the same sender process. For example, on a UNIX system the syslog 617 daemon (syslogd) might emit messages to the log. All messages logged 618 by the same syslogd process will bear the same PROCID. When the 619 syslog sender is restarted, the PROCID value MAY change. That may 620 enable the analysis script to detect the syslogd restart. 622 6.2.7. MSGID 624 The MSGID SHOULD identify the type of message. For example, a 625 firewall might use the MSGID "TCPIN" for incoming TCP traffic and the 626 MSGID "TCPOUT" for outgoing TCP traffic. Messages with the same 627 MSGID should reflect events of the same semantics. The MSGID itself 628 is a string without further semantics. It is intended for filtering 629 messages on the receiver. 631 The NILVALUE SHOULD be used when the sender does not intend to 632 provide a real MSGID. 634 6.3. STRUCTURED-DATA 636 STRUCTURED-DATA transports data in a well defined, easily parsable 637 and interpretable format. There are multiple usage scenarios. For 638 example, it may transport meta-information about the syslog message 639 or application-specific information such as traffic counters or IP 640 addresses. 642 STRUCTURED-DATA can contain zero, one, or multiple structured data 643 elements, which are referred to as "SD-ELEMENT" in this document. 645 In case of zero structured data elements, the STRUCTURED-DATA field 646 MUST contain the NILVALUE. 648 The character set used in STRUCTURED-DATA MUST be seven-bit ASCII in 649 an eight-bit field as described in RFC 2234 [7]. These are the ASCII 650 codes as defined in "USA Standard Code for Information Interchange" 651 ANSI.X3-4.1968 [1]. An exception is the PARAM-VALUE field (see 652 Section 6.3.3), in which UTF-8 encoding MUST be used. 654 A receiver MAY ignore malformed STRUCTURED-DATA elements. 656 6.3.1. SD-ELEMENT 658 A SD-ELEMENT consists of a name and parameter name-value pairs. The 659 name is referred to as SD-ID. The name-value pairs are referred to 660 as "SD-PARAM". 662 6.3.2. SD-ID 664 SD-IDs are case-sensitive and uniquely identify the type and purpose 665 of the SD-ELEMENT. The same SD-ID MUST NOT exist more than once in a 666 message. 668 There are two formats for SD-ID names: 670 o Names that do not contain an at-sign ("@", ABNF %d64) are reserved 671 to be assigned by IETF CONSENSUS. Currently, these are the names 672 defined in Section 7. Names of this format are only valid if they 673 are first registered with the IANA. Registered names MUST NOT 674 contain an at-sign ('@', ABNF %d64), an equal-sign ('=', ABNF 675 %d61), a closing brace (']', ABNF %d93), a quote-character ('"', 676 ABNF %d34), or whitespace, or control characters (ASCII code 127 677 and codes 32 or less). 679 o Anyone can define additional SD-IDs using names in the format 680 name@enterpriseID, e.g., "ourSDID@0". The format of the part 681 preceding the at-sign is not specified, however these names MUST 682 be printable US-ASCII strings, and MUST NOT contain the equal-sign 683 ('=', ABNF %d61), a closing brace (']', ABNF %d93), a quote- 684 character ('"', ABNF %d34), or whitespace, or control characters. 685 The part following the at-sign MUST be an enterpriseID as 686 specified in Section 7.2.2. 688 6.3.3. SD-PARAM 690 Each SD-PARAM consist of a name, referred to as PARAM-NAME, and a 691 value, referred to as PARAM-VALUE. 693 PARAM-NAME is case-sensitive. IANA controls all PARAM-NAMEs, with 694 the exception of those in SD-IDs whose names contain an at-sign. The 695 PARAM-NAME scope is within a specific SD-ID. Thus, equally-named 696 PARAM-NAME values contained in two different SD-IDs are not the same. 698 To support international characters, the PARAM-VALUE field MUST be 699 encoded using UTF-8. A sender MAY issue any valid UTF-8 sequence. A 700 receiver MUST accept any valid UTF-8 sequence in the "shortest form". 701 It MUST NOT fail if control characters are present in PARAM-VALUE. 702 It MAY modify messages containing control characters (e.g. by 703 escaping an octet with value 0 to "\0"). For the reasons outlined in 704 UNICODE TR36 [13], section 3.1, a sender MUST encode messages in the 705 "shortest form" and a receiver MUST NOT interpret messages in the 706 "non-shortest form". 708 Inside PARAM-VALUE, the characters '"' (ABNF %d34), '\' (ABNF %D92) 709 and ']' (ABNF %d93) MUST be escaped. This is necessary to avoid 710 parsing errors. Escaping ']' would not strictly be necessary but is 711 REQUIRED by this specification to avoid parser implementation errors. 712 Each of these three characters MUST be escaped as '\"', '\\' and '\]' 713 respectively. 715 A backslash ('\') followed by none of the three described characters 716 is considered an invalid escape sequence. Upon reception of such an 717 invalid escape sequence, the receiver MAY replace the two-character 718 sequence with only the second character received. Alternatively, it 719 MAY drop the message. 721 A SD-PARAM MAY be repeated multiple times inside a SD-ELEMENT. 723 6.3.4. Change Control 725 Once SD-IDs and PARAM-NAMEs are defined, syntax and semantics of 726 these objects MUST NOT be altered. Should a change to an existing 727 object be desired, a new SD-ID or PARAM-NAME MUST be created and the 728 old one remain unchanged. An exception is the addition of a new 729 OPTIONAL PARAM-NAME to an existing SD-ID, what MAY be done. 731 6.3.5. Examples 733 All examples in this section show only the structured data part of 734 the message. Examples should be considered to be on one line. They 735 are wrapped on multiple lines for readability purposes only. A 736 description is given after each example. 738 Example 1 - Valid 740 [exampleSDID@0 iut="3" eventSource="Application" 741 eventID="1011"] 743 This example is a structured data element with a non-IANA controlled 744 SD-ID of type "exampleSDID@0" which has three parameters. 746 Example 2 - Valid 748 [exampleSDID@0 iut="3" eventSource="Application" 749 eventID="1011"][examplePriority@0 class="high"] 751 This is the same example as in 1, but with a second structured data 752 element. Please note that the structured data element immediately 753 follows the first one (there is no SP between them). 755 Example 3 - Invalid 757 [exampleSDID@0 iut="3" eventSource="Application" 758 eventID="1011"] [examplePriority@0 class="high"] 760 This is nearly the same example as 2, but it has a subtle error. 761 Please note that there is a SP character between the two structured 762 data elements ("]SP["). This is invalid. It will cause the 763 STRUCTURED-DATA field to end after the first element. The second 764 element will be interpreted as part of the MSG field. 766 Example 4 - Invalid 768 [ exampleSDID@0 iut="3" eventSource="Application" 769 eventID="1011"][examplePriority@0 class="high"] 771 This example again is nearly the same as 2. It has another subtle 772 error. Please note the SP character after the initial bracket. A 773 structured data element SD-ID MUST immediately follow the beginning 774 bracket, so the SP character invalidates the STRUCTURED-DATA. Thus, 775 the receiver MAY discard this message. 777 Example 5 - Valid 779 [sigSig ver="1" rsID="1234" ... signature="..."] 781 Example 5 is a valid example. It shows a hypothetical IANA-assigned 782 SD-ID. Please note that the ellipses denote missing content, which 783 has been left out for brevity. 785 6.4. MSG 787 The MSG part contains a free-form message that provides information 788 about the event. 790 The character set used in MSG SHOULD be UNICODE, encoded using UTF-8 791 as specified in RFC 3629 [6]. If the sender can not encode the MSG 792 in Unicode, it MAY use any other encoding. 794 The sender SHOULD avoid octet values below 32 (the traditional US- 795 ASCII control character range except DEL). These values are legal, 796 but a receiver MAY modify these characters upon reception. For 797 example, it might change them into an escape sequence (e.g. value 0 798 may be changed to "\0"). A receiver SHOULD NOT modify any other 799 octet values. 801 If a sender encodes MSG in UTF-8, the string MUST start with the 802 Unicode byte order mask (BOM), which for UTF-8 is ABNF %xEF.BB.BF. 803 The sender SHOULD also include an "meta" SD-ID with an "enc" 804 parameter within the STRUCTURED-DATA. The sender MUST encode in the 805 "shortest form" and MAY use any valid UTF-8 sequence. 807 If a receiver receives MSG starting with a BOM, it MUST assume UTF-8 808 encoding. For the reasons outlined in UNICODE TR36 [13], section 809 3.1, a receiver MUST NOT interpret messages in the "non-shortest 810 form". It MUST NOT interpret invalid UTF-8 sequences. 812 If a sender does not encode MSG in UTF-8, the string MUST NOT start 813 with the Unicode BOM. If MSG is not encoded in UTF-8, the sender MAY 814 use any other encoding (including binary data). 816 If a receiver receives MSG not starting with a BOM, then the encoding 817 of the content is implementation specific and it is RECOMMENDED that 818 no assumption be made about the encoding of the content. 820 6.5. Examples 822 The following are examples of valid syslog messages. A description 823 of each example can be found below it. The examples are based on 824 similar examples from RFC 3164 [16] and may be familiar to readers. 825 The otherwise-unprintable Unicode BOM is represented as "BOM" in the 826 examples. 828 Example 1 830 <34>1 2003-10-11T22:14:15.003Z mymachine.example.com su - ID47 831 [meta enc="UTF-8"] BOM'su root' failed for lonvick on /dev/pts/8 833 In this example, the VERSION is 1 and the Facility has the value of 834 4. The severity is 2. The message was created on 11 October 2003 at 835 10:14:15pm UTC, 3 milliseconds into the next second. The message 836 originated from a host that identifies itself as 837 "mymachine.example.com". The APP-NAME is "su" and the PROCID is 838 unknown. The MSGID is "ID47". The MSG is "'su root' failed for 839 lonvick...", encoded in UTF-8. The encoding is defined by the BOM, 840 and also advertised in STRUCTURED-DATA. There is no STRUCTURED-DATA 841 present in the message, this is indicated by "-" in the STRUCTURED- 842 DATA field. The MSG is "'su root' failed for lonvick...". 844 Example 2 846 <165>1 2003-08-24T05:14:15.000003-07:00 192.0.2.1 847 myproc 8710 - - %% It's time to make the do-nuts. 849 In this example, the VERSION is again 1. The Facility is 20, the 850 Severity 5. The message was created on 24 August 2003 at 5:14:15am, 851 with a -7 hour offset from UTC, 3 microseconds into the next second. 852 The HOSTNAME is "192.0.2.1", so the sender did not know its FQDN and 853 used one of its IPv4 addresses instead. The APP-NAME is "myproc" and 854 the PROCID is "8710" (for example this could be the UNIX PID). There 855 is no specific MSGID and this is indicated by the "-" in the MSGID 856 field. The message is "%% It's time to make the do-nuts.". As the 857 Unicode BOM is missing, the receiver does not know the encoding of 858 the MSG part. 860 Example 3 - with STRUCTURED-DATA 862 <165>1 2003-10-11T22:14:15.003Z mymachine.example.com 863 evntslog - ID47 [exampleSDID@0 iut="3" eventSource= 864 "Application" eventID="1011"] BOMAn application 865 event log entry... 867 This example is modeled after example 1. However, this time it 868 contains STRUCTURED-DATA, a single element with the value 869 "[exampleSDID@0 iut="3" eventSource="Application" eventID="1011"]". 870 The MSG itself is "An application event log entry..." Please note 871 that the BOM at the beginning of MSG indicates UTF-8 encoding, even 872 when the informative meta SD-ID is not present. 874 Example 4 - STRUCTURED-DATA Only 876 <165>1 2003-10-11T22:14:15.003Z mymachine.example.com 877 evntslog - ID47 [exampleSDID@0 iut="3" eventSource= 878 "Application" eventID="1011"][examplePriority@0 879 class="high"] 881 This example shows a message with only STRUCTURED-DATA and no MSG 882 part. This is a valid message. 884 7. Structured Data IDs 886 This section defines the initial IANA-registered SD-IDs. See 887 Section 6.3 for a definition of structured data elements. All SD-IDs 888 defined here are OPTIONAL. 890 7.1. timeQuality 892 The SD-ID "timeQuality" MAY be used by the original sender to 893 describe its notion of system time. This SD-ID SHOULD be written if 894 the sender is not properly synchronized with a reliable external time 895 source or if it does not know whether or not its time zone 896 information is correct. The main use of this structured data element 897 is to provide some information on the level of trust it has in the 898 TIMESTAMP described in Section 6.2.3. All parameters are OPTIONAL. 900 7.1.1. tzKnown 902 The "tzKnown" parameter indicates whether the original sender knows 903 its time zone. If it does so, the value "1" MUST be used. If the 904 time zone information is in doubt, the value "0" MUST be used. If 905 the sender knows its time zone but decides to emit time in UTC, the 906 value "1" MUST be used (because the time zone is known). 908 7.1.2. isSynced 910 The "isSynced" parameter indicates whether the original sender is 911 synchronized to a reliable external time source, e.g., via NTP. If 912 the original sender is time synchronized, the value "1" MUST be used. 913 If not, the value "0" MUST be used. 915 7.1.3. syncAccuracy 917 The "syncAccuracy" parameter indicates how accurate the original 918 sender thinks its time synchronization is. It is an integer 919 describing the maximum number of microseconds that its clock may be 920 off between synchronization intervals. 922 If the value "0" is used for "isSynced", this parameter MUST NOT be 923 specified. If the value "1" is used for "isSynced" but the 924 "syncAccuracy" parameter is absent, a receiver MUST assume that the 925 time information provided is accurate enough to be considered 926 correct. The "syncAccuracy" parameter MUST be written only if the 927 original sender actually has knowledge of the reliability of the 928 external time source. In practice, in most cases, it will gain this 929 in-depth knowledge through operator configuration. 931 7.1.4. Examples 933 The following is an example of a system that does not know its time 934 zone nor whether it is being synchronized: 936 [timeQuality tzKnown="0" isSynced="0"] 938 With this information, the sender indicates that its time information 939 is unreliable. This may be a hint for the receiver to use its local 940 time instead of the message-provided TIMESTAMP for correlation of 941 multiple messages from different senders. 943 The following is an example of a system that knows its time zone and 944 knows that it is properly synchronized to a reliable external source: 946 [timeQuality tzKnown="1" isSynced="1"] 948 The following is an example of a system that knows both its time zone 949 and that it is externally synchronized. It also knows the accuracy 950 of the external synchronization: 952 [timeQuality tzKnown="1" isSynced="1" syncAccuracy="60000000"] 954 The difference between this and the previous example is that the 955 sender expects that its clock will be kept within 60 seconds of the 956 official time. Thus if the sender reports it is 9:00:00, it is no 957 earlier than 8:59:00 and no later then 9:01:00. 959 7.2. origin 961 The SD-ID "origin" MAY be used to indicate the origin of a syslog 962 message. The following parameters can be used. All parameters are 963 OPTIONAL. 965 Specifying any of these parameters is primarily an aid to log 966 analyzers and similar applications. 968 7.2.1. ip 970 The "ip" parameter denotes an IP address that the sender knows it had 971 at the time of sending the message. It MUST contain the textual 972 representation of an IP address as outlined in Section 6.2.4. 974 This parameter can be used to provide additional identifying 975 information to what is present in the HOSTNAME field. It might be 976 especially useful if the host's IP address is included in the message 977 while the HOSTNAME field still contains the FQDN. It is also useful 978 for describing all IP addresses of a multihomed host. 980 If a sender has multiple IP addresses, it MAY either list one of its 981 IP addresses in the "ip" parameter or it MAY include multiple "ip" 982 parameters in a single "origin" structured data element. 984 7.2.2. enterpriseId 986 The "enterpriseId" parameter MUST be a 'SMI Network Management 987 Private Enterprise Code', maintained by IANA, whose prefix is 988 iso.org.dod.internet.private.enterprise (1.3.6.1.4.1). The number 989 that follows is unique and may be registered by an on-line form at 990 . Only that number and any-enterprise assigned 991 ID below it MUST be specified in the "enterpriseId" parameter. If 992 sub-identifiers are used, they MUST be separated by periods and be 993 represented as decimal numbers ("9.1.30" and "11.2.3.7.5.12"). The 994 complete up-to-date list of Enterprise Numbers is maintained by IANA 995 at . 997 By specifying an enterpriseId, the vendor allows more specific 998 parsing of the message. 1000 7.2.3. software 1002 The "software" parameter uniquely identifies the software that 1003 generated the message. If it is used, "enterpriseId" SHOULD also be 1004 specified, so that a specific vendor's software can be identified. 1005 The "software" parameter is not the same as the APP-NAME header 1006 field. It always contains the name of the generating software, 1007 whereas APP-NAME can contain anything else, including an operator- 1008 configured value. 1010 The "software" parameter is a string. It MUST NOT be longer than 48 1011 characters. 1013 7.2.4. swVersion 1015 The "swVersion" parameter uniquely identifies the version of the 1016 software that generated the message. If it is used, the "software" 1017 and "enterpriseId" parameters SHOULD be provided, too. 1019 The "swVersion" parameter is a string. It MUST NOT be longer than 32 1020 characters. 1022 7.2.5. Example 1024 The following is an example with multiple IP addresses: 1026 [origin ip="192.0.2.1" ip="192.0.2.129"] 1027 In this example, the sender indicates that it has two ip addresses, 1028 one being 192.0.2.1 and the other one being 192.0.2.129. 1030 7.3. meta 1032 The SD-ID "meta" MAY be used to provide meta-information about the 1033 message. The following parameters can be used. All parameters are 1034 OPTIONAL. If the "meta" SD-ID is used, at least one parameter SHOULD 1035 be specified. 1037 7.3.1. sequenceId 1039 The "sequenceId" parameter tracks the sequence in which the sender 1040 sent the messages. It is an integer that MUST be set to 1 when the 1041 syslog function is started and MUST be increased with every message 1042 up to a maximum value of 2147483647. If that value is reached, the 1043 next message MUST be sent with a sequenceId of 1. 1045 7.3.2. sysUpTime 1047 The "sysUpTime" parameter MAY be used to include the SNMP "sysUpTime" 1048 parameter in the message. Its syntax and semantics are as defined in 1049 RFC 3418 [12]. 1051 As syslog does not support the SNMP "integer" syntax directly, the 1052 value MUST be represented as a decimal integer (no decimal point) 1053 using only the characters "0", "1", "2", "3", "4", "5", "6", "7", 1054 "8", and "9". 1056 7.3.3. enc 1058 The "enc" parameter SHOULD be specified if the MSG field is UTF-8 1059 encoded. If so, the sender SHOULD specify a meta SD-ID with 1060 'enc="UTF-8"' inside it. If the MSG is not UTF-8 encoded, the "enc" 1061 parameter MUST NOT be specified. 1063 Note that the "enc" parameter is just a secondary indicator for UTF-8 1064 encoding on the STRUCTURED-DATA level. The primary indication that 1065 the MSG is encoded in UTF-8 is that the Unicode BOM is included as it 1066 specified in MSG (Section 6.4). If a syslog message contains the 1067 "enc" parameter but does not contain the Unicode BOM, the receiver 1068 SHOULD NOT assume that the encoding is UTF-8. 1070 7.3.4. language 1072 The "language" parameter MAY be specified if the sender intends to 1073 convey information about the natural language used inside MSG. If it 1074 is specified, it MUST contain a two letter language identifier as 1075 defined in ISO 639 [14]. 1077 8. Security Considerations 1079 8.1. UNICODE 1081 This document uses UTF-8 encoding for the PARAM-VALUE and MSG fields. 1082 There are a number of security issues bound with UNICODE. Any 1083 implementor and operator is advised to review UNICODE TR36 [13] 1084 (UTR36) to learn about these issues. This document guards against 1085 the technical issues outlined in UTR36 by REQUIRING "shortest form" 1086 encoding both for senders and receivers. However, the visual 1087 spoofing due to character confusability still persists. This 1088 document tries to mimimize the effects of visual spoofing by allowing 1089 UNICODE only where local script is expected and needed. In all other 1090 fields, US-ASCII is REQUIRED. Also, the PARAM-VALUE and MSG fields 1091 should not be the primary source for identifying information, further 1092 reducing the risks associated with visual spoofing. 1094 8.2. Control Characters 1096 This document does not impose any restrictions on the MSG or PARAM- 1097 VALUE content. As such, they MAY contain control characters, 1098 including the NUL character. 1100 In some programming languages (most notably C and C++), the NUL 1101 (0x00) character traditionally has a special significance as string 1102 terminator. Most, if not all, implementations of these languages 1103 assume that a string will not extend beyond the first NUL character. 1104 This is primarily a restriction of the supporting run-time libraries. 1105 Please note that this restriction is often carried over to programs 1106 and script languages written in those languages. As such, NUL 1107 characters must be considered with great care and be properly 1108 handled. An attacker may deliberately include NUL characters to hide 1109 information after them. Incorrect handling of the NUL character may 1110 also invalidate cryptographic checksums that are transmitted inside 1111 the message. 1113 Many popular text editors are also written in languages with this 1114 restriction. Encoding NUL characters when writing to text files is 1115 advisable. If they are stored unencoded, the file can potentially 1116 become unreadable. 1118 The same is true for other control characters. For example, an 1119 attacker may deliberately include backspace characters to render 1120 parts of the log message unreadable. Similar issues exist for almost 1121 all control characters. 1123 Finally, invalid UTF-8 sequences may be used by an attacker to inject 1124 ASCII control characters. 1126 This specification permits a receiver to reformat control characters 1127 received. Among others, the security risks associated with control 1128 characters were an important driving force behind this restriction. 1129 In order to guarantee that the message text is kept unaltered, 1130 senders are advised to not send control characters. 1132 8.3. Message Truncation 1134 Message truncation can be misused by an attacker to hide vital log 1135 information. Messages over the minimum supported size may be 1136 discarded or truncated by the receiver or interim systems. As such, 1137 vital log information may be lost. 1139 In order to prevent information loss, messages should not be longer 1140 than the minimum maximum size required by Section 6.1. For best 1141 performance and reliability, messages should be as small as possible. 1142 Important information should be placed as early in the message as 1143 possible because information at the beginning of the message is less 1144 likely to be discarded by a size-limited receiver. 1146 A sender should limit the size of any user-supplied data within a 1147 syslog message. If it does not, an attacker may provide large data 1148 in hopes of exploiting a potential weakness. 1150 8.4. Replaying 1152 Messages may be recorded and replayed at a later time. An attacker 1153 may record a set of messages that indicate normal activity of a 1154 machine. At a later time, that attacker may remove that machine from 1155 the network and replay the syslog messages to the collector. Even 1156 with a TIMESTAMP field in the HEADER part, an attacker may record the 1157 packets and could simply modify them to reflect the current time 1158 before retransmitting them. The administrators may find nothing 1159 unusual in the received messages, and their receipt would falsely 1160 indicate normal activity of the machine. 1162 Cryptographically signing messages could prevent the alteration of 1163 TIMESTAMPs and thus the replay attack. 1165 8.5. Reliable Delivery 1167 Because there is no mechanism described within this document to 1168 ensure delivery, and the underlying transport may be unreliable 1169 (e.g., UDP), some messages may be lost. They may either be dropped 1170 through network congestion, or they may be maliciously intercepted 1171 and discarded. The consequences of dropping one or more syslog 1172 messages cannot be determined. If the messages are simple status 1173 updates, then their non-receipt may either not be noticed, or it may 1174 cause an annoyance for the system operators. On the other hand, if 1175 the messages are more critical, then the administrators may not 1176 become aware of a developing and potentially serious problem. 1177 Messages may also be intercepted and discarded by an attacker as a 1178 way to hide unauthorized activities. 1180 It may be desirable to use a transport with guaranteed delivery to 1181 mitigate congestion. 1183 It may also be desirable to include rate-limiting features in syslog 1184 senders. This can reduce potential congestion problems when message 1185 bursts happen. 1187 8.6. Message Integrity 1189 Besides being discarded, syslog messages may be damaged in transit, 1190 or an attacker may maliciously modify them. In such cases, the 1191 original contents of the message will not be delivered to the 1192 collector. Additionally, if an attacker is positioned between the 1193 sender and collector of syslog messages, they may be able to 1194 intercept and modify those messages while in-transit to hide 1195 unauthorized activities. 1197 8.7. Message Observation 1199 While there are no strict guidelines pertaining to the MSG format, 1200 most syslog messages are generated in human readable form with the 1201 assumption that capable administrators should be able to read them 1202 and understand their meaning. Neither the syslog protocol nor the 1203 syslog application have mechanisms to provide confidentiality for the 1204 messages in transit. In most cases passing clear-text messages is a 1205 benefit to the operations staff if they are sniffing the packets off 1206 of the wire. The operations staff may be able to read the messages 1207 and associate them with other events seen from other packets crossing 1208 the wire to track down and correct problems. Unfortunately, an 1209 attacker may also be able to observe the human-readable contents of 1210 syslog messages. The attacker may then use the knowledge gained from 1211 those messages to compromise a machine or do other damage. 1213 8.8. Misconfiguration 1215 Because there is no control information distributed about any 1216 messages or configurations, it is wholly the responsibility of the 1217 network administrator to ensure that the messages are actually going 1218 to the intended recipients. Cases have been noted where senders were 1219 inadvertently configured to send syslog messages to the wrong 1220 receivers. In many cases, the inadvertent receivers may not be 1221 configured to receive syslog messages and it will probably discard 1222 them. In certain other cases, the receipt of syslog messages has 1223 been known to cause problems for the unintended recipient. If 1224 messages are not going to the intended recipient, then they cannot be 1225 reviewed or processed. 1227 Using a reliable transport mapping can help identify these problems. 1229 8.9. Forwarding Loop 1231 As shown in Diagram 1, machines may be configured to relay syslog 1232 messages to subsequent relays before reaching a collector. In one 1233 particular case, an administrator found that he had mistakenly 1234 configured two relays to forward messages with certain SEVERITY 1235 values to each other. When either of these machines either received 1236 or generated that type of message, it would forward it to the other 1237 relay. That relay would, in turn, forward it back. This cycle did 1238 cause degradation to the intervening network as well as to the 1239 processing availability on the two devices. Network administrators 1240 must take care not to cause such a death spiral. 1242 8.10. Load Considerations 1244 Network administrators must take the time to estimate the appropriate 1245 capacity of the syslog receivers. An attacker may perform a Denial 1246 of Service attack by filling the disk of the collector with false 1247 messages. Placing the records in a circular file may alleviate this 1248 but that has the consequence of not ensuring that an administrator 1249 will be able to review the records in the future. Along this line, a 1250 receiver or collector must have a network interface capable of 1251 receiving all messages sent to it. 1253 Administrators and network planners must also critically review the 1254 network paths between the devices, the relays, and the collectors. 1255 Generated syslog messages should not overwhelm any of the network 1256 links. 1258 In order to reduce the impact of this issue, using transports with 1259 guaranteed delivery is recommended. 1261 8.11. Denial of Service 1263 As with any system, an attacker may just overwhelm a receiver by 1264 sending more messages to it than can be handled by the infrastructure 1265 or the device itself. Implementors should attempt to provide 1266 features that minimize this threat, such as only accepting syslog 1267 messages from known IP addresses. 1269 9. IANA Considerations 1271 9.1. VERSION 1273 IANA must maintain a registry of VERSION values as described in 1274 Section 6.2.2. Version numbers MUST be incremented for any new 1275 syslog protocol specification that changes any part of the HEADER. 1276 Changes include addition or removal of fields or a change of syntax 1277 or semantics of existing fields. 1279 VERSION numbers must be registered via the Standards Action method as 1280 described in RFC 2434 [9]. IANA must register the VERSIONs shown in 1281 table 4 below. 1283 VERSION FORMAT 1284 1 according to this document 1286 Table 4. IANA-registered VERSIONs. 1288 9.2. SD-IDs 1290 IANA must maintain a registry of Structured Data ID (SD-ID) values 1291 together with their associated PARAM-NAME values as described in 1292 Section 7. 1294 New SD-ID and new PARAM-NAME values must be registered through the 1295 IETF CONSENSUS method as described in RFC 2434 [9]. 1297 Once SD-IDs and SD-PARAMs are defined, syntax and semantics of these 1298 objects MUST NOT be altered. Should a change to an existing object 1299 be desired, a new SD-ID or SD-PARAM MUST be created and the old one 1300 remain unchanged. 1302 A provision is made here for locally extensible names. The IANA will 1303 not register, and will not control names with the at-sign (ABNF %d64) 1304 in them. 1306 IANA must register the SD-IDs and PARAM-NAMEs shown in table 5 below. 1308 SD-ID PARAM-NAME 1309 timeQuality OPTIONAL 1310 tzKnown OPTIONAL 1311 isSynced OPTIONAL 1312 syncAccuracy OPTIONAL 1314 origin OPTIONAL 1315 ip OPTIONAL 1316 enterpriseId OPTIONAL 1317 software OPTIONAL 1318 swVersion OPTIONAL 1320 meta OPTIONAL 1321 sequenceId OPTIONAL 1322 sysUpTime OPTIONAL 1323 enc OPTIONAL 1324 language OPTIONAL 1326 Table 5. IANA-registered SD-IDs and their PARAM-NAMEs. 1328 10. Authors and Working Group Chair 1330 The working group can be contacted via the mailing list: 1332 syslog-sec@employees.org 1334 The current Chairs of the Working Group may be contacted at: 1336 Chris Lonvick 1337 Cisco Systems 1338 Email: clonvick@cisco.com 1340 David Harrington 1341 Email: dbharrington@comcast.net 1343 The author of this draft is: 1345 Rainer Gerhards 1346 Email: rgerhards@adiscon.com 1348 Phone: +49-9349-92880 1349 Fax: +49-9349-928820 1351 Adiscon GmbH 1352 Mozartstrasse 21 1353 97950 Grossrinderfeld 1354 Germany 1356 11. Acknowledgments 1358 The authors wish to thank Chris Lonvick, Jon Callas, Andrew Ross, 1359 Albert Mietus, Anton Okmianski, Tina Bird, Devin Kowatch, David 1360 Harrington, Sharon Chisholm, Richard Graveman, Tom Petch, Dado 1361 Colussi, Clement Mathieu, Didier Dalmasso, and all other people who 1362 commented on various versions of this proposal. 1364 12. Notes to the RFC Editor 1366 This is a note to the RFC editor. This ID is submitted along with 1367 draft-ietf-syslog-transport-udp. These documents cross-reference 1368 each other. When RFC numbers are determined for each of these IDs, 1369 replace XXXX with the proper RFC number and remove this note. 1371 13. References 1373 13.1. Normative 1375 [1] American National Standards Institute, "USA Code for 1376 Information Interchange", ANSI X3.4, 1968. 1378 [2] Postel, J., "Internet Protocol", STD 5, RFC 791, 1379 September 1981. 1381 [3] Mockapetris, P., "Domain names - concepts and facilities", 1382 STD 13, RFC 1034, November 1987. 1384 [4] Mockapetris, P., "Domain names - implementation and 1385 specification", STD 13, RFC 1035, November 1987. 1387 [5] Bradner, S., "Key words for use in RFCs to Indicate Requirement 1388 Levels", BCP 14, RFC 2119, March 1997. 1390 [6] Yergeau, F., "UTF-8, a transformation format of ISO 10646", 1391 STD 63, RFC 3629, November 2003. 1393 [7] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1394 Specifications: ABNF", RFC 2234, November 1997. 1396 [8] Klyne, G. and C. Newman, "Date and Time on the Internet: 1397 Timestamps", RFC 3339, July 2002. 1399 [9] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA 1400 Considerations Section in RFCs", BCP 26, RFC 2434, 1401 October 1998. 1403 [10] Hinden, R. and S. Deering, "Internet Protocol Version 6 (IPv6) 1404 Addressing Architecture", RFC 3513, April 2003. 1406 [11] Chisholm, S. and D. Romascanu, "Alarm Management Information 1407 Base (MIB)", RFC 3877, September 2004. 1409 [12] Presuhn, R., "Management Information Base (MIB) for the Simple 1410 Network Management Protocol (SNMP)", STD 62, RFC 3418, 1411 December 2002. 1413 [13] Davis, M. and M. Suignard, "UNICODE Security Considerations", 1414 July 2005, . 1416 [14] International Organization for Standardization, "Code for the 1417 representation of names of languages", ISO Standard 639-1:2002, 1418 July 2002. 1420 [15] Okmianski, A., "Transmission of syslog messages over UDP", 1421 RFC XXXX, August 2004. 1423 13.2. Informative 1425 [16] Lonvick, C., "The BSD Syslog Protocol", RFC 3164, August 2001. 1427 [17] Malkin, G., "Internet Users' Glossary", RFC 1983, August 1996. 1429 Appendix A. Implementor Guidelines 1431 Information in this section is given as an aid to implementors. 1432 While this information is considered to be helpful, it is not 1433 normative. As such, an implementation is NOT REQUIRED to follow it 1434 in order to claim compliance to this specification. 1436 A.1. Relationship with BSD Syslog 1438 While BSD syslog is in widespread use, its format has never been 1439 formally standardized. In RFC 3164 [16] observed formats were 1440 specified. However, RFC 3164 is an INFORMATIONAL RFC, and practice 1441 shows that there are many different implementations. Research during 1442 creation of this document showed that there is very little in common 1443 between different syslog implementations on different platforms. The 1444 only thing that all of them agree upon is that messages start with 1445 "<" PRIVAL ">". Other than that, legacy syslog messages are not 1446 formatted in a consistent way. Consequently, RFC 3164 mandates no 1447 specific elements inside a syslog message. It states that any 1448 message destined to the syslog UDP port must be treated as a syslog 1449 message, no matter what its format or content is. 1451 This document retains the PRI value syntax and semantics. This will 1452 allow legacy syslog implementation to put messages generated by 1453 senders compliant to this specification into the right bins. 1455 RFC 3164 mandates UDP as transport protocol for syslog. This 1456 document places no restrictions on the transport. 1458 RFC 3164 specifies relay behavior. This document does not specify 1459 relay behavior. This might be done in a separate document. 1461 The TIMESTAMP in RFC 3164 offers less precision and lacks the year 1462 and timezone information. If a message formatted according to this 1463 document needs to be reformatted to be RFC 3164 compliant, it is 1464 suggested that the sender's local time zone be used, and the time 1465 zone information and the year be dropped. If a RFC 3164 formatted 1466 message is received and must be transformed to be compliant to this 1467 document, the current year should be added and the receiver's time 1468 zone be assumed. 1470 The HOSTNAME in RFC 3164 is less specific, but this format is still 1471 supported in this document as one of the alternate HOSTNAME 1472 representations. 1474 The MSG part of the message is defined as TAG and CONTENT in RFC 1475 3164. In this document, MSG is what was called CONTENT in RFC 3164. 1476 The TAG is now part of the header, but not as a single field. The 1477 TAG has been split into APP-NAME, PROCID, and MSGID. This does not 1478 totally resemble the usage of TAG, but provides the same 1479 functionality for most of the cases. 1481 In RFC 3164, STRUCTURED-DATA was not defined. If a message compliant 1482 with this document contains STRUCTURED-DATA and must be reformatted 1483 to be compliant with RFC 3164, the STRUCTURED-DATA simply becomes 1484 part of the RFC 3164 CONTENT free-form text. 1486 In general, this document tries to provide an easily parsable header 1487 with clear field separations whereas traditional BSD syslog suffers 1488 from some historically developed, hard to parse field separation 1489 rules. 1491 A.2. Message Length 1493 Implementors should note the message size limitations outlined in 1494 Section 6.1 and try to keep the most important parts early in the 1495 message (within the minimum guaranteed length). This ensures they 1496 will be seen by the receiver even if it (or a relay on the message 1497 path) truncates the message. 1499 The reason syslog receivers must only support receiving up to and 1500 including 480 octets has, among other things, to do with difficult 1501 delivery problems in a broken network. Syslog messages may use a UDP 1502 transport mapping with this 480 octet restriction to avoid session 1503 overhead and message fragmentation. In a network with problems, the 1504 likelihood of getting one single-packet message delivered 1505 successfully is higher than getting two message fragments delivered 1506 successfully. Therefore using a larger size may prevent the operator 1507 from getting some critical information about the problem, whereas 1508 using small messages might get that information to the operator. As 1509 such, messages intended for troubleshooting purposes should not be 1510 larger than 480 octets. To further strengthen this point, it has 1511 also been observed that some UDP implementations generally do not 1512 support message sizes of more then 480 octets. 1514 There are other use cases where syslog messages are used to transmit 1515 inherently lengthy information, e.g. audit data. By not enforcing 1516 any upper limit on the message size, syslog senders and receivers can 1517 be implemented with any size needed and still be compliant with this 1518 document. In such cases, it is the operator's responsibility to 1519 ensure that all components in a syslog infrastructure support the 1520 required message sizes. Transport mappings may recommend specific 1521 message size limits that must be enforced. 1523 Implementors are reminded that the message length is specified in 1524 octets. There is a potentially large difference between the length 1525 in characters and the length in octets for UTF-8 strings. 1527 It must be noted that the IPv6 MTU is about 2.5 times 480. An 1528 implementation targeted towards an IPv6-only environment might thus 1529 assume this as a larger minimum size. 1531 A.3. Severity Values 1533 This section describes guidelines for using Severity as outlined in 1534 Section 6.2.1. 1536 All implementations should try to assign the most appropriate 1537 severity to their message. Most importantly, messages designed to 1538 enable debugging or testing of software should be assigned severity 1539 7. Severity 0 should be reserved for messages of very high 1540 importance (like serious hardware failures or imminent power 1541 failure). An implementation may use severities 0 and 7 for other 1542 purposes if this is configured by the administrator. 1544 Because severities are very subjective, a receiver should not assume 1545 that all senders have the same definition of severity. 1547 A.4. TIME-SECFRAC Precision 1549 The TIMESTAMP described in Section 6.2.3 supports fractional seconds. 1550 This provides grounds for a very common coding error, where leading 1551 zeros are removed from the fractional seconds. For example, the 1552 TIMESTAMP "2003-10-11T22:13:14.003" may be erroneously written as 1553 "2003-10-11T22:13:14.3". This would indicate 300 milliseconds 1554 instead of the 3 milliseconds actually meant. 1556 A.5. Case Convention for Names 1558 Names are used at various places in this document, for example for 1559 SD-IDs and PARAM-NAMEs. This document uses "camel case" 1560 consistently. With that, each name begins with a lower case letter 1561 and each new word starts with an upper case letter, but no hyphen or 1562 other delimiter. An example of this is "timeQuality". 1564 While an implementation is free to use any other case convention for 1565 experimental names, it is suggested that the case convention outlined 1566 above is followed. 1568 A.6. Syslog Senders Without Knowledge of Time 1570 In Section 6.2.3, the NILVALUE has been allowed for usage by senders 1571 without knowledge of time. This is done to support a special case 1572 when a sender is not aware of time at all. It can be argued whether 1573 such a sender can actually be found in today's IT infrastructure. 1574 However, discussion has indicated that those things may exist in 1575 practice and as such there should be a guideline established for this 1576 case. 1578 However, an implementation SHOULD emit a valid TIMESTAMP if the 1579 underlying operating system, programming system, and hardware 1580 supports a clock function. A proper TIMESTAMP should be emitted even 1581 if it is difficult, but doable, to obtain the system time. The 1582 NILVALUE should only be used when it is actually impossible to obtain 1583 time information. This rule should not be used as an excuse for lazy 1584 implementations. 1586 A.7. Additional Information on PROCID 1588 The objective behind PROCID (Section 6.2.6) is to provide a quick way 1589 to detect a new instance of the sender's syslog process. It must be 1590 noted that this is not a reliable identification as a second sender 1591 process may actually be assigned the same process ID as a previous 1592 one. Properly used, PROCID can be helpful for analysis purposes. 1594 While PROCID is defined to contain the sender's process ID, it is up 1595 to the sender to decide what this ID is. For example, on a general 1596 purpose OS, it might actually be the operating system process ID of 1597 the syslog sender's process. Other syslog senders might decide that 1598 it is more appropriate to put an internal identification into PROCID. 1599 For example, a SMTP MTA might not put the operating system process ID 1600 into PROCID but might prefer to put its SMTP transaction ID into 1601 PROCID. This might be very useful, because it allows the receiver to 1602 group messages based on the SMTP transaction, which could also be 1603 called the SMTP "process" in this case. On an embedded system 1604 without any operating system process ID, PROCID might actually be a 1605 reboot ID, which might be the closest thing to a process ID on this 1606 hypothetical embedded system. 1608 A.8. Notes on the timeQuality SD-ID 1610 It is recommended that the value of "0" be the default for the 1611 "tzKnown" (Section 7.1.1) parameter. It should only be changed to 1612 "1" after the administrator has specifically configured the time 1613 zone. The value "1" may be used as the default if the underlying 1614 operating system provides accurate time zone information. It is 1615 still advised that the administrator explicitly acknowledge the 1616 correctness of the time zone information. 1618 It is important not to create a false impression of accuracy with the 1619 timeQuality SD-ID (Section 7.1). A sender should only indicate a 1620 given accuracy if it actually knows it is within these bounds. It is 1621 generally assumed that the sender gains this in-depth knowledge 1622 through operator configuration. As such, by default, an accuracy 1623 should not be provided. 1625 Author's Address 1627 Rainer Gerhards 1628 Adiscon GmbH 1629 Mozartstrasse 21 1630 Grossrinderfeld, BW 97950 1631 Germany 1633 Email: rgerhards@adiscon.com 1635 Intellectual Property Statement 1637 The IETF takes no position regarding the validity or scope of any 1638 Intellectual Property Rights or other rights that might be claimed to 1639 pertain to the implementation or use of the technology described in 1640 this document or the extent to which any license under such rights 1641 might or might not be available; nor does it represent that it has 1642 made any independent effort to identify any such rights. Information 1643 on the procedures with respect to rights in RFC documents can be 1644 found in BCP 78 and BCP 79. 1646 Copies of IPR disclosures made to the IETF Secretariat and any 1647 assurances of licenses to be made available, or the result of an 1648 attempt made to obtain a general license or permission for the use of 1649 such proprietary rights by implementers or users of this 1650 specification can be obtained from the IETF on-line IPR repository at 1651 http://www.ietf.org/ipr. 1653 The IETF invites any interested party to bring to its attention any 1654 copyrights, patents or patent applications, or other proprietary 1655 rights that may cover technology that may be required to implement 1656 this standard. Please address the information to the IETF at 1657 ietf-ipr@ietf.org. 1659 Disclaimer of Validity 1661 This document and the information contained herein are provided on an 1662 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1663 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 1664 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 1665 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 1666 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1667 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1669 Copyright Statement 1671 Copyright (C) The Internet Society (2006). This document is subject 1672 to the rights, licenses and restrictions contained in BCP 78, and 1673 except as set forth therein, the authors retain all their rights. 1675 Acknowledgment 1677 Funding for the RFC Editor function is currently provided by the 1678 Internet Society.