System Logging on a Single-Chassis System
Single-Chassis System Logging Configuration Overview
The Junos system logging utility is similar to the UNIX syslogd utility. This section describes how to configure system logging for a single-chassis system that runs the Junos OS.
System logging configuration for the Junos-FIPS software and for Juniper Networks routers in a Common Criteria environment is the same as for the Junos OS. For more information, see the Secure Configuration Guide for Common Criteria and Junos-FIPS.
For information about configuring system logging for a routing matrix composed of a TX Matrix router and T640 routers, see Configuring System Logging for a TX Matrix Router.
Each system log message belongs to a facility, which groups together related messages. Each message is also preassigned a severity level, which indicates how seriously the triggering event affects router functions. You always specify the facility and severity of the messages to include in the log. For more information, see Specifying the Facility and Severity of Messages to Include in the Log.
You direct messages to one or more destinations by including the appropriate statement at the [edit system syslog] hierarchy level:
To a named file in a local file system, by including the file statement. See Directing System Log Messages to a Log File.
To the terminal session of one or more specific users (or all users) when they are logged in to the router, by including the user statement. See Directing System Log Messages to a User Terminal.
To the router console, by including the console statement. See Directing System Log Messages to the Console.
To a remote machine that is running the syslogd utility or to the other Routing Engine on the router, by including the host statement.
By default, messages are logged in a standard format, which is based on a UNIX system log format; for detailed information about message formatting, see the System Log Explorer. You can alter the content and format of logged messages in the following ways:
You can log messages to a file in structured-data format instead of the standard Junos format. Structured-data format provides more information without adding significant length, and makes it easier for automated applications to extract information from the message. For more information, see Logging Messages in Structured-Data Format.
A message’s facility and severity level are together referred to as its priority. By default, the standard Junos format for messages does not include priority information (structured-data format includes a priority code by default.) To include priority information in standard-format messages directed to a file or a remote destination, include the explicit-priority statement. For more information, see Including Priority Information in System Log Messages.
By default, the standard Junos format for messages specifies the month, date, hour, minute, and second when the message was logged. You can modify the timestamp on standard-format system log messages to include the year, the millisecond, or both. (Structured-data format specifies the year and millisecond by default.) For more information, see Including the Year or Millisecond in Timestamps.
When directing messages to a remote machine, you can specify the IP address that is reported in messages as their source. You can also configure features that make it easier to separate messages generated by the Junos OS or messages generated on particular routers.
The predefined facilities group together related messages, but you can also use regular expressions to specify more exactly which messages from a facility are logged to a file, a user terminal, or a remote destination. For more information, see Using Strings and Regular Expressions to Refine the Set of Logged Messages.
Overview of Single-Chassis System Logging Configuration
The Junos OS system logging utility on the QFX Series is similar to the UNIX syslogd utility. This topic describes how to configure system logging for a single-chassis system that runs the Junos OS.
Each system log message belongs to a facility, which groups together related messages. Each message is also preassigned a severity level, which indicates how seriously the triggering event affects router functions. You always specify the facility and severity of the messages to include in the log. For more information, see Specifying the Facility and Severity of Messages to Include in the Log.
You direct messages to one or more destinations by including the appropriate statement at the [edit system syslog] hierarchy level:
To a named file in a local file system, by including the file statement. See Directing System Log Messages to a Log File.
To the terminal session of one or more specific users (or all users) when they are logged in to the switch, by including the user statement. See Directing System Log Messages to a User Terminal.
To the switch console, by including the console statement. See Directing System Log Messages to the Console.
To a remote machine that is running the syslogd utility, by including the host statement. See Directing System Log Messages to a Remote Machine.
By default, messages are logged in a standard format, which is based on a UNIX system log format; for detailed information about message formatting, see the Junos OS System Log Messages Reference. You can alter the content and format of logged messages in the following ways:
You can log messages to a file in structured-data format instead of the standard Junos OS format. Structured-data format provides more information without adding significant length, and makes it easier for automated applications to extract information from the message. For more information, see Logging Messages in Structured-Data Format.
A message’s facility and severity level are together referred to as its priority. By default, the standard Junos OS format for messages does not include priority information (structured-data format includes a priority code by default). To include priority information in standard-format messages directed to a file or a remote destination, include the explicit-priority statement. For more information, see Including Priority Information in System Log Messages.
By default, the standard Junos OS format for messages specifies the month, date, hour, minute, and second when the message was logged. You can modify the timestamp on standard-format system log messages to include the year, the millisecond, or both. (Structured-data format specifies the year and millisecond by default.) For more information, see Including the Year or Millisecond in Timestamps.
When directing messages to a remote machine, you can specify the IP address that is reported in messages as their source. You can also configure features that make it easier to separate messages generated by Junos OS or messages generated on particular switches. For more information, see Directing System Log Messages to a Remote Machine.
The predefined facilities group together related messages, but you can also use regular expressions to specify more exactly which messages from a facility are logged to a file, a user terminal, or a remote destination. For more information, see Using Strings and Regular Expressions to Refine the Set of Logged Messages.
During a commit check, warnings about the traceoptions configuration (for example, mismatch in trace file sizes or number of trace files) are not displayed on the console. However, these warnings are logged in the system log messages when the new configuration is committed.
Junos OS System Log Configuration Statements
To configure the switch to log system messages, include the syslog statement at the [edit system] hierarchy level:
Junos OS Minimum System Logging Configuration
To record or view system log messages, you must include the syslog statement at the [edit system] hierarchy level. Specify at least one destination for the messages, as described in Table 1. For more information about the configuration statements, see Single-Chassis System Logging Configuration Overview.
Table 1: Minimum Configuration Statements for System Logging
Destination | Minimum Configuration Statements |
|---|---|
File | [edit system syslog] file filename { facility severity; } |
Terminal session of one, several, or all users | [edit system syslog] user (username | *) { facility severity; } |
Router or switch console | [edit system syslog] console { facility severity; } |
Remote machine or the other Routing Engine on the router or switch | [edit system syslog] host (hostname | other-routing-engine)
{ facility severity; } |
Example: Configuring System Log Messages
The QFabric system monitors events that occur on its component devices and distributes system log messages about those events to all external system log message servers (hosts) that are configured. Component devices may include Node devices, Interconnect devices, Director devices, and the Virtual Chassis. Messages are stored for viewing only in the QFabric system database. To view the messages, issue the show log command.
This example describes how to configure system log messages on the QFabric system.
Requirements
This example uses the following hardware and software components:
Junos OS Release 12.2
QFabric system
External servers that can be configured as system log message hosts
Overview
Component devices that generate system log message events may include Node devices, Interconnect devices, Director devices, and the control plane switches. The following configuration example includes these components in the QFabric system:
Director software running on the Director group
Control plane switches
Interconnect device
Multiple Node devices
Configuration
CLI Quick Configuration
To quickly configure this example, copy the following commands, paste them into a text file, remove any line breaks, change any details necessary to match your network configuration, and then copy and paste the commands into the CLI at the [edit] hierarchy level.
Step-by-Step Procedure
The following example requires that you navigate various levels in the configuration hierarchy. For instructions on how to do that, see Using the CLI Editor in Configuration Mode in the Junos OS CLI User Guide .
To configure system messages from the QFabric Director device:
- Specify a host, any facility, and the error severity level.[edit system syslog]user@switch# set host 10.1.1.12 any error
Note You can configure more than one system log message server (host). The QFabric system sends the messages to each server configured.
- (Optional) Specify a filename to capture log messages.
Note On the QFabric system, a syslog file named
messagesis configured implicitly with facility and severity levels of any any and a file size of 100 MBs. Therefore, you cannot specify the filenamemessagesin your configuration, and automatic command completion does not work for that filename.[edit system syslog]user@switch# set file qflogs structured-data briefuser@switch# set file qflogs - (Optional) Configure the maximum size of your system log
message archive file. This example specifies an archive size of 1
GB.[edit system syslog]user@switch# set file qflogs archive size 1g
Results
From configuration mode, confirm your configuration by entering the show system command. If the output does not display the intended configuration, repeat the instructions in this example to correct the configuration.
If you are done configuring the device, enter commit from configuration mode.
See also
Logging Messages in Structured-Data Format
You can log messages to a file in structured-data format instead of the standard Junos OS format. Structured-data format provides more information without adding significant length, and makes it easier for automated applications to extract information from a message.
The structured-data format complies with Internet standard RFC 5424, The Syslog Protocol, which is at https://tools.ietf.org/html/rfc5424. The RFC establishes a standard message format regardless of the source or transport protocol for logged messages.
To output messages to a file in structured-data format, include the structured-data statement at the [edit system syslog file filename] hierarchy level:
The optional brief statement suppresses the English-language text that appears by default at the end of a message to describe the error or event.
The structured format is used for all messages logged to the file that are generated by a Junos process or software library.
If you include either or both of the explicit-priority and time-format statements along with the structured-data statement, they are ignored. These statements apply to the standard Junos OS system log format, not to structured-data format.
Specifying Log File Size, Number, and Archiving Properties
To prevent log files from growing too large, by default the Junos OS system logging utility writes messages to a sequence of files of a defined size. The files in the sequence are referred to as archive files to distinguish them from the active file to which messages are currently being written. The default maximum size depends on the platform type:
128 kilobytes (KB) for EX Series switches
1 megabyte (MB) for M Series, MX Series, and T Series routers
10 MB for TX Matrix or TX Matrix Plus routers
1 MB for the QFX Series
When an active log file called logfile reaches the maximum
size, the logging utility closes the file, compresses it, and names
the compressed archive file logfile.0.gz. The logging utility then opens and writes
to a new active file called logfile. This process is also known as file rotation. When
the new logfile reaches the configured maximum size, logfile.0.gz is renamed logfile.1.gz, and the new logfile is closed, compressed, and renamed logfile.0.gz. By default, the
logging utility creates up to 10 archive files in this manner. When
the maximum number of archive files is reached and when the size of
the active file reaches the configured maximum size, the contents
of the last archived file are overwritten by the current active file.
The logging utility by default also limits the users who can read
log files to the root user and users who have Junos OS maintenance permission.
Junos OS provides a configuration statement log-rotate-frequency that configures the system log file rotation frequency by configuring the time interval for checking the log file size. The frequency can be set to a value of 1 minute through 59 minutes. The default frequency is 15 minutes.
To configure the log rotation frequency, include the log-rotate-frequency statement at the [edit system syslog] hierarchy level.
You can include the archive statement to change the maximum size of each file, how many archive files are created, and who can read log files.
To configure values that apply to all log files, include the archive statement at the [edit system syslog] hierarchy level:
To configure values that apply to a specific log file, include the archive statement at the [edit system syslog file filename] hierarchy level:
archive-sites site-name specifies a list of archive sites that you want to use for storing files. The site-name value is any valid FTP URL to a destination. If more than one site name is configured, a list of archive sites for the system log files is created. When a file is archived, the router or switch attempts to transfer the file to the first URL in the list, moving to the next site only if the transfer does not succeed. The log file is stored at the archive site with the specified log filename. For information about how to specify valid FTP URLs, see Format for Specifying Filenames and URLs in Junos OS CLI Commands.
binary-data Mark file as containing binary data. This allows proper archiving of binary files, such as WTMP files (login records for UNIX based systems). To restore the default setting, include the no-binary-data statement.
files number specifies the number of files to create before the oldest file is overwritten. The value can be from 1 through 1000.
size size specifies the maximum size of each file. The value can be from 64 KB (64k) through 1 gigabyte (1g); to represent megabytes, use the letter m after the integer. There is no space between the digits and the k, m, or g units letter.
start-time "YYYY-MM-DD.hh:mm" defines the date and time in the local time zone for a one-time transfer of the active log file to the first reachable site in the list of sites specified by the archive-sites statement.
transfer-interval interval defines the amount of time the current log file remains open (even if it has not reached the maximum possible size) and receives new statistics before it is closed and transferred to an archive site. This interval value can be from 5 through 2880 minutes.
world-readable enables all users to read log files. To restore the default permissions, include the no-world-readable statement.
Including Priority Information in System Log Messages
The facility and severity level of a message are together referred to as its priority. By default, messages logged in the standard Junos OS format do not include information about priority. To include priority information in standard-format messages directed to a file, include the explicit-priority statement at the [edit system syslog file filename] hierarchy level:
Messages logged in structured-data format include priority information by default. If you include the structured-data statement at the [edit system syslog file filename] hierarchy level along with the explicit-priority statement, the explicit-priority statement is ignored and messages are logged in structured-data format.
For information about the structured-data statement, see Logging Messages in Structured-Data Format.
To include priority information in messages directed to a remote machine or the other Routing Engine, include the explicit-priority statement at the [edit system syslog host (hostname | other-routing-engine)] hierarchy level:
The other-routing-engine option does not apply to the QFX Series.
The priority recorded in a message always indicates the original, local facility name. If the facility-override statement is included for messages directed to a remote destination, the Junos OS system logging utility still uses the alternative facility name for the messages themselves when directing them to the remote destination. For more information, see Changing the Alternative Facility Name for System Log Messages Directed to a Remote Destination.
When the explicit-priority statement is included, the Junos OS logging utility prepends codes for the facility name and severity level to the message tag name, if the message has one:
(The tag is a unique identifier assigned to some Junos OS system log messages.)
In the following example, the CHASSISD_PARSE_COMPLETE message belongs to the daemon facility and is assigned severity info (6):
When the explicit-priority statement is not included, the priority does not appear in the message:
System Log Facility Codes and Numerical Codes Reported in Priority Information
Table 2 lists the facility codes that can appear in system log messages and maps them to facility names.
If the second column in Table 2 does not include the Junos OS facility name for a code, the facility cannot be included in a statement at the [edit system syslog] hierarchy level. Junos OS might use the facilities in Table 2—and others that are not listed—when reporting on internal operations.
Table 2: Facility Codes Reported in Priority Information
Code | Junos Facility Name | Type of Event or Error |
|---|---|---|
AUTH | authorization | Authentication and authorization attempts |
AUTHPRIV |
| Authentication and authorization attempts that can be viewed by superusers only |
CHANGE | change-log | Changes to Junos OS configuration |
CONFLICT | conflict-log | Specified configuration is invalid on the router type |
CONSOLE |
| Messages written to |
CRON |
| Actions performed or errors encountered by the cron process |
DAEMON | daemon | Actions performed or errors encountered by system processes |
DFC | dfc | Actions performed or errors encountered by the dynamic flow capture process |
FIREWALL | firewall | Packet filtering actions performed by a firewall filter |
FTP | ftp | Actions performed or errors encountered by the FTP process |
INTERACT | interactive-commands | Commands issued at the Junos OS CLI prompt or invoked by a client application such as a Junos XML protocol or NETCONF client |
KERN | kernel | Actions performed or errors encountered by the Junos kernel |
NTP |
| Actions performed or errors encountered by the Network Time Protocol (NTP) |
PFE | pfe | Actions performed or errors encountered by the Packet Forwarding Engine |
SYSLOG |
| Actions performed or errors encountered by the Junos system logging utility |
USER | user | Actions performed or errors encountered by user-space processes |
Table 3 lists the numerical severity codes that can appear in system log messages and maps them to severity levels.
Table 3: Numerical Codes for Severity Levels Reported in Priority Information
Numerical Code | Severity Level | Description |
|---|---|---|
0 | emergency | System panic or other condition that causes the router to stop functioning |
1 | alert | Conditions that require immediate correction, such as a corrupted system database |
2 | critical | Critical conditions, such as hard errors |
3 | error | Error conditions that generally have less serious consequences than errors in the emergency, alert, and critical levels |
4 | warning | Conditions that warrant monitoring |
5 | notice | Conditions that are not errors but might warrant special handling |
6 | info | Events or nonerror conditions of interest |
7 | debug | Software debugging messages (these appear only if a technical support representative has instructed you to configure this severity level) |
Including the Year or Millisecond in Timestamps
By default, the timestamp recorded in a standard-format system log message specifies the month, date, hour, minute, and second when the message was logged, as in the following example:
To include the year, the millisecond, or both in the timestamp, include the time-format statement at the [edit system syslog] or [edit security log] hierarchy levels:
However, the timestamp for traceoption messages is specified in milliseconds by default, and is independent of the [edit system syslog time-format] statement.
The modified timestamp is used in messages directed to each destination configured by a file, console, or user statement at the [edit system syslog] hierarchy level, but not to destinations configured by a host statement.
By default, in a FreeBSD console, the additional time information is not available in system log messages directed to each destination configured by a host statement. However, in a Junos OS specific implementation using the FreeBSD console, the additional time information is available in system log messages directed to each destination.
The following example illustrates the format for a timestamp that includes both the millisecond (401) and the year (2006):
Messages logged in structured-data format include the year and millisecond by default. If you include the structured-data statement at the [edit system syslog file filename] hierarchy level along with the time-format statement, the time-format statement is ignored and messages are logged in structured-data format.
For information about the structured-data statement, see Logging Messages in Structured-Data Format.
Using Strings and Regular Expressions to Refine the Set of Logged Messages
The predefined facilities group together related messages, but you can also match messages against strings and regular expressions to refine which messages from a facility are logged to a file, a user terminal, or a remote destination.
The match-strings and match configuration statements enable you to match system log messages against a string or regular expression, respectively. You can include these statements at the following hierarchy levels:
[edit system syslog file filename] (for a file)
[edit system syslog user (username | *)] (for a specific user session or for all user sessions on a terminal)
[edit system syslog host (hostname | other-routing-engine)] (for a remote destination)
To evaluate messages against a regular expression and only log matching messages to the given destination, include the match statement and specify the regular expression:
match "regular-expression";Starting with Junos OS Release 16.1, you can use simple string comparisons to more efficiently filter messages, because it is less CPU-intensive than matching against complex regular expressions. To specify the text string that must appear in a message for the message to be logged to a destination, include the match-strings statement and specify the matching string or list of strings:
match-strings string-name;match-strings [string1 string2];The match-strings and match statements select messages with the configured facility and severity that match the given string or regular expression. The match-strings statement performs a simple string comparison, and as a result, it is less CPU-intensive than using the match statement to match against complex regular expressions. If you configure both the match and match-strings statements for the same destination, Junos OS evaluates the match-strings condition first; if the message includes any of the configured substrings, then the message is logged and the match condition is not evaluated. If the match-strings condition is not satisfied, then the system evaluates the message against the regular expression in the match configuration statement.
When specifying regular expressions for the match statement, use the notation defined in POSIX Standard 1003.2 for extended (modern) UNIX regular expressions. Explaining regular expression syntax is beyond the scope of this document, but POSIX standards are available from the Institute of Electrical and Electronics Engineers (IEEE, http://www.ieee.org).
Table 4 specifies which character or characters are matched by some of the regular expression operators that you can use in the match statement. In the descriptions, the term term refers to either a single alphanumeric character or a set of characters enclosed in square brackets, parentheses, or braces.
The match statement is not case-sensitive.
Table 4: Regular Expression Operators for the match Statement
| Operator | Matches |
|---|---|
. (period) | One instance of any character except the space. |
* (asterisk) | Zero or more instances of the immediately preceding term. |
+ (plus sign) | One or more instances of the immediately preceding term. |
? (question mark) | Zero or one instance of the immediately preceding term. |
| (pipe) | One of the terms that appears on either side of the pipe operator. |
! (exclamation point) | Any string except the one specified by the expression, when the exclamation point appears at the start of the expression. Use of the exclamation point is Junos OS-specific. |
^ (caret) | Start of a line, when the caret appears outside square brackets. One instance of any character that does not follow it within square brackets, when the caret is the first character inside square brackets. |
$ (dollar sign) | End of a line. |
[ ] (paired square brackets) | One instance of one of the enclosed alphanumeric characters. To indicate a range of characters, use a hyphen ( - ) to separate the beginning and ending characters of the range. For example, [a-z0-9] matches any letter or number. |
( ) (paired parentheses) | One instance of the evaluated value of the enclosed term. Parentheses are used to indicate the order of evaluation in the regular expression. |
Using Strings and Regular Expressions
Filter messages that belong to the interactive-commands facility, directing those that include the string configure to the terminal of the root user:
[edit system syslog]
user root {
interactive-commands any;
match-strings configure;
}Messages like the following appear on the root user’s terminal when a user issues a configure command to enter configuration mode:
Filter messages that belong to the daemon facility
and have a severity of error or higher, directing them
to the file /var/log/process-errors. Omit messages generated by the SNMP process (snmpd), instead directing
them to the file /var/log/snmpd-errors:
[edit system syslog]
file process-errors {
daemon error;
match "!(.*snmpd.*)";
}
file snmpd-errors {
daemon error;
match-strings snmpd;
}Junos System Log Regular Expression Operators for the match Statement
Table 5: Regular Expression Operators for the match Statement
Operator | Matches |
|---|---|
. (period) | One instance of any character except the space. |
* (asterisk) | Zero or more instances of the immediately preceding term. |
+ (plus sign) | One or more instances of the immediately preceding term. |
? (question mark) | Zero or one instance of the immediately preceding term. |
| (pipe) | One of the terms that appear on either side of the pipe operator. |
! (exclamation point) | Any string except the one specified by the expression, when the exclamation point appears at the start of the expression. Use of the exclamation point is Junos OS–specific. |
^ (caret) | The start of a line, when the caret appears outside square brackets. One instance of any character that does not follow it within square brackets, when the caret is the first character inside square brackets. |
$ (dollar sign) | The end of a line. |
[ ] (paired square brackets) | One instance of one of the enclosed alphanumeric characters. To indicate a range of characters, use a hyphen ( - ) to separate the beginning and ending characters of the range. For example, [a-z0-9] matches any letter or number. |
( ) (paired parentheses) | One instance of the evaluated value of the enclosed term. Parentheses are used to indicate the order of evaluation in the regular expression. |
Disabling the System Logging of a Facility
To disable the logging of messages that belong
to a particular facility, include the facility none statement in the configuration. This statement is
useful when, for example, you want to log messages that have the same
severity level and belong to all but a few facilities. Instead of
including a statement for each facility you want to log, you can include
the any severity statement and
then a facility none statement
for each facility that you do not want to log. For example, the following
logs all messages at the error level or higher to the console,
except for messages from the daemon and kernel facilities. Messages from those facilities are logged to the file >/var/log/internals instead:
Examples: Configuring System Logging
The following example shows how to configure the
logging of messages about all commands entered by users at the CLI
prompt or invoked by client applications such as Junos OS XML protocol
or NETCONF client applications, and all authentication or authorization
attempts, both to the file cli-commands and to the terminal of any user who is logged in:
The following example shows how to configure the
logging of all changes in the state of alarms to the file /var/log/alarms:
The following example shows how to configure the handling of messages of various types, as described in the comments. Information is logged to two files, to the terminal of user alex, to a remote machine, and to the console:
The following example shows how to configure the handling of messages generated when users issue Junos OS CLI commands, by specifying the interactive-commands facility at the following severity levels:
info—Logs a message when users issue any command at the CLI operational or configuration mode prompt. The example writes the messages to the file
/var/log/user-actions.notice—Logs a message when users issue the configuration mode commands rollback and commit. The example writes the messages to the terminal of user philip.
warning—Logs a message when users issue a command that restarts a software process. The example writes the messages to the console.
[edit system]syslog {file user-actions {interactive-commands info;}user philip {interactive-commands notice;}console {interactive-commands warning;}}
Examples: Assigning an Alternative Facility
Log all messages generated on the local routing platform at the error level or higher to the local0 facility on the remote machine called monitor.mycompany.com:
[edit system syslog]
host monitor.mycompany.com {
any error;
facility-override local0;
}Configure routing platforms located in California and routing platforms located in New York to send messages to a single remote machine called central-logger.mycompany.com. The messages from California are assigned alternative facility local0 and the messages from New York are assigned to alternative facility local2.
Configure California routing platforms to aggregate messages in the local0 facility:
[edit system syslog] host central-logger.mycompany.com { change-log info; facility-override local0; }Configure New York routing platforms to aggregate messages in the local2 facility:
[edit system syslog] host central-logger.mycompany.com { change-log info; facility-override local2; }
On central-logger you can then configure the system logging utility to write messages from the local0 facility to the file california-config and the messages from the local2 facility to the file new-york-config.