Logging Support

Introduction

The system produces a wealth of information in log files. Most of the log messages generated in the system are that of general events from the various system components. For some of the more important events that are logged, see Security Related Events.

The following methods for logging are available:

• Logging of default log files: By default all logs are written to an internal RAM disk. Log files written to the internal RAM disk are not persistent across reboots.

• Logging of default log files to USB: When enabled it will log the same things that are logged to the internal RAM disk, but it will be done to a connected external USB drive.

• Logging to console port: It is possible to direct logging messages to the console port. Messages of severity level DEBUG or higher are shown on the console port.

• Logging to user defined sinks: The logging system supports creation of customized logging sources, destinations and filters. These separate components are combined together to create a logging sink. This is a very flexible way to configure logging in the system. It allows for logging to remote machines, local files, or files on external media (USB or SD Card). The sources can also be configured to receive message from other remote machines. The optional filters can also be used to more precisely control what messages are logged.

Overview

The system continuously generates a wealth of information in the form of log messages. These messages serve as a vital resource for monitoring system performance, troubleshooting issues, and understanding system activities.

By default, all log messages are stored on the internal RAM disk. However, the system also provides flexibility in log management. You can configure it to direct these messages to custom log files located on either internal or external media. Alternatively, you can set up the system to forward these messages to remote log servers for centralized logging.

Before we delve into the specifics of configuring the logging system, it’s crucial to grasp the fundamentals of syslog messages. Understanding what a syslog message is and how it’s structured will provide a solid foundation for the subsequent sections.

The Anatomy of a Syslog Message

Depending on the syslog format that is used, a few different fields can be found in a syslog message, in addition to the actual message itself. Regardless of the format, something referred to as Facility and Severity are always present in a syslog message:

• Facility: The facility indicates the system component that generated the log message. It is used to categorize the message based on the type of system component that generated it. The facility is represented by a number between 0 and 23, where each number corresponds to a specific system component.

  These facilities, and some description of how the systems attempts to conform to them, can be seen in Table 1 below.

  #	Facility	Description
  0	kern	Kernel log messages
  1	user	User-level messages
  2	mail	Unused
  3	daemon	System daemons
  4	auth	Security/Authorization messages
  5	syslog	Unused
  6	lpr	Unused
  7	news	Unused
  8	uucp	Unused
  9	cron	Unused
  10	authpriv	Unused
  11	ftp	Unused
  12	ntp	NTP
  13	security	Log audit, for audit trail
  14	console	Log alert
  16	local0	Alarm sub-system
  17	local1	Unused
  18	local2	PPP
  19	local3	Unused
  20	local4	OpenVPN, IPsec
  21	local5	Reserved, OEM customer specific
  22	local6	Unused
  23	local7	Unused

  Table 1: All of the standard syslog facilities and their uses in the system.

  Note

  The facilities security and console are displayed as LOGAUDIT and LOGALERTin Wireshark, which is the de facto tool to debug all network traffic.

• Severity: The severity indicates the level of urgency or criticality of the message. It is used to classify the message based on its importance. The severity is represented by a number between 0 and 7, where each number corresponds to a specific level of criticality.

  These severities, and some description of how the systems attempts to conform to them, can be seen in Table 2 below.

  #	Severity	Description
  0	emerg	System level service only
  1	alert	System level service only
  2	crit	System level service only
  3	err	Severe error, daemon/service may restart
  4	warning	Significant problem, e.g. no connection to Radius server
  5	notice	General log message, e.g. login successful
  6	info	Informational, less important
  7	debug	Developer/low-level debug messages

  Table 2: All of the standard syslog severities and their general usage in the system.

The system allows for selection of what format to use, when configuring custom logging destinations. The different formats will be covered briefly in the following sections.

Log Message Formatting

For the examples below, we will use an example log message generated in the following manner: Sent from the program proc with the process ID 123, and the message Example Message.. The message is generated with the following facility and severity: user and notice.

The system supports three different syslog formats:

• BSD: A legacy BSD format. Given our example message, the raw format would look like this:

  <13>proc[123]: Example message.

  The individual fields are interpreted as follows:

  • Priority: The value within the angle brackets <13> is the combined Facility and Severity value.

  • Message: The remainder of the text following the colon : is the actual log message.

  Note

  In the BSD format, the program name and process ID are not distinctly separated from the message. They are included as part of the overall message text.

• RFC 3164: This is a standardized syslog format defined in RFC 3164. In this format, our example message would appear as follows:

  <13>May 21 10:36:31 example proc[123]: Message.

  The individual fields are represented by specific parts of the raw message:

  • Priority: The value <13> within the angle brackets represents the Priority, which is a combined value of Facility and Severity. This value is calculated by multiplying the Facility value by 8 and then adding the Severity value.

  • Timestamp: The May 21 10:36:31 part of the message represents the Timestamp, indicating the date and time when the message was generated. The timestamp is formatted according to the local time and date of the machine that generated the message.

  • Hostname: The example part of the message indicates the Hostname or IP address of the machine that generated the message. The hostname is used to identify the source of the message in a networked environment.

  • Process ID: The proc[123] part of the message is the Tag, which usually consists of the process name proc and process ID 123. The tag is used to identify the specific process that generated the message.

  • Message ID: The Message. part of the message following the colon is the actual log Message. This message contains the detailed information about the event that triggered the log entry.

  Note

  When viewed in a Wireshark capture, the PID 123 will be displayed as part of the Message ID filed, before the actual message.

• RFC 5424: This is a more modern syslog format defined in RFC 5424. In this format, our example message would appear as follows:

  <13>1 2024-05-21T12:18:24+00:00 example proc 123 - [meta sequenceId="4"] Message.

  The individual fields are represented by specific parts of the raw message:

  • Priority: The value <13> within the angle brackets represents the Priority, which is a combined value of Facility and Severity. This value is calculated by multiplying the Facility value by 8 and then adding the Severity value.

  • Version: The 1 following the priority field represents the version of the syslog protocol, as defined in RFC 5424. This version number, ‘1’, signifies that the message conforms to the first revision of the protocol that introduced changes to the header format.

  • Timestamp: The 2024-05-21T12:18:24+00:00 part of the message represents the Timestamp, indicating the date and time when the message was generated. The timestamp is formatted according to the ISO 8601 standard.

  • Hostname: The example part of the message indicates the Hostname or IP address of the machine that generated the message. The hostname is used to identify the source of the message in a networked environment.

  • Application Name: The proc part of the message is the Application Name, which usually identifies the device or application that originated the message.

  • Process Id: The 123 part of the message is the Process ID, which usually identifies the process that generated the message.

  • Message ID: The - part of the message is the Message ID, which is a unique identifier for the type of message. In this case, no Message ID is provided.

  • Structured-Data: The [meta sequenceId="4"] part of the message is the Structured-Data, which provides additional information about the message in a structured format.

  • Message: The Message. part of the message following the Structured-Data is the actual log Message.

Default Log Files

As mentioned earlier, the system will always create a number of default log files. These log files are stored on the internal RAM disk, under the /var/log/ directly. In Table 3 below, the default log files along with their associated facilities and severities are listed.

Table 3: Default log files and their associated facilities and severities.

The default log file in the system is the messages log file. This log file contains most of the log messages generated by the system. The auth log file contains log messages related to authentication, such as login attempts and authentication failures. The kern log file contains kernel log messages, providing information about the internal operations of the kernel. The syslog log file is also good to view if we want to see all log messages, including the kernel messages, except those related to authentication.

In order to list all the currently available log files located on the internal RAM disk, including the default log files, use the dir log command:

example:/#> dir log
example:/#> dir log
/log/                 MOD. DATE/LINK    SIZE  MD5                             
alarm                 2024-05-20 14:18   276
appendix.log          2024-05-20 14:18   118
auth.log              2024-05-20 14:18   754
bootsettings.log      2024-05-20 14:18    20
btmp                  2024-05-20 14:18     0
kern.log              2024-05-20 14:19  2772
lastlog               2024-05-20 14:18     0
messages              2024-05-20 14:49  7717
mount.log             2024-05-20 14:18  1170
ntp.log               2024-05-20 14:18   134
syslog                2024-05-20 14:49 10489
wtmp                  2024-05-20 14:18  2304

Free: 19.10 MiB | Total: 20.1 MiB                                             
example:/#>

To view the contents of a specific log file, the show log command can be used. As mentioned earlier, the messages log file is the main log file in the system, and it will be displayed if nothing else is specified:

example:/#> show log
[...]
May 20 14:53:46 example finit[1]: Starting lldpd:, PID: 1058
May 20 14:53:47 example lldpcli[1059]: lldpd should resume operations
______________________________________________________________________________
log://messages                                        Mon May 20 14:53:47 2024

example:/#>

In order to view a specific log file, the show log://FILE command can be used. For instance, to view the auth.log log file:

example:/#> show log://auth.log
[...]
May 20 14:18:15 example login[811]: Authentication successful for user 'admin'
May 20 14:18:15 example login[811]: pam_unix(login:session): session opened
for user admin(uid=0) by LOGIN(uid=0)
May 20 14:18:15 example login[912]: root login on 'console'
______________________________________________________________________________
log://auth.log                                        Mon May 20 14:18:15 2024

example:/#>

Remember the short-keys to the show command when listing long files:

• R: show the rest of the file
• q: Quit viewer

