[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
syslog content for NETCONF stream
Hi,
I translated the syslog message format as defined
in draft-ietf-syslog-protocol-19.txt into XML encoding
for better subtree and Xpath filtering, as well as a TEXT encoding.
I doubt we can standardize any content given the
level of disagreement over every little detail.
But we still need to keep throwing darts at data models
until there is more agreement.
Simon asked an important question at the last IETF meeting:
"What do you think the NETCONF data model should look like"?
Debating the finer points of data modeling language design is
a nice academic exercise. Debating what the XML on the wire
looks like is much more important right now.
I am including the XSD and the NCX source file.
I hope the documentation is readable in the module header.
This is an attempt at a direct translation of syslog-19 message format.
If there is any interest, I will write up an I-D.
Andy
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns="http://netconfcentral.org/ietf/syslog";
targetNamespace="http://netconfcentral.org/ietf/syslog";
xmlns:xs="http://www.w3.org/2001/XMLSchema";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
elementFormDefault="qualified" attributeFormDefault="unqualified" xml:lang="en"
version="1"
xmlns:ncx="http://netconfcentral.org/ncx/1.0";
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<xs:annotation>
<xs:documentation> Converted from NCX module by ncxdump v0.2
Module: syslog
Owner: ietf
Application: syslog
Version: 1
Copyright (C) Andy Bierman (2007). All Rights Reserved.
Contact Info: Translated by Andy Bierman.
Send comments to ietf@andybierman.com.
Description:
Syslog Message Structure
Translated from draft-ietf-syslog-protocol-19.txt
Defines XML or TEXT encoding formats for translation
of syslog messages into NETCONF Notifications
Note: In all examples the double-quotes have been changed
to single quotes for NCX description string syntax compliance.
The content of the <notification> element is either
a <syslog> element of type 'SyslogTextMessage' or
an <xsyslog> element of type 'SyslogXmlMessage'.
Example Syslog encoding from [syslog] page 22, example 3:
<165>1 2003-10-11T22:14:15.003Z mymachine.example.com
evntslog - ID47 [exampleSDID@0 iut='3'; eventSource=
'Application' eventID='1011'] BOMAn application
event log entry...
NETCONF XML Encoding:
<notification xmlns='netconf-notification'>
<xsyslog xmlns='http://netconfcentral.org/ietf/syslog'>
<pri>165</pri>
<version>1</version>
<timestamp>2003-10-11T22:14:15.003Z</timestamp>
<hostname>mymachine.example.com</hostname>
<appname>evntslog</appname>
<procid>-</procid>
<msgid>ID47</msgid>
<sdparams>
<sdparam sd-id='exampleSDID@0'>
<iut>3</iut>
<eventSource>Application</eventSource>
<eventID>1011</eventID>
</sdparam>
</sdparams>
<msg>An application event log entry...</msg>
</xsyslog>
</notification>
NETCONF Text Encoding:
Note that PRI field MUST NOT be enclosed in angle brackets
They must be omitted instead!
<notification xmlns='netconf-notification'>
<syslog xmlns='http://netconfcentral.org/ietf/syslog'>
165 1 2003-10-11T22:14:15.003Z mymachine.example.com
evntslog - ID47 [exampleSDID@0 iut='3' eventSource=
'Application' eventID='1011'] BOMAn application
event log entry...
</syslog>
</notification>
Revision History:
Revision: 1
Initial version.
</xs:documentation>
</xs:annotation>
<xs:import namespace="http://www.w3.org/XML/1998/namespace";
schemaLocation="http://www.w3.org/2001/xml.xsd"/>
<xs:simpleType name="UsAsciiString">
<xs:annotation>
<xs:documentation>Structured Data Name or ID</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:string">
<xs:pattern value="[&#33;-&#126;]*"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="SDName">
<xs:annotation>
<xs:documentation>Structured Data Name or ID</xs:documentation>
</xs:annotation>
<xs:simpleContent>
<xs:restriction base="UsAsciiString">
<xs:minLength value="1"/>
<xs:maxLength value="32"/>
</xs:restriction>
</xs:simpleContent>
</xs:complexType>
<xs:simpleType name="SyslogPriority">
<xs:annotation>
<xs:documentation>PRI field from [syslog] 6.2.1:
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.
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.
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. Leading '0's MUST NOT be used.</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:string">
<xs:pattern value="[0-9]{1,3}"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="SyslogVersion">
<xs:annotation>
<xs:documentation>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 RFC
2434 [8].</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:string">
<xs:pattern value="([1-9])([0-9]{0,2})"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="SyslogTimestamp">
<xs:annotation>
<xs:documentation>The TIMESTAMP field is a formalized timestamp derived from RFC 3339
[7].
Whereas RFC 3339 [7] 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.
The sender SHOULD include TIME-SECFRAC if its clock accuracy and
performance permit. The 'timeQuality' SD-ID described in Section 7.1
allows the sender to specify accuracy and trustworthiness of the
timestamp.
A syslog sender incapable of obtaining system time MUST use the
NILVALUE as TIMESTAMP.</xs:documentation>
</xs:annotation>
<xs:simpleContent>
<xs:extension base="xs:dateTime"/>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="SyslogHostname">
<xs:annotation>
<xs:documentation>The HOSTNAME field identifies the machine that originally sent the
syslog message.
The HOSTNAME field SHOULD contain the host name and the domain name
of the originator in the format specified in STD 13 [2]. This format
is called a Fully Qualified Domain Name (FQDN) in this document.
In practice, not all senders are able to provide a FQDN. As such,
other values MAY also be present in HOSTNAME. This document makes
provisions for using other values in such situations. A sender
SHOULD provide the most specific available value first. The order of
preference for the contents of the HOSTNAME field is as follows:
1. FQDN
2. Static IP address
3. hostname
4. Dynamic IP address
5. the NILVALUE
If an IPv4 address is used, it MUST be in the format of the dotted
decimal notation as used in STD 13 [3]. If an IPv6 address is used,
a valid textual representation as described in RFC 4291 [9], Section
2.2, MUST be used.
Senders SHOULD consistently use the same value in the HOSTNAME field
for as long as possible. If the sender uses IP addresses inside
hostname, the following rules apply: If the sender is multihomed,
this value SHOULD be one of its actual IP addresses. If a sender is
running on a machine that has both statically and dynamically
assigned addresses, then that value SHOULD be from the statically
assigned addresses. As an alternative, the sender MAY use the IP
address of the interface that is used to send the message.
The NILVALUE SHOULD only be used when the sender has no way to obtain
its real hostname. This situation is considered highly unlikely.</xs:documentation>
</xs:annotation>
<xs:simpleContent>
<xs:restriction base="UsAsciiString">
<xs:minLength value="1"/>
<xs:maxLength value="255"/>
</xs:restriction>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="SyslogAppname">
<xs:annotation>
<xs:documentation>The APP-NAME field SHOULD identify the device or application that
generated the message. It is a string without further semantics. It
is intended for filtering messages on the receiver.
The NILVALUE MAY be used when the sender has no idea of its APP-NAME
or cannot provide that information. It may be that a device may not
be able 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.</xs:documentation>
</xs:annotation>
<xs:simpleContent>
<xs:restriction base="UsAsciiString">
<xs:minLength value="1"/>
<xs:maxLength value="48"/>
</xs:restriction>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="SyslogProcid">
<xs:annotation>
<xs:documentation>The PROCID field SHOULD be used to provide the sender's process name
or process ID. The field does not have any specific syntax.
The NILVALUE MAY be used when the sender can not obtain its PROCID or
cannot provide it.
PROCID is primarily meaningful for analysis tools. Properly used, it
can enable log analyzers to detect which messages were generated by
the same sender process. For example, on a UNIX system the syslog
daemon (syslogd) might emit messages to the log. All messages logged
by the same syslogd process will bear the same PROCID. When the
syslog sender is restarted, the PROCID value MAY change. That may
enable the analysis script to detect the syslogd restart.
This field MAY be operator-assigned. Some non-normative additional
information about PROCID values can be found in Appendix A.8.</xs:documentation>
</xs:annotation>
<xs:simpleContent>
<xs:restriction base="UsAsciiString">
<xs:minLength value="1"/>
<xs:maxLength value="12"/>
</xs:restriction>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="SyslogMsgid">
<xs:annotation>
<xs:documentation>The MSGID SHOULD identify the type of message. For example, a
firewall might use the MSGID 'TCPIN' for incoming TCP traffic and the
MSGID 'TCPOUT' for outgoing TCP traffic. Messages with the same
MSGID should reflect events of the same semantics. The MSGID itself
is a string without further semantics. It is intended for filtering
messages on the receiver.
The NILVALUE SHOULD be used when the sender does not intend to
provide a real MSGID.
This field MAY be operator-assigned.</xs:documentation>
</xs:annotation>
<xs:simpleContent>
<xs:restriction base="UsAsciiString">
<xs:minLength value="1"/>
<xs:maxLength value="32"/>
</xs:restriction>
</xs:simpleContent>
</xs:complexType>
<xs:simpleType name="SyslogParam">
<xs:annotation>
<xs:documentation>NOT REALLY USED!!! Represents one SD-PARAM entry</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:string"/>
</xs:simpleType>
<xs:complexType name="SyslogParamSet">
<xs:annotation>
<xs:documentation>Represents one SD-PARAM entry</xs:documentation>
</xs:annotation>
<xs:complexContent>
<xs:extension base="xs:anyType">
<xs:attribute name="sd-id" type="SDName" use="required"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="SyslogParams">
<xs:annotation>
<xs:documentation>Represents container of SD-PARAM entries</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="sdparam" type="SyslogParamSet" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:simpleType name="SyslogMsgData">
<xs:annotation>
<xs:documentation>The MSG section as defined in [syslog] sec. 6.4</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:string"/>
</xs:simpleType>
<xs:complexType name="SyslogXmlMessage">
<xs:annotation>
<xs:documentation>The top-level Syslog XML Message structure.
The header contents are placed at the same nest level
as the other fields in order to simplify encoding
and permit NETCONF subtree filtering to work properly</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="pri" type="SyslogPriority"/>
<xs:element name="version" type="SyslogVersion"/>
<xs:element name="timestamp" type="SyslogTimestamp"/>
<xs:element name="hostname" type="SyslogHostname"/>
<xs:element name="appname" type="SyslogAppname"/>
<xs:element name="procid" type="SyslogProcid"/>
<xs:element name="msgid" type="SyslogMsgid"/>
<xs:element name="sdparams" type="SyslogParams" minOccurs="0"/>
<xs:element name="msg" type="SyslogMsgData" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:simpleType name="SyslogTextMessage">
<xs:annotation>
<xs:documentation>The top-level Syslog TEXT Message structure.</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:string"/>
</xs:simpleType>
<xs:element name="syslog" type="SyslogTextMessage"/>
<xs:element name="xsyslog" type="SyslogXmlMessage"/>
</xs:schema>
ncx-module syslog {
header {
description
"Syslog Message Structure
Translated from draft-ietf-syslog-protocol-19.txt
Defines XML or TEXT encoding formats for translation
of syslog messages into NETCONF Notifications
Note: In all examples the double-quotes have been changed
to single quotes for NCX description string syntax compliance.
The content of the <notification> element is either
a <syslog> element of type 'SyslogTextMessage' or
an <xsyslog> element of type 'SyslogXmlMessage'.
Example Syslog encoding from [syslog] page 22, example 3:
<165>1 2003-10-11T22:14:15.003Z mymachine.example.com
evntslog - ID47 [exampleSDID@0 iut='3'; eventSource=
'Application' eventID='1011'] BOMAn application
event log entry...
NETCONF XML Encoding:
<notification xmlns='netconf-notification'>
<xsyslog xmlns='http://netconfcentral.org/ietf/syslog'>
<pri>165</pri>
<version>1</version>
<timestamp>2003-10-11T22:14:15.003Z</timestamp>
<hostname>mymachine.example.com</hostname>
<appname>evntslog</appname>
<procid>-</procid>
<msgid>ID47</msgid>
<sdparams>
<sdparam sd-id='exampleSDID@0'>
<iut>3</iut>
<eventSource>Application</eventSource>
<eventID>1011</eventID>
</sdparam>
</sdparams>
<msg>An application event log entry...</msg>
</xsyslog>
</notification>
NETCONF Text Encoding:
Note that PRI field MUST NOT be enclosed in angle brackets
They must be omitted instead!
<notification xmlns='netconf-notification'>
<syslog xmlns='http://netconfcentral.org/ietf/syslog'>
165 1 2003-10-11T22:14:15.003Z mymachine.example.com
evntslog - ID47 [exampleSDID@0 iut='3' eventSource=
'Application' eventID='1011'] BOMAn application
event log entry...
</syslog>
</notification>
";
version 1;
owner ietf;
application syslog;
copyright
"Copyright (C) Andy Bierman (2007). All Rights Reserved.";
contact-info
"Translated by Andy Bierman.
Send comments to ietf@andybierman.com.";
last-update "2007-04-05";
revision-history {
1 "Initial version.";
}
}
imports {
import xsd;
}
definitions {
type UsAsciiString {
description "Structured Data Name or ID";
syntax {
string pattern = "[!-~]*";
}
}
type SDName {
description "Structured Data Name or ID";
syntax {
UsAsciiString (1..32);
}
}
type SyslogPriority {
description
"PRI field from [syslog] 6.2.1:
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.
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.
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. Leading '0's MUST NOT be used.";
syntax {
string pattern = "[0-9]{1,3}"; # range 0 .. 191
}
}
type SyslogVersion {
description
"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 RFC
2434 [8].";
syntax {
string pattern = "([1-9])([0-9]{0,2})";
}
}
type SyslogTimestamp {
description
"The TIMESTAMP field is a formalized timestamp derived from RFC 3339
[7].
Whereas RFC 3339 [7] 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.
The sender SHOULD include TIME-SECFRAC if its clock accuracy and
performance permit. The 'timeQuality' SD-ID described in Section 7.1
allows the sender to specify accuracy and trustworthiness of the
timestamp.
A syslog sender incapable of obtaining system time MUST use the
NILVALUE as TIMESTAMP.";
syntax { dateTime; }
}
type SyslogHostname {
description
"The HOSTNAME field identifies the machine that originally sent the
syslog message.
The HOSTNAME field SHOULD contain the host name and the domain name
of the originator in the format specified in STD 13 [2]. This format
is called a Fully Qualified Domain Name (FQDN) in this document.
In practice, not all senders are able to provide a FQDN. As such,
other values MAY also be present in HOSTNAME. This document makes
provisions for using other values in such situations. A sender
SHOULD provide the most specific available value first. The order of
preference for the contents of the HOSTNAME field is as follows:
1. FQDN
2. Static IP address
3. hostname
4. Dynamic IP address
5. the NILVALUE
If an IPv4 address is used, it MUST be in the format of the dotted
decimal notation as used in STD 13 [3]. If an IPv6 address is used,
a valid textual representation as described in RFC 4291 [9], Section
2.2, MUST be used.
Senders SHOULD consistently use the same value in the HOSTNAME field
for as long as possible. If the sender uses IP addresses inside
hostname, the following rules apply: If the sender is multihomed,
this value SHOULD be one of its actual IP addresses. If a sender is
running on a machine that has both statically and dynamically
assigned addresses, then that value SHOULD be from the statically
assigned addresses. As an alternative, the sender MAY use the IP
address of the interface that is used to send the message.
The NILVALUE SHOULD only be used when the sender has no way to obtain
its real hostname. This situation is considered highly unlikely.";
syntax { UsAsciiString (1..255); }
}
type SyslogAppname {
description
"The APP-NAME field SHOULD identify the device or application that
generated the message. It is a string without further semantics. It
is intended for filtering messages on the receiver.
The NILVALUE MAY be used when the sender has no idea of its APP-NAME
or cannot provide that information. It may be that a device may not
be able 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.";
syntax {
UsAsciiString (1..48);
}
}
type SyslogProcid {
description
"The PROCID field SHOULD be used to provide the sender's process name
or process ID. The field does not have any specific syntax.
The NILVALUE MAY be used when the sender can not obtain its PROCID or
cannot provide it.
PROCID is primarily meaningful for analysis tools. Properly used, it
can enable log analyzers to detect which messages were generated by
the same sender process. For example, on a UNIX system the syslog
daemon (syslogd) might emit messages to the log. All messages logged
by the same syslogd process will bear the same PROCID. When the
syslog sender is restarted, the PROCID value MAY change. That may
enable the analysis script to detect the syslogd restart.
This field MAY be operator-assigned. Some non-normative additional
information about PROCID values can be found in Appendix A.8.";
syntax {
UsAsciiString (1..12);
}
}
type SyslogMsgid {
description
"The MSGID SHOULD identify the type of message. For example, a
firewall might use the MSGID 'TCPIN' for incoming TCP traffic and the
MSGID 'TCPOUT' for outgoing TCP traffic. Messages with the same
MSGID should reflect events of the same semantics. The MSGID itself
is a string without further semantics. It is intended for filtering
messages on the receiver.
The NILVALUE SHOULD be used when the sender does not intend to
provide a real MSGID.
This field MAY be operator-assigned.";
syntax {
UsAsciiString (1..32);
}
}
type SyslogParam {
description
"NOT REALLY USED!!! Represents one SD-PARAM entry";
syntax { string; }
}
type SyslogParamSet {
description "Represents one SD-PARAM entry";
syntax { any; }
# really replacement of the abstract 'param-name'
# struct {
# SyslogParam param-name+;
# }
metadata {
SDName sd-id;
}
}
type SyslogParams {
description "Represents container of SD-PARAM entries";
syntax {
struct {
SyslogParamSet sdparam+;
}
}
}
type SyslogMsgData {
description
"The MSG section as defined in [syslog] sec. 6.4";
syntax { string; }
}
type SyslogXmlMessage {
description
"The top-level Syslog XML Message structure.
The header contents are placed at the same nest level
as the other fields in order to simplify encoding
and permit NETCONF subtree filtering to work properly";
syntax {
struct {
SyslogPriority pri;
SyslogVersion version;
SyslogTimestamp timestamp;
SyslogHostname hostname;
SyslogAppname appname;
SyslogProcid procid;
SyslogMsgid msgid;
SyslogParams sdparams?;
SyslogMsgData msg?;
}
}
}
type SyslogTextMessage {
description
"The top-level Syslog TEXT Message structure.";
syntax { string; }
}
}
}