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 devices 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
filestatement. 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
userstatement. See Directing System Log Messages to a User Terminal.To the router console, by including the
consolestatement. See Directing System Log Messages to the Console.-
To a remote machine that is running the syslogd utility, by including the
hoststatement. 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 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-prioritystatement. 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 Junos OS or messages generated on particular devices. 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:
[edit system] syslog { archive <files number> <size size> <world-readable | no-world-readable>; console { facility severity; } file filename { facility severity; archive <archive-sites (ftp-url <password password>)> <files number> <size size> <start-time "YYYY-MM-DD.hh:mm"> <transfer-interval minutes> <world-readable | no-world-readable>; explicit-priority; match "regular-expression"; structured-data { brief; } } host hostname { facility severity; explicit-priority; facility-override facility; log-prefix string match "regular-expression"; } source-address source-address; time-format (year | millisecond | year millisecond); user (username | *) { facility severity; match "regular-expression"; } }
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.
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: Configure 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
Procedure
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.
set system syslog host 10.1.1.12 any error set system syslog file qflogs set system syslog file qflogs structured-data brief set system syslog file qflogs archive size 1g
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
errorseverity 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 messages is configured implicitly with facility and severity levels of
any anyand a file size of 100 MBs. Therefore, you cannot specify the filename messages in your configuration, and automatic command completion does not work for that filename.[edit system syslog] user@switch# set file qflogs structured-data brief user@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.
[edit]
user@switch# show system
syslog {
file qflogs {
}
host 10.1.1.12 {
any error;
}
}
If you are done configuring the device, enter commit from configuration mode.
Log 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:
[edit system syslog file filename] facility severity; structured-data { brief; }
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.
Specify 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:
archive <files number> <size size> <world-readable | no-world-readable>;
To configure values that apply to a specific log
file, include the archive statement at the [edit system syslog file filename] hierarchy level:
archive <archive-sites (ftp-url <password password>)> <files number> <size size> <start-time "YYYY-MM-DD.hh:mm"> <transfer-interval minutes> <world-readable | no-world-readable> ;
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.
Include 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:
[edit system syslog file filename] facility severity; explicit-priority;
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:
[edit system syslog host (hostname | other-routing-engine)] facility severity; explicit-priority;
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:
FACILITY-severity[-TAG]
(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):
Aug 21 12:36:30 router1 chassisd[522]: %DAEMON-6-CHASSISD_PARSE_COMPLETE: Using new configuration
When the explicit-priority statement
is not included, the priority does not appear in the message:
Aug 21 12:36:30 router1 chassisd[522]: CHASSISD_PARSE_COMPLETE: Using new configuration
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.
Code |
Junos Facility Name |
Type of Event or Error |
|---|---|---|
|
|
Authentication and authorization attempts |
|
|
Authentication and authorization attempts that can be viewed by superusers only |
|
|
Changes to Junos OS configuration |
|
|
Specified configuration is invalid on the router type |
|
|
Messages written to /dev/console by the kernel console output r |
|
|
Actions performed or errors encountered by the cron process |
|
|
Actions performed or errors encountered by system processes |
|
|
Actions performed or errors encountered by the dynamic flow capture process |
|
|
Packet filtering actions performed by a firewall filter |
|
|
Actions performed or errors encountered by the FTP process |
|
|
Commands issued at the Junos OS CLI prompt or invoked by a client application such as a Junos XML protocol or NETCONF client |
|
|
Actions performed or errors encountered by the Junos kernel |
|
|
Actions performed or errors encountered by the Network Time Protocol (NTP) |
|
|
Actions performed or errors encountered by the Packet Forwarding Engine |
|
|
Actions performed or errors encountered by the Junos system logging utility |
|
|
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.
Numerical Code |
Severity Level |
Description |
|---|---|---|
|
|
System panic or other condition that causes the router to stop functioning |
|
|
Conditions that require immediate correction, such as a corrupted system database |
|
|
Critical conditions, such as hard errors |
|
|
Error conditions that generally have less serious consequences than errors in the emergency, alert, and critical levels |
|
|
Conditions that warrant monitoring |
|
|
Conditions that are not errors but might warrant special handling |
|
|
Events or nonerror conditions of interest |
|
|
Software debugging messages (these appear only if a technical support representative has instructed you to configure this severity level) |
Include 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:
Aug 21 12:36:30
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:
[edit system syslog] time-format (year | millisecond | year millisecond);
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):
Aug 21 12:36:30.401 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.
Use 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.
| 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:
timestamp router-name mgd[PID]: UI_CMDLINE_READ_LINE: User 'user', command 'configure private'
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
Operator |
Matches |
|---|---|
|
One instance of any character except the space. |
|
Zero or more instances of the immediately preceding term. |
|
One or more instances of the immediately preceding term. |
|
Zero or one instance of the immediately preceding term. |
|
One of the terms that appear on either side of the pipe operator. |
|
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. |
|
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. |
|
The end of a line. |
|
One instance of one of the enclosed alphanumeric characters.
To indicate a range of characters, use a hyphen ( |
|
One instance of the evaluated value of the enclosed term. Parentheses are used to indicate the order of evaluation in the regular expression. |
Disable 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:
[edit system syslog]
console {
any error;
daemon none;
kernel none;
}
file internals {
daemon info;
kernel info;
}
Examples: Configure 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:
[edit system]
syslog {
file cli-commands {
interactive-commands info;
authorization info;
}
user * {
interactive-commands info;
authorization info;
}
}
The following example shows how to configure the logging of all changes in the state of alarms to the file /var/log/alarms:
[edit system]
syslog {
file alarms {
kernel warning;
}
}
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:
[edit system]
syslog {
/* write all security-related messages to file /var/log/security */
file security {
authorization info;
interactive-commands info;
}
/* write messages about potential problems to file /var/log/messages: */
/* messages from "authorization" facility at level "notice" and above, */
/* messages from all other facilities at level "warning" and above */
file messages {
authorization notice;
any warning;
}
/* write all messages at level "critical" and above to terminal of user "alex" if */
/* that user is logged in */
user alex {
any critical;
}
/* write all messages from the "daemon" facility at level "info" and above, and */
/* messages from all other facilities at level "warning" and above, to the */
/* machine monitor.mycompany.com */
host monitor.mycompany.com {
daemon info;
any warning;
}
/* write all messages at level "error" and above to the system console */
console {
any error;
}
}
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 commandsrollbackandcommit. The example writes the messages to the terminal of userphilip.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: Assign 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
local0facility:[edit system syslog] host central-logger.mycompany.com { change-log info; facility-override local0; }Configure New York routing platforms to aggregate messages in the
local2facility:[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.