example:/#> follow log
Press Ctrl-C to abort
May 20 14:53:46 S1 dnsmasq[1047]: read /etc/hosts - 3 names
May 20 14:53:46 S1 finit[1]: Starting lldpd:, PID: 1058
May 20 14:53:47 S1 lldpcli[1059]: lldpd should resume operations

Security Related Events

The system produces a lot of different log messages, but there are a few that are considered a bit more important in terms of security. As such they are listen below, in Table 4.

Table 4: Security related events that are logged in the system.

The messages that are generated for these events should mostly conform to the examples given in Table 4. However, it is possible that the messages are slightly different. They are indicative of the type of messages that are generated for these events.

Logging Sink Overview

The system provides a highly customizable logging system that allows for the configuration of custom logging sources, destinations, and filters. These components are combined to create what is called a sink. A sink is a combination of the mentioned components and allows for the creation of customized logging setups.

In Figure 1 below, we show an example of the relationship between the different logging components and how they can be combined to create a logging sink. This simple example includes two sources, two destinations, and two filters. There are two sinks that combine the components in the following way:

• Sink-1: Utilizes Source-1, Source-2 and Destination-1.
• Sink-2: Utilizes Source-2, Destination-2, Filter-1, and Filter-2.

As we can see, source-2 is used in both sinks, and filter-1 and filter-2 are only used in sink-2 because they are optional components.

┌─Sources─────────────────────────┐ ┌─Destinations────────────────────┐ ┌─Filters─────────────────────────┐
│                                 │ │                                 │ │                                 │
│ ┌─────────────┐ ┌─────────────┐ │ │ ┌─────────────┐ ┌─────────────┐ │ │ ┌─────────────┐ ┌─────────────┐ │
│ │  Source-1   │ │  Source-2   │ │ │ │Destination-1│ │Destination-2│ │ │ │   Filter-1  │ │   Filter-2  │ │
│ └┬────────────┘ └┬────────────┘ │ │ └┬────────────┘ └┬────────────┘ │ │ └┬────────────┘ └┬────────────┘ │
│  │               │              │ │  │               │              │ │  │               │              │
│  ▼               ▼              │ │  ▼               ▼              │ │  ▼               ▼              │
└─────────────────────────────────┘ └─────────────────────────────────┘ └─────────────────────────────────┘
   │               │                   │               │                   │               │
   │ ┌─────────────┴─────────────────┐ │ ┌─────────────┘                   │               │
   │ │                               │ │ │                                 │               │
   │ │ ┌───────────────────────────────┘ │ ┌───────────────────────────────┘               │
   │ │ │                             │   │ │                                               │
   │ │ │                             │   │ │ ┌─────────────────────────────────────────────┘
   │ │ │                             │   │ │ │
   ▼ ▼ ▼                             ▼   ▼ ▼ ▼
┌─────────────┐                     ┌─────────────┐
│   Sink-1    │                     │   Sink-2    │
└─────────────┘                     └─────────────┘

Figure 1: The relationship between the different logging components and how they are combined to create a logging sink. Components can be combined and be reused across multiple sinks.

Configuration of these logging sinks is what allows for specialized logging setups, such as logging to remote machines, local files, or files on external media (USB or SD Card).

The way in which these components can be defined and combined allows for a very flexible and powerful logging system. The following sections will describe each of these components in more detail.

Supported Transport Protocols

Both logging sources and destinations can use the following transport protocols to send and receive log messages from remote machines:

• UDP: UDP (User Datagram Protocol) is a connectionless protocol that allows for fast and lightweight communication. It is commonly used for log message transmission due to its simplicity and low overhead. Log messages sent over UDP are not guaranteed to arrive at the destination, but they are typically sent in a fire-and-forget manner.

  Warning

  Messages will be sent in clear text, i.e. the messages will be readable by anyone who can intercept the messages.

• TCP: TCP (Transmission Control Protocol) is a reliable and connection-oriented protocol that ensures the delivery of log messages. It provides features such as error checking, flow control, and retransmission of lost packets. Log messages sent over TCP are guaranteed to arrive at the destination, but they may introduce additional latency compared to UDP.

  Warning

  Messages will be sent in clear text, i.e. the messages will be readable by anyone who can intercept the messages.

• TLS: TLS (Transport Layer Security) is a cryptographic protocol that provides secure communication over a network. It is used to encrypt log messages sent to remote destinations, ensuring the confidentiality and integrity of the data. TLS adds an extra layer of security to log message transmission, protecting against eavesdropping and tampering.

  Note

  TLS will use TCP as the underlying protocol.

  Tip

  Messages will be encrypted, i.e. the messages will not be readable by anyone who can intercept the messages.

  For more information on how certificates are used in the system, see the Certificate Management section.

In conclusion, the choice of transport protocol for log message transmission depends on the specific requirements of your system. UDP offers speed and simplicity, making it suitable for situations where high throughput is more important than guaranteed delivery. TCP, on the other hand, ensures that every log message reaches its destination, at the cost of additional latency. For secure communication, TLS is the go-to choice as it encrypts log messages, protecting them from eavesdropping and tampering. Remember, each protocol has its strengths and trade-offs, and the best choice depends on the balance between speed, reliability, and security in your specific use case.

Sources

A logging source is a component that specifies where the log messages originate from. There are different types of sources available:

• Local: Log messages generated by the system itself. Local log messages can be divided into two categories:

  • Userspace: Log messages generated by the system itself, including system services, applications, and other non-kernel related sources. These messages provide information about the behavior and status of various processes running on the system. Userspace log messages are typically used for troubleshooting and monitoring purposes.

  • Kernel: Log messages generated by the kernel itself, which is the core component of the operating system. Kernel log messages provide information about internal operations of the kernel, such as hardware events, driver activity, and system errors. These messages are crucial for diagnosing and debugging issues at the system level.

  Both userspace and kernel log messages are important for understanding the overall health and performance of a system. By analyzing these log messages, administrators and developers can identify issues, track system behavior, and make informed decisions for system optimization and troubleshooting.

• Remote: Log messages received from remote machines. When a remote source is defined, the system listens for incoming log messages on the specified port. The following transport protocols are supported: UDP, TCP, and TLS.

  Configuring a remote source allows the system to receive log messages from external sources, enabling centralized logging and monitoring of multiple systems.

  However, since our devices are typically not used as log servers, a more common approach would be to use them as log-server relays, forwarding log messages to a dedicated log server. One advantage of this solution is that log messages sent over UDP to the relay can be forwarded to the log server over a more reliable TCP connection or a secure TLS connection.

Destinations

A logging destination is a component that specifies where the log messages are sent to. There are different types of destinations available:

• File: Used to send log messages to a local file on the device or to a connected external media device (e.g., USB or SD-Card). When the file destination is specified, a media type and a path relative to that media must be provided.

  Note

  For the internal media, the path is relative to the /log/ folder on the device.

  Warning

  Keep in mind that the internal media for logging, where the /log/ folder is located, is stored on the internal RAM disk. This means that any log messages sent to a file on the internal media will be lost upon reboot. To retain log messages after a reboot, ensure to log them to a file on an external media device, or alternatively forward them to a remote destination.

  The media definitions are the same as those used in other parts of the system. For more information on how to configure media definitions, see the Media Settings part of the Boot Configuration.

  When logging to a file, you can specify a log rotation policy by setting the maximum size of each log file, the number of log files to retain, and the number of compressed log files to retain.

• Remote: Used to send log messages to a remote machine. The following transport protocols are supported: UDP, TCP, and TLS.

  Configuring a remote destination allows the system to send log messages to an external log server, enabling centralized logging and monitoring of multiple systems. Remote destinations are commonly used to forward log messages to a dedicated log server for storage, analysis, and monitoring.

• Console: Used to display log messages directly on the attached console Log messages sent to the console are displayed in real-time, allowing administrators to monitor system activity and diagnose issues directly from the console.

  Warning

  Keep in mind that when sending log messages to the console, it may be more difficult to operate the device using the CLI, as the log messages will be interspersed with the command output. It will not overwrite any written commands, but it will be displayed in between the command output, making it harder to read.

Each individual destination has a buffer that stores log messages until they are sent to the destination. For instance, if the device cannot reach the remote destination, the log messages will be stored in the buffer until the connection is reestablished.

This buffering mechanism applies not only to logging to remote destinations but also to logging to files on the device. However, it is particularly relevant when logging to local files stored on a connected external media device, rather than when logging to files on the internal RAM disk. This is because the IO operation to the external media device might be slower than the rate at which log messages are generated, especially in situations where a larger burst of log messages occurs. In such cases, the buffer stores the log messages until they can be written to the external media device.

Filters

A logging filter is an optional component that can be used to either include or exclude log messages based on specific criteria. Filters are used to define what type of messages are sent to the logging destination. There are a number of different filter types that can be utilized:

• Facility: Filter messages based on the facility of the log message. The facility indicates the type of system component that generated the log message, mentioned in an earlier section.

• Severity: Filter messages based on the severity of the log message. The severity indicates the level of criticality of the log message, mentioned in an earlier section.

• Hostname: Filter messages based on the hostname of the device that generated the log message. This is done by matching on the HOST field in the syslog message.

  Tip

  Supports regular expressions for more advanced matching.

• Message: Filter messages based on the content of the log message.

  Tip

  Supports regular expressions for more advanced matching.

• Program: Filter messages based on the program name that generated the log message. This is done by matching on the PROGRAM field in the syslog message.

  Tip

  Supports regular expressions for more advanced matching.

• Network: Filter messages based on a provided IP subnet. If the sender of the log message is within the specified subnet, it will be a match.

