Skip to content

Commit 082fc1a

Browse files
leodidoleodido
committed
docs(ciscoios,rfc3164): document current support for Cisco IOS syslog extensions
Signed-off-by: Leonardo Di Donato <[email protected]>
1 parent e598f39 commit 082fc1a

File tree

3 files changed

+88
-5
lines changed

3 files changed

+88
-5
lines changed

‎ciscoios/flags.go‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
1+
// Package ciscoios provides component flags for configuring Cisco IOS syslog parsing.
2+
//
3+
// Cisco IOS devices send syslog messages with optional prepended fields in a fixed order:
4+
//
5+
// <PRI> [message_counter:] [sequence:] [hostname:] [*]timestamp: message
6+
//
7+
// Each component can be independently enabled or disabled on the Cisco device,
8+
// and the parser must be configured to match the device's configuration.
9+
//
10+
// See rfc3164.WithCiscoIOSComponents() documentation in the rfc3164 package for detailed
11+
// usage instructions and Cisco device configuration examples.
112
package ciscoios
213

314
type Component int

‎rfc3164/machine_test.go‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -339,6 +339,11 @@ var testCases = []testCase{
339339
// parsing disabled. Note that if we were to also leave the sequence number and
340340
// hostname parsers enabled then the message counter would be parsed as the
341341
// sequence number, and the sequence number as the hostname.
342+
//
343+
// This demonstrates a known limitation: the parser cannot auto-detect which
344+
// Cisco components are present because they all follow the pattern "digits/alphanum:".
345+
// Users must configure the parser flags to match their Cisco device configuration.
346+
// Mismatched configuration will result in parsing errors or incorrect field values.
342347
opts: []syslog.MachineOption{
343348
WithCiscoIOSComponents(ciscoios.DisableMessageCounter | ciscoios.DisableSequenceNumber | ciscoios.DisableHostname),
344349
},

‎rfc3164/options.go‎

Lines changed: 72 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -75,13 +75,80 @@ func WithSecondFractions() syslog.MachineOption {
7575
}
7676
}
7777

78-
// WithCiscoIOSComponents configures the parser with specific Cisco IOS format components.
78+
// WithCiscoIOSComponents enables parsing of non-standard Cisco IOS syslog extensions.
7979
//
80-
// By default, all Cisco IOS components are enabled. Use the flags to disable specific components:
80+
// Cisco IOS devices can prepend additional fields before the timestamp when logging
81+
// to remote syslog servers. This option enables parsing of up to three components:
8182
//
82-
// rfc3164.WithCiscoIOSComponents(
83-
// ciscoios.DisableMessageCounter | ciscoios.DisableSequenceNumber | ciscoios.DisableHostname | ciscoios.DisableSecondFractions
84-
// )
83+
// 1. SYSLOG MESSAGE COUNTER (enabled by default, disable with ciscoios.DisableMessageCounter):
84+
// - Automatically added when logging to remote syslog servers
85+
// - Can be disabled on device: "no logging message-counter syslog"
86+
// - Format: <PRI>NNN: timestamp
87+
// - When disabled on device, sends: <PRI>: timestamp (empty field with colon)
88+
// - Example: <189>237: *Jan 8 19:46:03.295: %SYS-5-CONFIG_I: ...
89+
// - Cisco docs: https://www.cisco.com/c/en/us/td/docs/routers/access/wireless/software/guide/SysMsgLogging.html
90+
//
91+
// 2. SERVICE SEQUENCE NUMBER (enabled by default, disable with ciscoios.DisableSequenceNumber):
92+
// - Enabled on device with: "service sequence-numbers"
93+
// - Global sequence counter for all messages on the device
94+
// - Format: <PRI>[msgcount:] NNNNNN: timestamp
95+
// - Example: <189>237: 000485: *Jan 8 19:46:03.295: %SYS-5-CONFIG_I: ...
96+
// - Cisco docs: https://www.cisco.com/c/en/us/td/docs/routers/access/wireless/software/guide/SysMsgLogging.html#wp1054751
97+
//
98+
// 3. ORIGIN HOSTNAME (enabled by default, disable with ciscoios.DisableHostname):
99+
// - Enabled on device with: "logging origin-id hostname"
100+
// - Adds hostname before timestamp
101+
// - Format: <PRI>[msgcount:] [seqnum:] hostname: timestamp
102+
// - Example: <189>237: 000485: router1: *Jan 8 19:46:03.295: ...
103+
//
104+
// IMPORTANT CONFIGURATION REQUIREMENT:
105+
// The parser options must match your Cisco device configuration.
106+
// Since all three components use the format "digits:" or "alphanumeric:",
107+
// the parser cannot (at the moment) automatically detect which fields are present if they're selectively disabled.
108+
//
109+
// Common Cisco Configurations:
110+
//
111+
// ciscoios.All // Message counter + sequence + hostname + milliseconds (default)
112+
// ciscoios.DisableSequenceNumber // Message counter + hostname only
113+
// ciscoios.DisableHostname // Message counter + sequence only
114+
// ciscoios.DisableSequenceNumber | ciscoios.DisableHostname // Message counter only
115+
//
116+
// Cisco Device Configuration Examples:
117+
//
118+
// For message counter only (most common):
119+
//
120+
// conf t
121+
// logging host 10.0.0.10
122+
// ! Message counter is enabled by default for remote logging
123+
// ! No additional configuration needed
124+
//
125+
// To add service sequence numbers:
126+
//
127+
// conf t
128+
// service sequence-numbers
129+
// logging host 10.0.0.10
130+
//
131+
// To add hostname:
132+
//
133+
// conf t
134+
// logging origin-id hostname
135+
// logging host 10.0.0.10
136+
//
137+
// To disable message counter on Cisco device:
138+
//
139+
// conf t
140+
// no logging message-counter syslog
141+
// ! Device will send: <PRI>: timestamp (colon with no digits)
142+
// ! Parser will interpret this as MessageCounter = 0
143+
//
144+
// KNOWN LIMITATION:
145+
// If your Cisco device configuration does not match the parser flags, parsing
146+
// will fail or produce incorrect results. For example, if the device sends
147+
// message counter + sequence but the parser is configured for sequence only,
148+
// the message counter will be incorrectly parsed as the sequence number.
149+
//
150+
// The ciscoios.All flag enables all components plus WithSecondFractions() for
151+
// parsing millisecond timestamps that Cisco IOS can send.
85152
func WithCiscoIOSComponents(flags ciscoios.Component) syslog.MachineOption {
86153
return func(m syslog.Machine) syslog.Machine {
87154
if flags&ciscoios.DisableMessageCounter == 0 {

0 commit comments

Comments
 (0)