Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

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:

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:

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.

Note

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:

  1. Specify a host, any facility, and the error severity level.
    Note

    You can configure more than one system log message server (host). The QFabric system sends the messages to each server configured.

  2. (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 any and 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.

  3. (Optional) Configure the maximum size of your system log message archive file. This example specifies an archive size of 1 GB.

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.

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.

Note

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:

Note

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:

Note

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.

Note

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 /dev/console by the kernel console output r

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.

Note

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):

Note

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:

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:

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.

Note

The match statement is not case-sensitive.

Table 4: Regular Expression Operators for the match Statement

OperatorMatches

. (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:

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:

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.

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:

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:

  • Configure New York routing platforms to aggregate messages in the local2 facility:

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.