• Rate-limit: Filter messages if they exceed a certain provided rate of log messages per second. This is useful for preventing log flooding attacks.

  It is also possible to perform the rate limit per a specific type of content that is part of the log message:

  • Host: The rate limit is performed per host that is sending log messages.
  • Source IP: The rate limit is performed per source IP address that is sending log messages.
  • Facility: The rate limit is performed per facility that is sending log messages.
  • Severity: The rate limit is performed per severity level that is sending log messages.

Each individual filter can combine multiple of these filter types for the same filter definition. However, if we want to combine multiple filters that, for instance, use the same filter type, we need to create multiple filter definitions and combine them using the and or or operators, when we assign them to a sink.

Sinks

When all the other components have been defined, a sink object can be created. Configuration of a sink is very straightforward, it is simply specifying the source(s) and destination(s) to use, and optionally the filter(s) to use.

However, when specifying multiple filters, their relation to each other must be taken into account. The filters can be combined using the and or or operators. Each subsequent filter will be combined with the previous filter using the specified operator. As an example if we have four filters, filter-1, filter-2, filter-3, and filter-4, and we combine them in the following way:

example:/config/logging/sink-1/#> filter filter-1 and filter-2 or filter-3 and filter-4

This means that the sink will allow messages that match filter-1 and filter-2 or messages that match filter-3 and filter-4.

When the sink has been finalized and its configuration activated, it will start to send log messages from the source(s) to the destination(s) based on the filter(s) specified.

Configuration

The logging in the system can be configured from the top-level configuration context in the CLI:

example:/#> configure
example:/config/#> logging
example:/config/logging/#>

We will separate these sections into the following sub-sections:

• General Logging Configuration
• Source Configuration
• Destination Configuration
• Filter Configuration
• Sink Configuration

General Logging Configuration

The general logging settings are configured directly under the logging context:

example:/config/logging/#>

[no] console

Use to enable or disable logging directly on the console.

Default: Disabled

Example

example:/config/logging/#> console
example:/config/logging/#> no console

no

Disable logging to the console.

[no] external-logging [SIZE [COUNT]]

Enable or disable logging of default log files external media, e.g. USB/SD-Card.

When enabled the same log files that are logged to the local RAM disk will also be logged to the specified external media.

A folder called /log/ will be created on the external media if it does not exist, this is where the log files will be created.

All log files are automatically compressed from generation .1

Note

Sinks can be configured to log to a file on external media, regardless if this setting is enabled or not. This setting only handles logging of the systems default log files to the specified external media.

Default: Disabled

Example

Enable external logging and Keep 10 log files, each 10MiB (uncompressed):

example:/config/logging/#> external-logging 10M 10

no

Disable logging of default log files to usb.

SIZE

Max size of each log file, in uncompressed form. Takes an optional k/M size modifier.

COUNT

Number of log files to keep, in total.

[no] external-logging-media [MEDIA]

Specify the target external media (USB/SD-Card) for the logging.

The selectable medias are based on the configured medias in the boot configuration context. Any media name can be configured, but a warning will be displayed if it is not also configured in the boot configuration.

Tip

Refer to this page for help on how to correctly set up access to external media devices.

Default: external

Example

example:/config/logging/#> external-logging-media my-other-media

no

Reset the option to default, the default external media.

MEDIA

Dynamically created using the media command in the boot configuration context. Use the do show media command in the current context to list all existing media definitions. All usable media definitions will be listed under Active. In addition, two default media definitions exist if no changes have been made to medias in the boot context:W

• internal: The representation of the built-in flash. This cannot be changed or removed.

• external: The default media definition for any connected external media device (e.g. USB, SD-Card). It is configured to always match the first partition on said external media device. This definition is not static or locked, it can be freely adjusted by the user, even removed.

[no] secure-mode

Enable or disable secure mode. This setting determines whether the unit reject or accept any logging messages from remote machines. By default secure mode is enabled, meaning the unit operates in a secure way and do not accept any messages from remote machines.

Default: Enabled

Example

example:/config/logging/#> secure-mode
example:/config/logging/#> no secure-mode

no

Disable secure mode.

Source Configuration

Each source configuration has its sub-context under the logging context:

example:/config/logging/#> source example
example:/config/logging/source-example/#>

[no] name NAME

Change the name of the source. The name is a free form string that identifies the source. The name is used to select the source when configuring a sink.

Note

If the name is changed it will also be changed in all sinks that uses this source, so it is not necessary to update all sinks that uses this source.

Example

example:/config/logging/source-example/#> name my-source

no

Does nothing for this command, the source must have a name.

NAME

The free form name of the source. It can be up to 15 characters long. It allows for the following characters: a-z, A-Z, 0-9, -, and _.

[no] type local|remote

Specify the type of the source.

A source can be either local, i.e the device itself, or some other remote device capable of sending syslog messages.

Note

If the source is remote it is important to also ensure that the ‘secure-mode’ option, under the global logging configuration context, is set to disable. While ‘secure-mode’ is enabled the device will not allow any remote log messages to be received by the device (This option is by default enabled).

Example

example:/config/logging/source-example/#> type local
example:/config/logging/source-example/#> type remote

no

Does nothing for this command, the source must have a type.

local

The source is the device itself.

Note

When this type is selected, additional settings will be available to configure the source. These settings are specific to the local source type. See the Source Local Specific.

remote

The source is a remote device.

Note

When this type is selected, additional settings will be available to configure the source. These settings are specific to the remote source type. See the Source Remote Specific.

Source Local Specific

When the source type is set to local, additional settings are available to configure the source. These settings are specific to the local source type.

example:/config/logging/source-example/#> type local

[no] userspace

Enable or disable local userspace log messages.

When enabled, the source will collect log messages from userspace processes on the local machine. This includes messages from system daemons, user applications, and other non-kernel processes. When disabled, these messages will not be collected.

Default: Enabled

Example

example:/config/logging/source-example/#> userspace
example:/config/logging/source-example/#> no userspace

no

Disable logging of userspace log messages.

[no] kernel

Enable or disable local kernel log messages.

When enabled, the source will collect log messages from the local machine’s kernel. This includes messages related to the operation of the kernel, hardware drivers, and system services. When disabled, these messages will not be collected.

Default: Enabled

Example

example:/config/logging/source-example/#> kernel
example:/config/logging/source-example/#> no kernel

no

Disable logging of kernel log messages.

Source Remote Specific

When the source type is set to remote, additional settings are available to configure the source. These settings are specific to the remote source type.

example:/config/logging/source-example/#> type remote

[no] format rfc3164|rfc5424

Set the syslog formatting to expect from remote clients.

Default: rfc5424

Example

example:/config/logging/source-example/#> format rfc3164
example:/config/logging/source-example/#> format rfc5424

no

Does nothing for this command, the source must have a format.

rfc3164

Use the RFC 3164 syslog format. This the traditional syslog format that includes a timestamp, hostname, process name, process ID, and the message.

Example of a message in RFC 3164 format:

Nov 18 09:36:42 hostname proc[123] message

rfc5424

Use the RFC 5424 syslog format. This is a newer syslog format that includes structured data and additional fields.

Example of a message in RFC 5424 format:

1 2019-11-18T09:36:42.000321+01:00 hostname proc 123 - - message

[no] transport udp|tcp|tls

Specify the transport protocol to be used for the source.

This option allows for specification of the transport protocol to be used for the source. Any client that wants to send messages to the device must use the same transport protocol.

Default: TLS

Example

example:/config/logging/source-example/#> transport udp
example:/config/logging/source-example/#> transport tcp
example:/config/logging/source-example/#> transport tls

no

Does nothing for this command, the source must have a transport.

udp

Use the User Datagram Protocol. This is a connectionless protocol that does not guarantee delivery of packets.

tcp

Use the Transmission Control Protocol. This is a connection oriented protocol that guarantees delivery of packets.

tls

Use the Transport Layer Security protocol. This is a secure protocol that provides encryption and authentication.

Note

When this type is selected, additional settings will be available to configure the source. These settings are specific to the TLS transport protocol. See the Source Remote TLS Specific.

[no] ip-protocol ipv4|ipv6

Specify the IP protocol to be used for the source.

This option allows for specification of the IP protocol to be used for the source. Any client that wants to send messages to the device must use the same IP protocol.

Default: IPv4

Example

example:/config/logging/source-example/#> ip-protocol ipv4
example:/config/logging/source-example/#> ip-protocol ipv6

no

Does nothing for this command, the source must have an IP protocol.

ipv4

Expect messages to be sent using the IPv4 protocol.

ipv6

Expect messages to be sent using the IPv6 protocol.

[no] listen [IFNAME]

Specify a specific interface, with static address, to listen on.

This option allows for providing a specific IP address to listen on. By default every available interface will be listened on, i.e. we bind to the address 0.0.0.0.

If a specific interface should be listened on, provide the interface name as the argument to this option.

Note

The interface must have a static IP address configured, otherwise the device will not be able to bind to the address. If the interface has more than one address, only the first address will be used.

Tip

If you want to receive only messages from a specific remote host, based on its IP address, configure a filter for to handle that instead.

Default: Listen on all available interfaces.

Example

example:/config/logging/source-example/#> listen vlan1
example:/config/logging/source-example/#> no listen

no

Listen on all available interfaces.

IFNAME

The name of the interface to listen on. Only one specific interface can be provided.

[no] port [PORT]

Specify another port to use, other than the default.

This configuration option allows for specification of a non-default source port for the remotely received messages.

