forked from syslog4j/syslog4j
-
Notifications
You must be signed in to change notification settings - Fork 0
/
RFC5424.txt
2131 lines (1417 loc) · 83.2 KB
/
RFC5424.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
Network Working Group R. Gerhards
Request for Comments: 5424 Adiscon GmbH
Obsoletes: 3164 March 2009
Category: Standards Track
The Syslog Protocol
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (c) 2009 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents in effect on the date of
publication of this document (http://trustee.ietf.org/license-info).
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document.
This document may contain material from IETF Documents or IETF
Contributions published or made publicly available before November
10, 2008. The person(s) controlling the copyright in some of this
material may not have granted the IETF Trust the right to allow
modifications of such material outside the IETF Standards Process.
Without obtaining an adequate license from the person(s) controlling
the copyright in such materials, this document may not be modified
outside the IETF Standards Process, and derivative works of it may
not be created outside the IETF Standards Process, except to format
it for publication as an RFC or to translate it into languages other
than English.
Gerhards Standards Track [Page 1]
RFC 5424 The Syslog Protocol March 2009
Abstract
This document describes the syslog protocol, which is used to convey
event notification messages. This protocol utilizes a layered
architecture, which allows the use of any number of transport
protocols for transmission of syslog messages. It also provides a
message format that allows vendor-specific extensions to be provided
in a structured way.
This document has been written with the original design goals for
traditional syslog in mind. The need for a new layered specification
has arisen because standardization efforts for reliable and secure
syslog extensions suffer from the lack of a Standards-Track and
transport-independent RFC. Without this document, each other
standard needs to define its own syslog packet format and transport
mechanism, which over time will introduce subtle compatibility
issues. This document tries to provide a foundation that syslog
extensions can build on. This layered architecture approach also
provides a solid basis that allows code to be written once for each
syslog feature rather than once for each transport.
This document obsoletes RFC 3164.
Table of Contents
1. Introduction ....................................................4
2. Conventions Used in This Document ...............................4
3. Definitions .....................................................4
4. Basic Principles ................................................5
4.1. Example Deployment Scenarios ...............................6
5. Transport Layer Protocol ........................................7
5.1. Minimum Required Transport Mapping .........................7
6. Syslog Message Format ...........................................8
6.1. Message Length .............................................9
6.2. HEADER .....................................................9
6.2.1. PRI .................................................9
6.2.2. VERSION ............................................11
6.2.3. TIMESTAMP ..........................................11
6.2.4. HOSTNAME ...........................................13
6.2.5. APP-NAME ...........................................14
6.2.6. PROCID .............................................14
6.2.7. MSGID ..............................................14
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 .....................................17
6.3.5. Examples ...........................................17
Gerhards Standards Track [Page 2]
RFC 5424 The Syslog Protocol March 2009
6.4. MSG .......................................................18
6.5. Examples ..................................................19
7. Structured Data IDs ............................................20
7.1. timeQuality ...............................................20
7.1.1. tzKnown ............................................21
7.1.2. isSynced ...........................................21
7.1.3. syncAccuracy .......................................21
7.1.4. Examples ...........................................21
7.2. origin ....................................................22
7.2.1. ip .................................................22
7.2.2. enterpriseId .......................................22
7.2.3. software ...........................................23
7.2.4. swVersion ..........................................23
7.2.5. Example ............................................23
7.3. meta ......................................................24
7.3.1. sequenceId .........................................24
7.3.2. sysUpTime ..........................................24
7.3.3. language ...........................................24
8. Security Considerations ........................................24
8.1. UNICODE ...................................................24
8.2. Control Characters ........................................25
8.3. Message Truncation ........................................26
8.4. Replay ....................................................26
8.5. Reliable Delivery .........................................26
8.6. Congestion Control ........................................27
8.7. Message Integrity .........................................28
8.8. Message Observation .......................................28
8.9. Inappropriate Configuration ...............................28
8.10. Forwarding Loop ..........................................29
8.11. Load Considerations ......................................29
8.12. Denial of Service ........................................29
9. IANA Considerations ............................................30
9.1. VERSION ...................................................30
9.2. SD-IDs ....................................................30
10. Working Group .................................................31
11. Acknowledgments ...............................................31
12. References ....................................................32
12.1. Normative References .....................................32
12.2. Informative References ...................................33
Appendix A. Implementer Guidelines ...............................34
A.1. Relationship with BSD Syslog ..............................34
A.2. Message Length ............................................35
A.3. Severity Values ..........................................36
A.4. TIME-SECFRAC Precision ....................................36
A.5. Case Convention for Names ................................36
A.6. Syslog Applications Without Knowledge of Time ............37
A.7. Notes on the timeQuality SD-ID ............................37
A.8. UTF-8 Encoding and the BOM ................................37
Gerhards Standards Track [Page 3]
RFC 5424 The Syslog Protocol March 2009
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 easily
parseable, structured information, and allows for vendor extensions.
This document does not describe any storage format for syslog
messages. It is beyond of the scope of the syslog protocol and is
unnecessary for system interoperability.
This document has been written with the original design goals for
traditional syslog in mind. The need for a new layered specification
has arisen because standardization efforts for reliable and secure
syslog extensions suffer from the lack of a Standards-Track and
transport-independent RFC. Without this document, each other
standard would need to define its own syslog packet format and
transport mechanism, which over time will introduce subtle
compatibility issues. This document tries to provide a foundation
that syslog extensions can build on. This layered architecture
approach also provides a solid basis that allows code to be written
once for each syslog feature instead of once for each transport.
This document obsoletes RFC 3164, which is an Informational document
describing some implementations found in the field.
2. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119].
3. Definitions
Syslog utilizes three layers:
o "syslog content" is the management information contained in a
syslog message.
o The "syslog application" layer handles generation, interpretation,
routing, and storage of syslog messages.
o The "syslog transport" layer puts messages on the wire and takes
them off the wire.
Gerhards Standards Track [Page 4]
RFC 5424 The Syslog Protocol March 2009
Certain types of functions are performed at each conceptual layer:
o An "originator" generates syslog content to be carried in a
message.
o A "collector" gathers syslog content for further analysis.
o A "relay" forwards messages, accepting messages from originators
or other relays and sending them to collectors or other relays.
o A "transport sender" passes syslog messages to a specific
transport protocol.
o A "transport receiver" takes syslog messages from a specific
transport protocol.
Diagram 1 shows the different entities separated by layer.
+---------------------+ +---------------------+
| content | | content |
|---------------------| |---------------------|
| syslog application | | syslog application | (originator,
| | | | collector, relay)
|---------------------| |---------------------|
| syslog transport | | syslog transport | (transport sender,
| | | | (transport receiver)
+---------------------+ +---------------------+
^ ^
| |
--------------------------
Diagram 1. Syslog Layers
4. Basic Principles
The following principles apply to syslog communication:
o The syslog protocol does not provide acknowledgment of message
delivery. Though some transports may provide status information,
conceptually, syslog is a pure simplex communications protocol.
o Originators and relays may be configured to send the same message
to multiple collectors and relays.
o Originator, relay, and collector functionality may reside on the
same system.
Gerhards Standards Track [Page 5]
RFC 5424 The Syslog Protocol March 2009
4.1. Example Deployment Scenarios
Sample deployment scenarios are shown in Diagram 2. Other
arrangements of these examples are also acceptable. As noted, in the
following diagram, relays may send all or some of the messages that
they receive and also send messages that they generate internally.
The boxes represent syslog-enabled applications.
+----------+ +---------+
|Originator|---->----|Collector|
+----------+ +---------+
+----------+ +-----+ +---------+
|Originator|---->----|Relay|---->----|Collector|
+----------+ +-----+ +---------+
+----------+ +-----+ +-----+ +---------+
|Originator|-->--|Relay|-->--..-->--|Relay|-->--|Collector|
+----------+ +-----+ +-----+ +---------+
+----------+ +-----+ +---------+
|Originator|---->----|Relay|---->----|Collector|
| |-+ +-----+ +---------+
+----------+ \
\ +-----+ +---------+
+->--|Relay|---->----|Collector|
+-----+ +---------+
+----------+ +---------+
|Originator|---->----|Collector|
| |-+ +---------+
+----------+ \
\ +-----+ +---------+
+->--|Relay|---->----|Collector|
+-----+ +---------+
+----------+ +-----+ +---------+
|Originator|---->----|Relay|---->-------|Collector|
| |-+ +-----+ +---| |
+----------+ \ / +---------+
\ +-----+ /
+->--|Relay|-->--/
+-----+
Gerhards Standards Track [Page 6]
RFC 5424 The Syslog Protocol March 2009
+----------+ +-----+ +---------+
|Originator|---->----|Relay|---->--------------|Collector|
| |-+ +-----+ +--| |
+----------+ \ / +---------+
\ +------------+ /
\ |+----------+| /
+->-||Relay ||->---/
|+----------|| /
||Originator||->-/
|+----------+|
+------------+
Diagram 2. Some Possible Syslog Deployment Scenarios
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. Syslog transports are defined in other
documents. One such transport is defined in [RFC5426] and is
consistent with the traditional UDP transport. This transport is
needed to maintain interoperability as the UDP transport has
historically been used for the transmission of syslog messages.
Any syslog transport protocol MUST NOT deliberately alter the syslog
message. If the transport protocol needs to perform temporary
transformations at the transport sender, these transformations MUST
be reversed by the transport protocol at the transport receiver so
that the relay or collector will see an exact copy of the message
generated by the originator or relay. Otherwise, end-to-end
cryptographic verifiers (such as signatures) will be broken. Of
course, message alteration might occur due to transmission errors or
other problems. Guarding against such alterations is not within the
scope of this document.
5.1. Minimum Required Transport Mapping
All implementations of this specification MUST support a TLS-based
transport as described in [RFC5425].
All implementations of this specification SHOULD also support a
UDP-based transport as described in [RFC5426].
It is RECOMMENDED that deployments of this specification use the TLS-
based transport.
Gerhards Standards Track [Page 7]
RFC 5424 The Syslog Protocol March 2009
6. Syslog Message Format
The syslog message has the following ABNF [RFC5234] definition:
SYSLOG-MSG = HEADER SP STRUCTURED-DATA [SP MSG]
HEADER = PRI VERSION SP TIMESTAMP SP HOSTNAME
SP APP-NAME SP PROCID SP MSGID
PRI = "<" PRIVAL ">"
PRIVAL = 1*3DIGIT ; range 0 .. 191
VERSION = NONZERO-DIGIT 0*2DIGIT
HOSTNAME = NILVALUE / 1*255PRINTUSASCII
APP-NAME = NILVALUE / 1*48PRINTUSASCII
PROCID = NILVALUE / 1*128PRINTUSASCII
MSGID = NILVALUE / 1*32PRINTUSASCII
TIMESTAMP = NILVALUE / 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-59
TIME-SECFRAC = "." 1*6DIGIT
TIME-OFFSET = "Z" / TIME-NUMOFFSET
TIME-NUMOFFSET = ("+" / "-") TIME-HOUR ":" TIME-MINUTE
STRUCTURED-DATA = NILVALUE / 1*SD-ELEMENT
SD-ELEMENT = "[" SD-ID *(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*32PRINTUSASCII
; except '=', SP, ']', %d34 (")
MSG = MSG-ANY / MSG-UTF8
MSG-ANY = *OCTET ; not starting with BOM
MSG-UTF8 = BOM UTF-8-STRING
BOM = %xEF.BB.BF
Gerhards Standards Track [Page 8]
RFC 5424 The Syslog Protocol March 2009
UTF-8-STRING = *OCTET ; UTF-8 string as specified
; in RFC 3629
OCTET = %d00-255
SP = %d32
PRINTUSASCII = %d33-126
NONZERO-DIGIT = %d49-57
DIGIT = %d48 / NONZERO-DIGIT
NILVALUE = "-"
6.1. Message Length
Syslog message size limits are dictated by the syslog transport
mapping in use. There is no upper limit per se. Each transport
mapping defines the minimum maximum required message length support,
and the minimum maximum MUST be at least 480 octets in length.
Any transport receiver MUST be able to accept messages of up to and
including 480 octets in length. All transport receiver
implementations SHOULD be able to accept messages of up to and
including 2048 octets in length. Transport receivers MAY receive
messages larger than 2048 octets in length. If a transport receiver
receives a message with a length larger than it supports, the
transport receiver SHOULD truncate the payload. Alternatively, it
MAY discard the message.
If a transport receiver truncates messages, the truncation MUST occur
at the end of the message. After truncation, the message MAY contain
invalid UTF-8 encoding or invalid STRUCTURED-DATA. The transport
receiver MAY discard the message or MAY try to process as much as
possible in this case.
6.2. HEADER
The character set used in the HEADER MUST be seven-bit ASCII in an
eight-bit field as described in [RFC5234]. These are the ASCII codes
as defined in "USA Standard Code for Information Interchange"
[ANSI.X3-4.1968].
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. PRI
The PRI part MUST have three, four, or five characters and will be
bound with angle brackets as the first and last characters. The PRI
part starts with a leading "<" ('less-than' character, %d60),
followed by a number, which is followed by a ">" ('greater-than'
Gerhards Standards Track [Page 9]
RFC 5424 The Syslog Protocol March 2009
character, %d62). The number contained within these angle brackets
is known as the Priority value (PRIVAL) and represents both the
Facility and Severity. The Priority value consists of one, two, or
three decimal integers (ABNF DIGITS) using values of %d48 (for "0")
through %d57 (for "9").
Facility and Severity values are not normative but often used. They
are described in the following tables for purely informational
purposes. Facility values MUST be in the range of 0 to 23 inclusive.
Numerical Facility
Code
0 kernel messages
1 user-level messages
2 mail system
3 system daemons
4 security/authorization messages
5 messages generated internally by syslogd
6 line printer subsystem
7 network news subsystem
8 UUCP subsystem
9 clock daemon
10 security/authorization messages
11 FTP daemon
12 NTP subsystem
13 log audit
14 log alert
15 clock daemon (note 2)
16 local use 0 (local0)
17 local use 1 (local1)
18 local use 2 (local2)
19 local use 3 (local3)
20 local use 4 (local4)
21 local use 5 (local5)
22 local use 6 (local6)
23 local use 7 (local7)
Table 1. Syslog Message Facilities
Each message Priority also has a decimal Severity level indicator.
These are described in the following table along with their numerical
values. Severity values MUST be in the range of 0 to 7 inclusive.
Gerhards Standards Track [Page 10]
RFC 5424 The Syslog Protocol March 2009
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
Table 2. Syslog Message Severities
The Priority value is calculated by first multiplying the Facility
number by 8 and then adding the numerical value of the Severity. For
example, a kernel message (Facility=0) with a Severity of Emergency
(Severity=0) would have a Priority value of 0. Also, a "local use 4"
message (Facility=20) with a Severity of Notice (Severity=5) would
have a Priority value of 165. In the PRI of a syslog message, these
values would be placed between the angle brackets as <0> and <165>
respectively. The only time a value of "0" follows the "<" is for
the Priority value of "0". Otherwise, leading "0"s MUST NOT be used.
6.2.2. 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. Changes include the addition or removal of fields, or a
change of syntax or semantics of existing fields. This document uses
a VERSION value of "1". The VERSION values are IANA-assigned
(Section 9.1) via the Standards Action method as described in
[RFC5226].
6.2.3. TIMESTAMP
The TIMESTAMP field is a formalized timestamp derived from [RFC3339].
Whereas [RFC3339] makes allowances for multiple syntaxes, this
document imposes further restrictions. The TIMESTAMP value 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.
o Leap seconds MUST NOT be used.
Gerhards Standards Track [Page 11]
RFC 5424 The Syslog Protocol March 2009
The originator SHOULD include TIME-SECFRAC if its clock accuracy and
performance permit. The "timeQuality" SD-ID described in Section 7.1
allows the originator to specify the accuracy and trustworthiness of
the timestamp.
A syslog application MUST use the NILVALUE as TIMESTAMP if the syslog
application is incapable of obtaining system time.
6.2.3.1. 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 US
Eastern Standard Time (observing daylight savings time).
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 providing just three digits for the fractional part
of a second 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.
Gerhards Standards Track [Page 12]
RFC 5424 The Syslog Protocol March 2009
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 results in TIME-SECFRAC being
longer than the allowed 6 digits, which invalidates it.
6.2.4. HOSTNAME
The HOSTNAME field identifies the machine that originally sent the
syslog message.
The HOSTNAME field SHOULD contain the hostname and the domain name of
the originator in the format specified in STD 13 [RFC1034]. This
format is called a Fully Qualified Domain Name (FQDN) in this
document.
In practice, not all syslog applications are able to provide an FQDN.
As such, other values MAY also be present in HOSTNAME. This document
makes provisions for using other values in such situations. A syslog
application 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. the NILVALUE
If an IPv4 address is used, it MUST be in the format of the dotted
decimal notation as used in STD 13 [RFC1035]. If an IPv6 address is
used, a valid textual representation as described in [RFC4291],
Section 2.2, MUST be used.
Syslog applications SHOULD consistently use the same value in the
HOSTNAME field for as long as possible.
The NILVALUE SHOULD only be used when the syslog application has no
way to obtain its real hostname. This situation is considered highly
unlikely.
Gerhards Standards Track [Page 13]
RFC 5424 The Syslog Protocol March 2009
6.2.5. APP-NAME
The APP-NAME field SHOULD identify the device or application that
originated the message. It is a string without further semantics.
It is intended for filtering messages on a relay or collector.
The NILVALUE MAY be used when the syslog application has no idea of
its APP-NAME or cannot provide that information. It may be that a
device is unable to provide that information either because of a
local policy decision, or because the information is not available,
or not applicable, on the device.
This field MAY be operator-assigned.
6.2.6. PROCID
PROCID is a value that is included in the message, having no
interoperable meaning, except that a change in the value indicates
there has been a discontinuity in syslog reporting. The field does
not have any specific syntax or semantics; the value is
implementation-dependent and/or operator-assigned. The NILVALUE MAY
be used when no value is provided.
The PROCID field is often used to provide the process name or process
ID associated with a syslog system. The NILVALUE might be used when
a process ID is not available. On an embedded system without any
operating system process ID, PROCID might be a reboot ID.
PROCID can enable log analyzers to detect discontinuities in syslog
reporting by detecting a change in the syslog process ID. However,
PROCID is not a reliable identification of a restarted process since
the restarted syslog process might be assigned the same process ID as
the previous syslog process.
PROCID can also be used to identify which messages belong to a group
of messages. For example, an SMTP mail transfer agent might put its
SMTP transaction ID into PROCID, which would allow the collector or
relay to group messages based on the SMTP transaction.
6.2.7. 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 a relay or collector.
Gerhards Standards Track [Page 14]
RFC 5424 The Syslog Protocol March 2009
The NILVALUE SHOULD be used when the syslog application does not, or
cannot, provide any value.
This field MAY be operator-assigned.
6.3. STRUCTURED-DATA
STRUCTURED-DATA provides a mechanism to express information in a well
defined, easily parseable and interpretable data format. There are
multiple usage scenarios. For example, it may express 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.
In case of zero structured data elements, the STRUCTURED-DATA field
MUST contain the NILVALUE.
The character set used in STRUCTURED-DATA MUST be seven-bit ASCII in
an eight-bit field as described in [RFC5234]. These are the ASCII
codes as defined in "USA Standard Code for Information Interchange"
[ANSI.X3-4.1968]. An exception is the PARAM-VALUE field (see
Section 6.3.3), in which UTF-8 encoding MUST be used.
A collector MAY ignore malformed STRUCTURED-DATA elements. A relay
MUST forward malformed STRUCTURED-DATA without any alteration.
6.3.1. SD-ELEMENT
An 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
SD-IDs are case-sensitive and uniquely identify the type and purpose
of the SD-ELEMENT. The same SD-ID MUST NOT exist more than once in a
message.
There are two formats for SD-ID names:
o Names that do not contain an at-sign ("@", ABNF %d64) are reserved
to be assigned by IETF Review as described in BCP26 [RFC5226].
Currently, these are the names defined in Section 7. Names of
this format are only valid if they are first registered with the
IANA. Registered names MUST NOT contain an at-sign ('@', ABNF
Gerhards Standards Track [Page 15]
RFC 5424 The Syslog Protocol March 2009
%d64), an equal-sign ('=', ABNF %d61), a closing brace (']', ABNF
%d93), a quote-character ('"', ABNF %d34), whitespace, or control
characters (ASCII code 127 and codes 32 or less).
o Anyone can define additional SD-IDs using names in the format
name@<private enterprise number>, e.g., "ourSDID@32473". The
format of the part preceding the at-sign is not specified;
however, these names MUST be printable US-ASCII strings, and MUST
NOT contain an at-sign ('@', ABNF %d64), an equal-sign ('=', ABNF
%d61), a closing brace (']', ABNF %d93), a quote-character ('"',
ABNF %d34), whitespace, or control characters. The part following
the at-sign MUST be a private enterprise number as specified in
Section 7.2.2. Please note that throughout this document the
value of 32473 is used for all private enterprise numbers. This
value has been reserved by IANA to be used as an example number in
documentation. Implementors will need to use their own private
enterprise number for the enterpriseId parameter, and when
creating locally extensible SD-ID names.
6.3.3. SD-PARAM
Each SD-PARAM consists of a name, referred to as PARAM-NAME, and a
value, referred to as PARAM-VALUE.
PARAM-NAME is case-sensitive. IANA controls all PARAM-NAMEs, with
the exception of those in SD-IDs whose names contain an at-sign. The
PARAM-NAME scope is within a specific SD-ID. Thus, equally named
PARAM-NAME values contained in two different SD-IDs are not the same.
To support international characters, the PARAM-VALUE field MUST be
encoded using UTF-8. A syslog application MAY issue any valid UTF-8
sequence. A syslog application MUST accept any valid UTF-8 sequence
in the "shortest form". It MUST NOT fail if control characters are
present in PARAM-VALUE. The syslog application MAY modify messages
containing control characters (e.g., by changing an octet with value
0 (USASCII NUL) to the four characters "#000"). For the reasons
outlined in UNICODE TR36 [UNICODE-TR36], section 3.1, an originator
MUST encode messages in the "shortest form" and a collector or relay
MUST NOT interpret messages in the "non-shortest form".
Inside PARAM-VALUE, the characters '"' (ABNF %d34), '\' (ABNF %d92),
and ']' (ABNF %d93) MUST be escaped. This is necessary to avoid
parsing errors. Escaping ']' would not strictly be necessary but is
REQUIRED by this specification to avoid syslog application
implementation errors. Each of these three characters MUST be
escaped as '\"', '\\', and '\]' respectively. The backslash is used
Gerhards Standards Track [Page 16]
RFC 5424 The Syslog Protocol March 2009
for control character escaping for consistency with its use for
escaping in other parts of the syslog message as well as in
traditional syslog.
A backslash ('\') followed by none of the three described characters
is considered an invalid escape sequence. In this case, the
backslash MUST be treated as a regular backslash and the following
character as a regular character. Thus, the invalid sequence MUST
not be altered.
An SD-PARAM MAY be repeated multiple times inside an SD-ELEMENT.
6.3.4. Change Control
Once SD-IDs and PARAM-NAMEs are defined, syntax and semantics of
these objects MUST NOT be altered. Should a change to an existing
object be desired, a new SD-ID or PARAM-NAME MUST be created and the
old one remain unchanged. OPTIONAL PARAM-NAMEs MAY be added to an
existing SD-ID.
6.3.5. Examples
All examples in this section show only the structured data part of
the message. Examples should be considered to be on one line. They
are wrapped on multiple lines in this document for readability
purposes. A description is given after each example.
Example 1 - Valid
[exampleSDID@32473 iut="3" eventSource="Application"
eventID="1011"]
This example is a structured data element with a non-IANA controlled
SD-ID of type "exampleSDID@32473", which has three parameters.
Example 2 - Valid
[exampleSDID@32473 iut="3" eventSource="Application"
eventID="1011"][examplePriority@32473 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
[exampleSDID@32473 iut="3" eventSource="Application"
eventID="1011"] [examplePriority@32473 class="high"]
Gerhards Standards Track [Page 17]
RFC 5424 The Syslog Protocol March 2009
This is nearly the same example as 2, but it has a subtle error --
there is an 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
[ exampleSDID@32473 iut="3" eventSource="Application"
eventID="1011"][examplePriority@32473 class="high"]
This example is nearly the same as 2. It has another subtle error --
the SP character occurs after the initial bracket. A structured data
element SD-ID MUST immediately follow the beginning bracket, so the
SP character invalidates the STRUCTURED-DATA. A syslog application
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. The ellipses denote missing content, which has been left out
of this example 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 SHOULD be UNICODE, encoded using UTF-8
as specified in [RFC3629]. If the syslog application cannot encode
the MSG in Unicode, it MAY use any other encoding.
The syslog application SHOULD avoid octet values below 32 (the
traditional US-ASCII control character range except DEL). These
values are legal, but a syslog application MAY modify these
characters upon reception. For example, it might change them into an
escape sequence (e.g., value 0 may be changed to "\0"). A syslog
application SHOULD NOT modify any other octet values.
If a syslog application encodes MSG in UTF-8, the string MUST start