Default: Depends on the transport protocol. UDP: 514, TCP: 601, TLS: 6514,

Example

example:/config/logging/source-example/#> port 5514

no

Reset the port to the default value.

PORT

The port number to use for the source. The port number must be in the range 1-65535.

[no] keep-hostname

Enable or disable hostname rewriting.

If this setting is enabled, the hostname specified in the HOST field of the incoming log messages for the source will be preserved.

For instance, this can be useful if the original sender’s hostname should be preserved when acting as a syslog relay.

If disabled, the HOST field of the message will be rewritten to indicate that it was sent from this device, if the log source is used when sending to another remote destination.

Note

If the received log message contains no hostname, a hostname will be added to the message. For a message that has been received from a remote source, the hostname will be the address of the sender.

Default: Disabled

Example

example:/config/logging/source-example/#> keep-hostname
example:/config/logging/source-example/#> no keep-hostname

no

Disable hostname rewriting.

[no] use-dns [local-only]

Enable or disable DNS usage for hostname resolving.

Handling of syslog messages will block on DNS queries. Therefore, if this setting is enabled, a DoS scenario could potentially occur. To prevent this, or reduce the risk, ensure that relevant firewall rules are configured. Furthermore, it’s important to ensure that any host that may send messages and can reach this source is resolvable.

If the local-only option is specified, hostname resolution attempts will be performed locally only for statically configured hosts. These can be configured under the ‘dns’ context using the ‘host’ command.

Note

This setting has no effect if the keep-hostname setting is enabled, and an incoming message contains a hostname in its HOST field.

Default: Enabled

Example

example:/config/logging/source-example/#> use-dns
example:/config/logging/source-example/#> use-dns local-only
example:/config/logging/source-example/#> no use-dns

no

Disable DNS usage for hostname resolving.

local-only

Only use locally configured DNS entries for hostname resolving.

See the DNS Configuration section for more information on how to configure DNS entries.

Source Remote TLS Specific

When the source type is set to remote and the transport protocol is set to tls, additional settings are available to configure the source. These settings are specific to the remote source type and the TLS transport protocol.

example:/config/logging/source-example/#> type remote
example:/config/logging/source-example/#> transport tls

[no] peer-verify [untrusted|trusted]

Select the verification method to be used during TLS handshake.

The peer-verify option can be used to specify the level of verification that should be performed during the TLS handshake.

The value is a combination of two properties:

• First we specify whether the peer is required to provide a certificate or if it is optional:

  • Required: When peer-verify is specified.
  • Optional: When no peer-verify is specified.

• Second we specify whether the certificate provided needs to be valid (Trusted) or not (Untrusted):

  • Trusted: When the trusted option is specified.
  • Untrusted: When untrusted option is specified.

Based on the combination of these two properties, the following combinations are possible:

• Optional Untrusted: The peer is not required to provide a certificate, but if it does, it does not need to be verified.

• Optional Trusted: The peer is not required to provide a certificate, but if it does, it needs to be verified.

• Required Untrusted: The peer is required to provide a certificate, but it does not need to be verified.

• Required Trusted: The peer is required to provide a certificate, and it needs to be verified.

For all the scenarios where Trusted is specified, a CA certificate needs to be provided as well, in order to verify the certificate provided by the peer.

Note

If only peer-verify is specified, it defaults to using trusted.

If only no peer-verify is specified, it defaults to using untrusted.

These two commands are just shorthand commands for the most strict and least strict verification methods.

Default: Required Trusted, i.e. peer-verify trusted.

Example

example:/config/logging/source-example/#> peer-verify untrusted
example:/config/logging/source-example/#> peer-verify trusted
example:/config/logging/source-example/#> peer-verify
example:/config/logging/source-example/#> no peer-verify untrusted
example:/config/logging/source-example/#> no peer-verify trusted
example:/config/logging/source-example/#> no peer-verify

no

Make the peer verification optional during the TLS handshake, i.e. the peer is not required to provide a certificate.

untrusted

If a certificate is provided, it does not need to be verified.

trusted

If a certificate is provided, it needs to be verified.

[no] certificate [NAME]

Specify the Certificate to use.

The selected certificate will be used for authenticating the source against any client that connects to it.

Note

The certificate must be imported into the system before it can be used. For more information on how to import certificates, see the Certificate Management section.

Default: None

Example

example:/config/logging/source-example/#> certificate my-cert

no

Remove the certificate from the source.

NAME

The name of the certificate to use.

[no] ca-certificate [NAME]

Specify the CA Certificate to use.

The selected CA certificate will be used for verifying any certificate that is provided by clients that connect to the source.

Note

The CA certificate must be imported into the system before it can be used. For more information on how to import certificates, see the Certificate Management section.

Note

If the peer-verify option is set to trusted, a CA certificate must be provided.

Default: None

Example

example:/config/logging/source-example/#> ca-certificate my-ca-cert

no

Remove the CA certificate from the source.

NAME

The name of the CA certificate to use.

Destination Configuration

Each destination configuration has its sub-context under the logging context:

example:/config/logging/#> destination example
example:/config/logging/destination-example/#>

[no] name NAME

Change the name of the destination. The name is a free form string that identifies the destination. The name is used to select the destination when configuring a sink.

Note

If the name is changed it will also be changed in all sinks that uses this destination, so it is not necessary to update all sinks that uses this destination.

Example

example:/config/logging/destination-example/#> name my-destination

no

Does nothing for this command, the destination must have a name.

NAME

The free form name of the destination. It can be up to 15 characters long. It allows for the following characters: a-z, A-Z, 0-9, -, and _.

[no] type file|remote|console

Specify the type of the destination.

A destination can be either a file, a remote server, or the console.

Example

example:/config/logging/destination-example/#> type file
example:/config/logging/destination-example/#> type remote
example:/config/logging/destination-example/#> type console

no

Does nothing for this command, the destination must have a type.

file

The destination is a file on the device or external media.

Note

When this type is selected, additional settings will be available to configure the destination. These settings are specific to the file destination type. See the Destination File Specific.

remote

The destination is a remote server.

Note

When this type is selected, additional settings will be available to configure the destination. These settings are specific to the remote destination type. See the Destination Remote Specific.

console

The destination is the console.

Note

When this type is selected, no additional settings are available to configure the destination.

Warning

Keep in mind that when sending log messages to the console, it may be more difficult to operate the device using the CLI, as the log messages will be interspersed with the command output. It will not overwrite any written commands, but it will be displayed in between the command output, making it harder to read.

Destination File Specific

When the destination type is set to file, additional settings are available to configure the destination. These settings are specific to the file destination type.

example:/config/logging/destination-example/#> type file

[no] media [internal|MEDIA]

Specifies the target media where the log file will be stored.

The file name/path, set with the file-name command, will be relative to the root of the specified media.

Tip

Refer to this page for help on how to correctly set up access to external media devices.

Tip

Tab completion is available for the MEDIA argument, to list all existing media definitions.

Default: None

Example

example:/config/logging/destination-example/#> media internal
example:/config/logging/destination-example/#> media external
example:/config/logging/destination-example/#> media my-other-media

no

Removes the configured media from the destination. However, if another media is not specified, the destination configuration will be invalid.

internal

Sets the destination to the internal memory of the device. This is a special media definition that will always exist. When used in the context of a logging media, it refers to the /log/ directory on the internal RAM disk. Therefore, specified file-name will be relative to this directory.

Warning

As mentioned above, the internal log directory is located on the internal RAM disk. This means that the log files will be lost upon reboot or power loss, because the RAM disk is not persistent.

MEDIA

Specifies the name of the external media to use. Any log file, set with the file-name command, will be relative to the root of the specified media, e.g. /media/external/.

The media must be defined in the boot configuration context, see Boot Configuration for more information. The reason for this is to give the user full control over which media devices should be made available on the system in general.

Note

By default, the media definition external is available for use. This definition is configured to always match the first partition on any connected external media device (e.g. USB, SD-Card).

This definition is not static or locked, it can be freely adjusted by the user, even removed.

Tip

Use the do show media command in the current context to list all existing media definitions. All usable media definitions will be listed under Active.

[no] file-name [PATH]

Specify the name or the path of the log file to be used.

The provided PATH will be relative to the root of the specified media, set with the media command.

Warning

If a path is specified, ensure that all directories in the path exist. Failure to do so will result in the log file not being created.

Default: None

Example

example:/config/logging/destination-example/#> file-name my-log-file.log
example:/config/logging/destination-example/#> file-name /my-folder/my-log-file.log

no

Removes the configured file name from the destination. However, if another file name is not specified, the destination configuration will be invalid.

PATH

The name or path of the log file to use. The file name/path can be up to 127 characters long.

The file name part of the PATH can include any character, except for the null character \0 and the slash /. The slash is used as a directory separator. In addition, the file name should not include special characters such as ?, *, |, <, >, &, ;, (, ), or newline.

The path can include multiple directories, which are separated by slashes /. Each directory in the path must already exist; otherwise, the log file will not be created. The path is relative to the root of the specified media, set with the media command.

[no] rotate [0-100]

Specify the maximum number of log files to keep.

When the file is rotated, a new log file will be created with the same name, but with a sequence number appended to it. The sequence number will start at 0 and increase for each new log file created. The oldest log file will have the highest sequence number. As an example, if we allow for 5 rotated log files, the files will be named as follows:

my-log-file.log           – The current log file
my-log-file.log.0         – The fifth rotated log file
my-log-file.log.1         – The fourth rotated log file
my-log-file.log.2         – The third rotated log file
my-log-file.log.3         – The second rotated log file
my-log-file.log.4         – The first rotated log file

When the maximum number of log files is reached, the oldest log file will be deleted to make room for the new log file. If compress is enabled, the oldest compressed log file will be deleted instead and the oldest log file will be compressed.

Each file is rotated when it reaches a certain size, specified with the size command.

Warning

If log file rotation is disabled, the log file will grow indefinitely. This can lead to the log file consuming all available space on the media. Therefore, if it is disabled, ensure that the log file does not grow too large.

Default: 1 file.

Example

example:/config/logging/destination-example/#> rotate 5
example:/config/logging/destination-example/#> no rotate

no

Use to disable log file rotation.

0-100

The maximum number of log files to keep. The value must be in the range 0-100.

Setting the rotate value to 0 will disable log file rotation. This is the same as using the no rotate command.

[no] size 1-1000[k|K|M|G|KB|MB|GB]

Specify the size that triggers log file rotation when reached.

When the log file reaches the specified size, it will be rotated. The number of rotations is specified with the rotate command.

Default: 100KB

Example

example:/config/logging/destination-example/#> size 100KB
example:/config/logging/destination-example/#> size 10MB
example:/config/logging/destination-example/#> size 1GB

no

This option has no effect for this command. If rotate is enabled, the size must be set. If rotate is disabled, the specified size will not be used.

1-1000[k|K|M|G|KB|MB|GB]

Specifies the size in bytes, which must be in the range of 1-1000. The size is specified with a size modifier, such as KB, MB, or GB, to indicate kilobytes, megabytes, or gigabytes, which results in the following sizes:

• KB or k: Kilobytes (1024 bytes).
• MB or M: Megabytes (1,048,576 bytes).
• GB or G: Gigabytes (1,073,741,824 bytes).

[no] compress [0-100]

Specify the maximum number of compressed log files to keep.

When the number of rotated log files reaches the maximum number of rotations, as specified with the rotate command, the oldest log file will be compressed, if this option is enabled. This command specifies the maximum number of such compressed log files to keep. When the maximum number of compressed log files is reached, the oldest compressed log file will be deleted to make room for the new compressed log file.

The compressed log file will have the same name as the original log file, with the sequence number appended to it, starting from the sequence number of the last rotated log file. In addition, the compressed log file will have the .gz extension. The highest sequence number will be the oldest.

As an example, if we allow for 3 rotated files and 3 compressed files, the files will be named as follows:

my-log-file.log           – The current log file
my-log-file.log.0         – The third rotated log file
my-log-file.log.1         – The second rotated log file
my-log-file.log.2         – The first rotated log file
my-log-file.log.3.gz      – The third compressed log file
my-log-file.log.4.gz      – The second compressed log file
my-log-file.log.5.gz      – The first compressed log file

Default: 2 compressed files.

Example

example:/config/logging/destination-example/#> compress 3
example:/config/logging/destination-example/#> no compress

no

Disables log file compression.

0-100

The maximum number of compressed log files to keep. The value must be in the range 0-100. If the value is set to 0, log file compression will be disabled, which is the same as using the no compress command.

Destination Remote Specific

When the destination type is set to remote, additional settings are available to configure the destination. These settings are specific to the remote destination type.

example:/config/logging/destination-example/#> type remote

[no] format bsd|rfc3164|rfc5424

Set the syslog formatting to use when sending messages to the remote server.

Default: rfc5424

Example

example:/config/logging/destination-example/#> format bsd
example:/config/logging/destination-example/#> format rfc3164
example:/config/logging/destination-example/#> format rfc5424

no

Does nothing for this command, the destination must have a format.

bsd

Use the legacy BSD format. This simple format includes a the process name, process ID, and the message.

Example of a message in BSD format:

proc[123]: message.

rfc3164

Use the RFC 3164 syslog format. This the traditional syslog format that includes a timestamp, hostname, process name, process ID, and the message.

Example of a message in RFC 3164 format:

Nov 18 09:36:42 hostname proc[123] message

rfc5424

Use the RFC 5424 syslog format. This is the newest syslog format that includes structured data and additional fields.

Example of a message in RFC 5424 format:

1 2019-11-18T09:36:42.000321+01:00 hostname proc 123 - - message

[no] transport [udp|tcp|tls]

Specify the transport protocol to be used for the destination.

This option allows for specification of the transport protocol to be used for the destination. Any server that wants to receive messages from the device must be configured to use the same transport protocol.

Default: TLS

Example

example:/config/logging/destination-example/#> transport udp
example:/config/logging/destination-example/#> transport tcp
example:/config/logging/destination-example/#> transport tls

no

Does nothing for this command, the destination must have a transport.

udp

Use the User Datagram Protocol. This is a connectionless protocol that does not guarantee delivery of packets.

tcp

Use the Transmission Control Protocol. This is a connection oriented protocol that guarantees delivery of packets.

tls

Use the Transport Layer Security protocol. This is a secure protocol that provides encryption and authentication.

Note

When this type is selected, additional settings will be available to configure the destination. These settings are specific to the TLS transport protocol. See the Destination Remote TLS Specific.

[no] ip-protocol ipv4|ipv6

Specify the IP protocol to be used for the destination.

This option allows for specification of the IP protocol to be used for the destination. Any server that wants to receive messages from the device must use the same IP protocol.

Default: IPv4

Example

example:/config/logging/destination-example/#> ip-protocol ipv4
example:/config/logging/destination-example/#> ip-protocol ipv6

no

Does nothing for this command, the destination must have an IP protocol.

ipv4

Transmit messages using the IPv4 protocol.

ipv6

Transmit messages using the IPv6 protocol.

[no] port [PORT]

Specify a port to use, different from the default one.

This configuration option allows you to specify a non-default destination port for messages sent remotely.

Default: Depends on the transport protocol. UDP: 514, TCP: 601, TLS: 6514,

Example

example:/config/logging/destination-example/#> port 5514

no

This option resets the port to its default value based on the transport protocol.

PORT

Specifies the port number to use for the destination. The port number must be within the range of 1-65535.

[no] host [ [address IPADDR] | [name HOSTNAME|FQDN] | [dhcp IFNAME] ]

Defines the location of the host for the remote destination.

The host location can be specified in one of the following ways:

• By providing an IPv4 or IPv6 address using the address keyword followed by the IPADDR. The expected address type is dependent on the IP protocol set for the destination, see the ip-protocol command.

• By providing a hostname or a Fully Qualified Domain Name (FQDN) using the name keyword followed by the HOSTNAME or FQDN.

• By obtaining the destination address over DHCP using the dhcp keyword followed by the IFNAME. If a lease received on the specified interface contains option 7, it will be used as the destination address.

Default: None

Example

example:/config/logging/destination-example/#> host address 192.168.1.1
example:/config/logging/destination-example/#> host address 2001:db8::1
example:/config/logging/destination-example/#> host name example.com
example:/config/logging/destination-example/#> host name mydevice
example:/config/logging/destination-example/#> host dhcp vlan1

no

Removes any configured host from the destination. However, if another host is not specified, the destination configuration will be invalid.

address IPADDR

Specifies the IPv4 or IPv6 address of the host.

name HOSTNAME|FQDN

Specifies the hostname or FQDN of the host.

dhcp IFNAME

Specifies the interface name to obtain the destination address over DHCP. If a lease received on the specified interface contains option 7, it will be used as the destination address.

Note

It’s crucial to ensure that the specified interface has DHCP enabled and can successfully receive a lease from a DHCP server.

For detailed instructions on how to configure DHCP on an interface, please refer to the Interface Configuration section.

Note

Each destination instance can apply up to two IP addresses, provided by option 7 in the DHCP lease.

[no] throttle [VALUE]

Specify a throttle value to rate limit the number of messages sent per second

By setting a throttle value, you can limit the number of messages sent per second to the configured destination. This is particularly useful when the destination has a maximum message handling capacity.

Note

It’s important to understand how messages are managed when the transmission rate is exceeded.

If the rate of incoming messages surpasses the configured limit, the system doesn’t instantly discard the excess messages. Instead, these messages are buffered and transmitted as soon as the rate limit allows.

However, bear in mind that the buffer has a limited capacity. If the buffer reaches its maximum capacity due to a continuous influx of messages exceeding the rate limit, any incoming messages will be discarded until there is available space in the buffer.

Tip

If you prefer to drop messages when the rate limit is exceeded, you can use a filter of type rate-limit. This filter will instantly discard any messages that surpass the specified rate limit.

For more information on how to configure a rate-limit filter, see the Filter Configuration section.

Default: no throttle, i.e. no rate limiting.

Example

example:/config/logging/destination-example/#> throttle 100

no

This option disables throttling, allowing messages to be sent at the maximum possible rate.

VALUE

This option allows you to specify the maximum number of messages that can be sent per second to the destination. The value must be a non-negative integer.

Destination Remote TLS Specific

When the destination type is set to remote and the transport protocol is set to tls, additional settings are available to configure the destination. These settings are specific to the remote destination type and the TLS transport protocol.

example:/config/logging/destination-example/#> type remote
example:/config/logging/destination-example/#> transport tls

[no] peer-verify [untrusted|trusted]

Select the verification method to be used during TLS handshake.

The peer-verify option can be used to specify the level of verification that should be performed during the TLS handshake.

The value is a combination of two properties:

• First we specify whether the peer is required to provide a certificate or if it is optional:

  • Required: When peer-verify is specified.
  • Optional: When no peer-verify is specified.

• Second we specify whether the certificate provided needs to be valid (Trusted) or not (Untrusted):

  • Trusted: When the trusted option is specified.
  • Untrusted: When untrusted option is specified.

Based on the combination of these two properties, the following combinations are possible:

• Optional Untrusted: The peer is not required to provide a certificate, but if it does, it does not need to be verified.

• Optional Trusted: The peer is not required to provide a certificate, but if it does, it needs to be verified.

• Required Untrusted: The peer is required to provide a certificate, but it does not need to be verified.

• Required Trusted: The peer is required to provide a certificate, and it needs to be verified.

For all the scenarios where Trusted is specified, a CA certificate needs to be provided as well, in order to verify the certificate provided by the peer.

Note

If only peer-verify is specified, it defaults to using trusted.

If only no peer-verify is specified, it defaults to using untrusted.

These two commands are just shorthand commands for the most strict and least strict verification methods.

Default: Required Trusted, i.e. peer-verify trusted.

Example

example:/config/logging/destination-example/#> peer-verify untrusted
example:/config/logging/destination-example/#> peer-verify trusted
example:/config/logging/destination-example/#> peer-verify
example:/config/logging/destination-example/#> no peer-verify untrusted
example:/config/logging/destination-example/#> no peer-verify trusted
example:/config/logging/destination-example/#> no peer-verify

no

Make the peer verification optional during the TLS handshake, i.e. the peer is not required to provide a certificate.

untrusted

If a certificate is provided, it does not need to be verified.

trusted

If a certificate is provided, it needs to be verified.

[no] certificate [NAME]

Specify the Certificate to use.

The selected certificate will be used for authenticating the destination against the remote server that it connects to.

Note

The certificate must be imported into the system before it can be used. For more information on how to import certificates, see the Certificate Management section.

Default: None

Example

example:/config/logging/destination-example/#> certificate my-cert

no

Remove the certificate from the destination.

NAME

The name of the certificate to use.

[no] ca-certificate [NAME]

Specify the CA Certificate to use.

The selected CA certificate will be used for verifying the certificate that is provided by the remote server that the destination connects to.

Note

The CA certificate must be imported into the system before it can be used. For more information on how to import certificates, see the Certificate Management section.

Note

If the peer-verify option is set to trusted, a CA certificate must be provided.

Default: None

Example

example:/config/logging/destination-example/#> ca-certificate my-ca-cert

no

Remove the CA certificate from the destination.

NAME

The name of the CA certificate to use.

Filter Configuration

Each filter configuration has its sub-context under the logging context:

example:/config/logging/#> filter example
example:/config/logging/filter-example/#>

[no] name NAME

Change the name of the filter. The name is a free form string that identifies the filter. The name is used to select the filter when configuring a sink.

Note

If the name is changed it will also be changed in all sinks that uses this filter, so it is not necessary to update all sinks that uses this filter.

Example

example:/config/logging/filter-example/#> name my-filter

no

Does nothing for this command, the filter must have a name.

NAME

The free form name of the filter. It can be up to 15 characters long. It allows for the following characters: a-z, A-Z, 0-9, -, and _.

[no] invert

Enable if the entire filter logic should be inverted.

Normally the configured filter will match messages that conform directly to the specified filter, e.g. if we filter on facility auth any message not matching that facility will be filtered out. However, if we would enable invert, any message matching the filter would be filtered out instead.

For instance, by inverting filters we can more easily filter out messages when we may want to include more messages than we exclude.

Default: Disabled, i.e. no invert.

Example

example:/config/logging/filter-example/#> invert

no

Disables the invert option.

[no] facility FACILITY[ FACILITY ...|,FACILITY ...]

Filter messages based on their facility.

By specifying one or more facilities, only messages that match the specified facilities will be allowed through the filter.

Default: None

Example

example:/config/logging/filter-example/#> facility auth
example:/config/logging/filter-example/#> facility auth authpriv
example:/config/logging/filter-example/#> facility auth,authpriv

Tip

Both comma and space can be used as separators between facilities.

Individual facilities can be added or removed to the active list, i.e. each call to the command does not replace the existing list of facilities.

example:/config/logging/filter-example/#> facility auth
example:/config/logging/filter-example/#> facility authpriv
example:/config/logging/filter-example/#> facility security
example:/config/logging/filter-example/#> show facility
auth,authpriv,security
example:/config/logging/filter-example/#> no facility auth
example:/config/logging/filter-example/#> show facility
authpriv,security

In order to remove all of the configured facilities, use the no facility, with no specified facilities.

example:/config/logging/filter-example/#> no facility

no

Removes all configured facilities from the filter.

FACILITY[,FACILITY ...]

The facility or facilities to filter on. Refer to the Facility section for a list of available facilities.

Tip

Tab completion is available for the FACILITY argument, to list all existing facilities.

[no] level LEVEL[ LEVEL ...|,LEVEL, ...|..LEVEL|..]

Filter messages based on the severity level of the message.

By specifying one or more severity levels, only messages that match any of the specified severity levels will be allowed through the filter.

Default: None

Example

example:/config/logging/filter-example/#> level warning
example:/config/logging/filter-example/#> level warning error
example:/config/logging/filter-example/#> level warning,error

Tip

Both comma and space can be used as separators between severities.

Also levels can be specified as ranges, e.g. info..warning will match all severity levels from info to warning.

example:/config/logging/filter-example/#> level info..warning

Further, all levels from a certain level and up can be specified, e.g. notice.. will match all severity levels from notice and up.

example:/config/logging/filter-example/#> level notice..

Individual severity levels can be added or removed to the active list, i.e. each call to the command does not replace the existing list of severity levels.

example:/config/logging/filter-example/#> level warning
example:/config/logging/filter-example/#> level error
example:/config/logging/filter-example/#> level crit
example:/config/logging/filter-example/#> show level
warning,error,crit
example:/config/logging/filter-example/#> no level warning
example:/config/logging/filter-example/#> show level
error,crit

In order to remove all of the configured severity levels, use the no level, with no specified severities.

example:/config/logging/filter-example/#> no level

no

Removes all configured severity levels from the filter.

LEVEL

The level of the severity or severities to filter on. Refer to the Severity section for a list of available severities.

Tip

Tab completion is available for the LEVEL argument, to list all existing severities.

[no] hostname "NAME"

Filter messages based on the hostname field of the message.

It is important to note that this filter will only be performed on the actual hostname field of the the specific log message. This means that this filter will not match on the IP address of a given host, even if the IP address and the host field refers to the same actual host.

Note

Make sure to use double quotes around the hostname to match, e.g. "my-example-host".

Tip

Supports the use of regular expressions.

Tip

For filtering based on the IP address use the ‘network’ filter instead.

Default: None

Example

Match on a specific hostname:

example:/config/logging/filter-example/#> hostname “my-example-host”

Use regular expressions to match on multiple hostnames, e.g. all hosts starting with my-example-host followed by a digit:

example:/config/logging/filter-example/#> hostname “my-example-host[0-9]”

no

Removes the hostname filter from the filter.

"NAME"

The name of the hostname to filter on, or a regular expression to match on.

[no] message "MESSAGE"

Filter messages based on the text content of the message.

This filter will match on the actual text content of the message, and will only allow messages through that matches the specified text.

Note

This filtering will only be performed on the text content of the message and not on the message headers.

Note

Make sure to use double quotes around the message to match, e.g. "my example message".

Tip

Supports the use of regular expressions.

Default: None

Example

Match on a specific message:

example:/config/logging/filter-example/#> message “my example message”

Use regular expressions to match on specific patterns in the message content. For example, to filter all messages containing the word “error” (in any case):

example:/config/logging/filter-example/#> message “^.*[Ee]rror.*$”

In this example, the regular expression “^.[Ee]rror.$” is used. Here’s what each part of the expression means:

• ^ : This symbol represents the start of a line.
• .* : This matches any character (except for a newline) 0 or more times.
• [Ee]rror : This matches the word “error” in any case (i.e., “Error” or “error”).
• .* : This again matches any character (except for a newline) 0 or more times.
• $ : This symbol represents the end of a line.

So, this regular expression will match any line that contains the word “error” in any case, regardless of what comes before or after “error” in the line.

no

Removes the message filter from the filter.

"MESSAGE"

The message content to filter on, or a regular expression to match on.

[no] program "NAME"

Filter messages based on the name of the program that generated it.

This will filter the messages against the program field for the log messages. It will match on the application name that generated the message, not the process ID or any other field.

Note

Make sure to use double quotes around the message to match, e.g. "my example message".

Tip

Supports the use of regular expressions.

Default: None

Example

Use the program command to match on a specific program name:

example:/config/logging/filter-example/#> program “my-example-program”

In this example, the program command is used to filter log messages from a specific program named “my-example-program”.

You can also use regular expressions to match on specific patterns in the program name:

example:/config/logging/filter-example/#> program “^udhcpc\s*:vlan\d$”

In this second example, the regular expression “^udhcpc\s*:vlan\d$” is used. Here’s what each part of the expression means:

• ^ : This symbol represents the start of a line.
• udhcpc : This matches the exact string “udhcpc”.
• \s* : This matches any whitespace character 0 or more times.
• :vlan : This matches the exact string “:vlan”.
• \d : This matches any digit.
• $ : This symbol represents the end of a line.

So, this regular expression will match any line that starts with “udhcpc”, followed by any number of whitespace characters, followed by “:vlan”, and ends with a digit.

no

Removes the program filter from the filter.

"NAME"

The name of the program to filter on, or a regular expression to match on.

[no] network ADDR/LEN

Filter messages based on the provided IP subnet.

If the IP address of a sender belongs to the subnet provided the message will be considered a match. Hence, it is possible to match on specific addresses (using a /32 length) or a range of addresses.

Note

The filter will match against the address of the last-hop sender of the message, i.e. if the message have been relayed it will be the IP address of the relay and not the original sender of the message.

Default: None

Example

Filter log messages originating from any IP address within the 192.168.1.0/24 network:

example:/config/logging/filter-example/#> network 192.168.1.0/24

Filter log messages originating from a specific IP address, 192.168.2.2. The /32 subnet mask indicates a single IP address.

example:/config/logging/filter-example/#> network 192.168.2.2/32

no

Removes the network filter from the filter.

ADDR/LEN

The IP address and subnet length to filter on. The subnet length specifies the number of bits in the subnet mask. The subnet length must be in the range of 1-32.

[no] rate-limit [per host|source-ip|facility|level] RATE

Filter out messages if they exceed the provided message rate.

When this configuration option is used messages will be filtered out, i.e. dropped, if the messages per second exceed the set rate value.

It is also possible to optionally perform the rate limit per a specific type of content that is part of the message. The following options can be selected from, but only one at a time per filter:

• host: The host specified in the message.
• source-ip: The source IP address of the sender, if the message has been relayed this is the address of the relay.
• facility: The facility of the message.
• level: The severity level of the message.

If the rate-limit is configured for a specific type it means that the imposed rate is applied for each individual type when a message is handled. As an example, if we have configured a rate-limit of 100 per host, and we have two hosts transmitting messages, a total of 200 messages will be allowed, 100 for each of the transmitting hosts.

If no specific type is provided the rate will be applied for every message, regardless of their content.

Note

The rate provided will always be in number of messages per second.

Default: No rate limiting, i.e. no rate-limit.

Example

Filter out messages if they exceed 100 messages per second:

example:/config/logging/filter-example/#> rate-limit 100

Filter out messages if they exceed 100 messages per second per host:

example:/config/logging/filter-example/#> rate-limit per host 100

no

Disables the rate limiting.

per host

Perform the rate limiting per host.

source-ip

Perform the rate limiting per source IP address.

facility

Perform the rate limiting per facility.

level

Perform the rate limiting per severity level.

RATE

The maximum number of messages that can be sent per second. The value must be a non-negative integer.

Sink Configuration

Each sink configuration has its sub-context under the logging context:

example:/config/logging/#> sink example
example:/config/logging/sink-example/#>

[no] name NAME

Change the name of the sink. The name is a free form string that identifies the sink.

Example

example:/config/logging/sink-example/#> name my-sink

no

Does nothing for this command, the sink must have a name.

NAME

The free form name of the sink. It can be up to 15 characters long. It allows for the following characters: a-z, A-Z, 0-9, -, and _.

[no] source SOURCE[ SOURCE ...|,SOURCE ...]

Define the source(s) from which the log messages should be sent.

By specifying one or more sources, you direct the log messages from the designated sources to the sink.

Note

For the sink to be valid, at least one source must be specified.

Default: None

Example

example:/config/logging/sink-example/#> source example-1

To specify multiple sources simultaneously:

example:/config/logging/sink-example/#> source example-1 example-2
example:/config/logging/sink-example/#> source example-1,example-2

no

This command removes all configured sources from the sink.

SOURCE

This argument represents the name of the source to be associated with the sink. For more information on configuring sources, refer to the Source Configuration section.

Tip

Tab completion is available for the SOURCE argument, providing a list of all existing sources.

[no] destination DESTINATION[ DESTINATION ...|,DESTINATION ...]

Define the destination(s) to which the log messages should be sent.

By specifying one or more destinations, you direct the log messages to the designated destinations.

Note

For the sink to be valid, at least one destination must be specified.

Default: None

Example

example:/config/logging/sink-example/#> destination example-1

To specify multiple destinations simultaneously:

example:/config/logging/sink-example/#> destination example-1 example-2
example:/config/logging/sink-example/#> destination example-1,example-2

no

This command removes all configured destinations from the sink.

DESTINATION

This argument represents the name of the destination to be associated with the sink. For more information on configuring destinations, refer to the Destination Configuration section.

Tip

Tab completion is available for the DESTINATION argument, providing a list of all existing destinations.

[no] filter [and|or] FILTER [ [and|or] FILTER ...]

Define optional filter(s) to include or exclude specific log messages.

By default, filters are combined using the AND operator. However, you can also use the OR operator to combine filters. The operator should be specified before the filter.

The order of the filters and the combination operator are crucial. The AND operator takes precedence over the OR operator.

Note

When using multiple filters, the AND operator evaluates first, followed by the OR operator. This order of operations can affect the outcome of the filter combination.

Default: None

Example

Specify a single filter:

example:/config/logging/sink-example/#> filter filter-1

Specify multiple filters using the and operator:

example:/config/logging/sink-example/#> filter filter-1 and filter-2

If you list multiple filters without specifying an operator, the and operator is assumed. Therefore, the following command is equivalent to the previous command:

example:/config/logging/sink-example/#> filter filter-1 filter-2

Specify multiple filters using the or operator:

example:/config/logging/sink-example/#> filter filter-1 or filter-2

Example: Advanced Filter Combination

Combine filters using both and and or operators. Remember, the and operator takes precedence over the or operator:

example:/config/logging/sink-example/#> filter filter-1 and filter-2 or filter-3 and filter-4

This command works as follows:

• filter-1 and filter-2: This part of the command will match log messages that meet both the conditions of filter-1 and filter-2.

• or: This operator combines the results of the two surrounding expressions.

• filter-3 and filter-4: This part of the command will match log messages that meet both the conditions of filter-3 and filter-4.

So, the entire command will match log messages that either meet both the conditions of filter-1 and filter-2, or meet both the conditions of filter-3 and filter-4.

Remember, the and operator takes precedence over the or operator. So, the and operations are evaluated first, followed by the or operation.

no

This command removes all configured filters from the sink.

and

This operator is used to combine multiple filters. When the and operator is used, a log message must meet all the specified filter conditions to be matched.

Note

This is the default operator when combining multiple filters, when no operator is specified.

or

This operator is also used to combine multiple filters. However, when the or operator is used, a log message can meet any one of the specified filter conditions to be matched.

FILTER

This argument represents the name of the filter to be associated with the sink. For more information on configuring filters, refer to the Filter Configuration section.

Tip

Tab completion is available for the FILTER argument, providing a list of all existing filters.

Status

In the exec context, it is possible to view the current status of the logging setup. We can use the show logging command to obtain a summary of the current setup:

example:/#> show logging
╒ Source Summary ══════════════════════════════════════════════════════════════╕
│SOURCE           PROCESSED                                                   │
│local-userspace  329                                                          │
│sink-remote      879                                                          │
│local-kernel     1                                                            │
└──────────────────────────────────────────────────────────────────────────────┘

╒ Destination Summary ═════════════════════════════════════════════════════════╕
│DESTINATION  PROCESSED                                                        │
│auth         3                                                                │
│ppp          0                                                                │
│cli          0                                                                │
│sink-file    879                                                              │
│syslog       327                                                              │
│kern         1                                                                │
│openvpn      0                                                                │
│alarm        1                                                                │
│messages     326                                                              │
│ntp          2                                                                │
│sink-relay   879                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

╒ Filters ═════════════════════════════════════════════════════════════════════╕
│FILTER    MATCHED  NOT_MATCHED                                                │
│ntp       2        328                                                        │
│auth      3        327                                                        │
│ppp       0        330                                                        │
│cli       0        330                                                        │
│syslog    327      3                                                          │
│kern      1        329                                                        │
│openvpn   0        330                                                        │
│alarm     1        329                                                        │
│messages  326      4                                                          │
└──────────────────────────────────────────────────────────────────────────────┘
example:/#>

This is also a context that can be entered, with additional commands to view the status of specific aspects of the logging setup:

example:/#> logging
example:/config/logging/#>

show source [connection|facility|program|severity|summary|verbose]

Show source related status information.

A number of options are available to show different levels of detail for the source status. If no option is provided, a summary of the source status will be shown.

Example

example:/config/logging/#> show source
╒ Sources ═════════════════════════════════════════════════════════════════════╕
│TYPE        NAME             DESCRIPTION  PROCESSED                           │
│remote      sink-remote      192.168.1.1  892                                 │
│unix-dgram  local-userspace  /dev/log     318                                 │
│file        local-kernel     /dev/kmsg    1                                   │
└──────────────────────────────────────────────────────────────────────────────┘
client1:/logging/#>

connection

Show status information for remote connections over TCP.

Example

example:/config/logging/#> show source connection
[…]

facility

Show a status summary on the number of messages that have been generated per facility.

Example

example:/config/logging/#> show source facility
[…]

program

Show a status summary on the number of messages that have been generated by each application/program.

Example

example:/config/logging/#> show source program
[…]

severity

Show a status summary on the number of messages per severity level.

Example

example:/config/logging/#> show source severity
[…]

summary

Show a summary of the source status.

Example

example:/config/logging/#> show source summary
[…]

verbose

Show more detailed status information for the source.

Warning

This command includes some verbose information and may occupy additional width in the terminal, more so than usual.

Example

example:/config/logging/#> show source verbose
[…]

show destination [file|remote|summary|verbose]

Show destination related status information.

A number of options are available to show different levels of detail for the destination status. If no option is provided, a summary of the destination status will be shown.

Example

example:/config/logging/#> show destination
╒ Destinations ═════════════════════════════════════════════════════════════════════════════════╕
│TYPE    NAME        DESCRIPTION             PROCESSED  DROPPED  WRITTEN  QUEUED  MEMORY_USAGE  │
│remote  sink-relay  tls,server1:6514        735        0        735      0       0             │
│remote  sink-relay  tls,Syslog-Server:6514  285        0        0        0       0             │
│file    alarm       /var/log/alarm          1          0        1        0       0             │
│file    sink-file   /log//from-hosts        888        0        888      0       0             │
│file    syslog      /var/log/syslog         330        0        330      0       0             │
│file    ntp         /var/log/ntp.log        2          0        2        0       0             │
│file    messages    /var/log/messages       329        0        329      0       0             │
│file    auth        /var/log/auth.log       3          0        3        0       0             │
│file    kern        /var/log/kern.log       1          0        1        0       0             │
└───────────────────────────────────────────────────────────────────────────────────────────────┘

file

Show status information for file destinations.

Example

example:/config/logging/#> show destination file
[…]

remote

Show status information for remote destinations.

Example

example:/config/logging/#> show destination remote
[…]

summary

Show a summary of the destination status.

Example

example:/config/logging/#> show destination summary
[…]

verbose

Show more detailed status information for the destination.

Warning

This command includes some verbose information and may occupy additional width in the terminal, more so than usual.

Example

example:/config/logging/#> show destination verbose
[…]

show filter

Show filter related status information.

Example

example:/config/logging/#> show filter
╒ Filters ═════════════════════════════════════════════════════════════════════╕
│FILTER    MATCHED  NOT_MATCHED                                                │
│ntp       2        331                                                        │
│auth      3        330                                                        │
│ppp       0        333                                                        │
│cli       0        333                                                        │
│syslog    330      3                                                          │
│kern      1        332                                                        │
│openvpn   0        333                                                        │
│alarm     1        332                                                        │
│messages  329      4                                                          │
└──────────────────────────────────────────────────────────────────────────────┘
client1:/logging/#>

show all

Show all logging status information.

Warning

This command includes some verbose information and may occupy additional width in the terminal, more so than usual.

Example

example:/config/logging/#> show all
[…]

show

Show a summary of the logging status.

Example

example:/config/logging/#> show
[…]

Example

This section is intended to provide a simple example of how to configure a logging sink, and the associated components. For additional in-depth configuration examples, refer to the separate How-To guides.

Logging to Custom File on Internal RAM Disk

In this example we want to create a simple setup where we log all messages of severity notice or higher to a file on the internal RAM disk. This file will be rotated when it reaches a size of 1MB, and a maximum of 5 rotated files will be kept.

We start by configuring the source:

example:/#> configure
example:/config/#> logging
example:/config/logging/#> source local
example:/config/logging/source-local/#> userspace
example:/config/logging/source-local/#> kernel
example:/config/logging/source-local/#> end
example:/config/logging/#>

Next we configure the destination:

example:/config/logging/#> destination file-1
example:/config/logging/destination-file-1/#> type file
example:/config/logging/destination-file-1/#> file-name my-file-1
example:/config/logging/destination-file-1/#> media internal
example:/config/logging/destination-file-1/#> size 1M
example:/config/logging/destination-file-1/#> rotate 5
example:/config/logging/destination-file-1/#> end
example:/config/logging/#>

Now we configure the filter:

example:/config/logging/#> filter filter-1
example:/config/logging/filter-filter-1/#> level notice..
example:/config/logging/filter-filter-1/#> end
example:/config/logging/#>

Now that we have all the components we can configure the sink:

example:/config/logging/#> sink example
example:/config/logging/sink-example/#> source local
example:/config/logging/sink-example/#> destination file-1
example:/config/logging/sink-example/#> filter filter-1
example:/config/logging/sink-example/#> end
example:/config/logging/#>

The configuration overview should now look like this:

example:/config/logging/#> show
Console syslog   : Disabled
External logging : Disabled
Secure mode      : Enabled

╒ Sources ═══════════════════════════════════════════════════════════════════╕
│NAME                                                                        │
│Type: local      USERSPACE  KERNEL                                          │
│local            Yes        Yes                                             │
└────────────────────────────────────────────────────────────────────────────┘

╒ Destinations ══════════════════════════════════════════════════════════════╕
│NAME                                                                        │
│Type: file       MEDIA     PATH                                             │
│file-1           internal  my-file-1                                        │
└────────────────────────────────────────────────────────────────────────────┘

╒ Filters ═══════════════════════════════════════════════════════════════════╕
│NAME             INVERT        TYPE  FILTER                                 │
│filter-1         No           Level  notice,warning,err,crit,alert,emerg    │
└────────────────────────────────────────────────────────────────────────────┘

╒ Sinks ═════════════════════════════════════════════════════════════════════╕
│NAME             SOURCES       DESTINATIONS   OP FILTERS                    │
│example          local         file-1            filter-1                   │
└────────────────────────────────────────────────────────────────────────────┘

example:/config/logging/#>

Now we can leave the configuration context and apply the changes:

example:/config/logging/#> leave
example:/#>

At this point the logging from the local device to the file my-file-1 should be active. It should be possible to view the log messages in the file now:

example:/#> show log://my-file-1
[...]
May 20 12:53:05 example clish[906]: User 'admin' entering domain shell.
May 20 12:53:16 example clish[906]: User 'admin' leaving domain shell.
______________________________________________________________________________
log://my-file-1                                       Mon May 20 12:53:16 2024

Troubleshooting

If you are experiencing issues with your logging configuration, this section provides some general troubleshooting steps to help you identify and resolve the problem.

The status commands, covered in the Status section, can be used to provide an overview of the current logging setup. This can be useful to identify if there are any basic issues with the configuration.

Advanced Troubleshooting

In this section, we provide some advanced troubleshooting steps to help you identify and resolve issues with your logging configuration. For these steps, we will access the system shell to perform additional checks and diagnostics.

example:/#> shell
Domain shell started.
root@example:~ #

The following are some advanced troubleshooting steps you can perform.

Verify the Syslog Configuration

Check that the syslog configuration can be parsed correctly by the application:

root@example:~ # syslog-ng -s -f /etc/syslog-ng-writer.conf
root@example:~ # syslog-ng -s -f /etc/syslog-ng-reader.conf

If there is no additional output, the configuration is correct.

Check the Syslog Application

Check that the syslog applications are correctly running:

root@example:~ # initctl status syslog-ng:reader
     Status : running
   Identity : syslog-ng:reader
Description : System log reader daemon
     Origin : /etc/finit.d/syslog-ng.conf
Condition(s): <+pid/syslog-ng:writer>
    Command : /sbin/syslog-ng -c /var/run/syslog-ng/reader.ctl
              -R /var/run/syslog-ng/reader.persist
              -p /var/run/syslog-ng-reader.pid
              -F --cfgfile /etc/syslog-ng-reader.conf
   PID file : /run/syslog-ng-reader.pid
        PID : 614
       User : root
      Group : admin
     Uptime : 1 min 47 sec
   Restarts : 0 (0/10)
  Runlevels : [S-123456789]
     Memory : --.--
     CGroup : /system/syslog-ng cpu 0 [100, ] mem [, ]
              ├─ 610 syslog-ng -c /var/run/syslog-ng/writer.ctl
                               -R /var/run/syslog-ng/writer.persist
                               -p /var/run/syslog-ng-writer.pid -
              └─ 614 syslog-ng -c /var/run/syslog-ng/reader.ctl
                               -R /var/run/syslog-ng/reader.persist
                               -p /var/run/syslog-ng-reader.pid -
root@zero-12-34-50:~ #

root@zero-12-34-50:~ # initctl status syslog-ng:writer
     Status : running
   Identity : syslog-ng:writer
Description : System log writer daemon
     Origin : /etc/finit.d/syslog-ng.conf
    Command : /sbin/syslog-ng -c /var/run/syslog-ng/writer.ctl
                              -R /var/run/syslog-ng/writer.persist
                              -p /var/run/syslog-ng-writer.pid
                              -F --cfgfile /etc/syslog-ng-writer.conf
   PID file : /run/syslog-ng-writer.pid
        PID : 610
       User : root
      Group : admin
     Uptime : 5 min 49 sec
   Restarts : 0 (0/10)
  Runlevels : [S-123456789]
     Memory : --.--
     CGroup : /system/syslog-ng cpu 0 [100, ] mem [, ]
              ├─ 610 syslog-ng -c /var/run/syslog-ng/writer.ctl
                               -R /var/run/syslog-ng/writer.persist
                               -p /var/run/syslog-ng-writer.pid -
              └─ 614 syslog-ng -c /var/run/syslog-ng/reader.ctl
                               -R /var/run/syslog-ng/reader.persist
                               -p /var/run/syslog-ng-reader.pid -

root@zero-12-34-50:~ #

If the applications are running correctly, the output should look similar to the above.

Generate a Test Log Message

Generate a log message using the logger command to test the logging functionality. For example:

root@example:~ # logger -t test "This is a test log message"

It is also possible to generate messages with a specific facility and severity:

root@example:~ # logger -t test -p local0.info "This is a test log message"

Then check the relevant log file to see if the message was logged correctly.