WeOS
5.29.0

# 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 customised 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.

Related Examples and Use-Cases

- Logging to Remote Machines
- Logging and DHCP Option 7
- Logging Relay
- Logging and Receiving From Remote Clients

## 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 categorise 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/Authorisation 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 `LOGALERT`in 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`.

Note

The Facility and Severity values of a syslog message are always present and combined into a single value known as the Priority. This Priority is computed by multiplying the Facility value by 8 and then adding the Severity value. For instance, if the Facility value is 1 and the Severity value is 5, the Priority would be calculated as `8 * 1 + 5 = 13`.

In binary, the Priority value is represented as an 8-bit number. For the above example, the Priority value of 13 would be represented as `00001101`.

In raw output, such as a Wireshark capture, the Priority is displayed within angle brackets, like `<13>`.

Note

The names of the fields described below, are somewhat based on how they will be displayed in a Wireshark capture.

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 standardised 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.

Log File | Facility | Severity | Description
--- | --- | --- | ---
auth.log | auth, authpriv | * | Logs related to authentication are stored in auth.log.
kern.log | kern | * | Kernel logs are stored in kern.log.
alarm | local0 | * | Alarm logs are stored in alarm.
cli | local1 | * | Command Line Interface logs are stored in cli.
ppp.log | local2 | * | Point-to-Point Protocol logs are stored in ppp.log.
ntp.log | local3, ntp | * | Network Time Protocol logs are stored in ntp.log.
openvpn.log | local4 | * | OpenVPN logs are stored in openvpn.log.
syslog | All except auth, authpriv | * | Logs from all facilities except ‘auth’, ‘authpriv’ are stored in syslog.
messages | All except auth, authpriv, cron, kern, mail, news | * | Logs from all facilities except ‘auth’, ‘authpriv’, ‘cron’, ‘kern’, ‘mail’, ‘news’ are stored in messages.

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

Note

There may be additional log files created by the system by default, that are not listed in the table above. However, the log files listed in the table should always be present in the system, if a message is generated that should be logged to one of these log files, based on the facility and severity of the message.

Warning

As mentioned earlier, the default log files are 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.

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` command after entering the file/log context.

    example:/#> file log
    example:/file/log#> dir
    /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:/#>

Note

The individual size for each of the default log files is limited to 100K. Each file will be rotated up to one time, meaning that the system will keep the current log file and the previous log file. As an example, if the messages log file reaches 100K, it will be renamed to messages.0 and a new messages log file will be created.

Each default log file will also allow for two compressed log files to be retained. A log file is compressed when we reach the maximum number of rotations for a given log file. When this happens, the oldest rotated log file will be compressed. The compressed log files will be named messages.1.gz and messages.2.gz. The system will keep the most recent compressed log file and delete the oldest compressed log file when a new compressed log file is created.

As an example, if we say that we have an average message size of 100-200 bytes, we can allow for around 500-1000 messages in each log file. This is a rough estimate, and the actual number of messages that can be stored in a log file will depend on the actual size of the messages.

To view the contents of the system main 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
    ______________________________________________________________________________
    messages                                        Mon May 20 14:53:47 2024

    example:/#>

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

    example:/#> show logfile 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'
    ______________________________________________________________________________
    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

Tip

Also, the `follow` command is very useful when monitoring log files. It continuously lists new lines as they are appended to a file. Use `Ctrl-C` to stop and return to the command prompt.

    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.

Event | Facility | Severity | Example
--- | --- | --- | ---
Login successful | auth | notice | Authentication successful for user ‘admin’ from 10.0.0.1
Login failed | auth | warning | Authentication failed for user ‘admin’ from 10.0.0.1
Audit trail | security | notice | User ‘admin’ changed the configuration
System startup | console | notice | \\/ Westermo WeOS v5.7, entering runlevel 3
System shutdown | console | notice | \\/ Westermo WeOS v5.7, entering runlevel 6
System update | console | notice | \\/ Westermo WeOS v5.7, entering runlevel 9
Enter Maintenance mode | user | notice | Entering maintenance mode for upgrade to WeOS-5.7.x.pkg …
Exit Maintenance mode | user | notice | Exiting maintenance mode for upgrade
Service start | console | notice | Starting mdnsd:1, PID: 1203
Service stop | console | notice | Stopping mdnsd:1, PID: 1203, sending SIGTERM…
Service restarting | console | notice | Restarting mdnsd:1, PID: 1203, sending SIGHUP…
Service Died | console | warning | Service mdnsd:1 died, restarting (1/10)
Service FAIL | console | warning | Service mdnsd:1 keeps crashing, not restarting
Link up | console | notice | Link up on eth1
Link down | console | notice | Link down on eth1
DHCP Unknown host ID | console | warning | DHCPDISCOVER(11:22:33:44:55:66) vlan1 no address available
NTP reply not synced | ntp | info | reply from 10.0.0.1: not synced (alarm), next query 64s
NTP synced | ntp | info | clock is now synced
NTP peer valid | ntp | info | peer 10.0.0.1 now valid
NTP update FAIL | ntp | err | no reply received in time, skipping initial time setting
TTDP stack ready | daemon | notice | Bypass relays in normal position (upon startup; IEC 61375)
ECSC comm. established | daemon | notice | ECSP_CTRL traffic heard from ECSC (upon startup; IEC 61375)

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 customised 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 specialised logging setups, such as logging to remote machines, local files, or files on external media (USB or SD Card).

Note

No log messages will be received from any source or sent to any destination unless a sink is configured to utilise them.

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 behaviour 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 analysing these log messages, administrators and developers can identify issues, track system behaviour, 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.

Note

The buffer size is limited. If it becomes full, any new log messages will be dropped until there is space in the buffer again.

Note

To prevent the log buffer from using too much memory, the maximum number of log messages that can be buffered for each destination is divided among all the destinations in use. This means that if you have multiple destinations, the buffer size for each destination will be smaller than if you only have one destination.

#### 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 utilised:

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

Tip

It is possible to invert a filter by using the setting it to `invert`. Meaning that the filter will allow all messages that do not match the filter criteria. As an example, if we have a filter that specify severity `debug` and we set it to `inverted`, it will allow all messages that are not of severity `debug`.

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.
`identification [ hostname | fqdn ]`

  Choose how the device will identify itself in syslog messages.

  There are two options: - `hostname` will use the system hostname, while ignoring any configured or received domain name. - `fqdn` will use the fully qualified domain name, which is a combination of the hostname and the domain name. The domain name is first read from the “domain” command in the “system” configuration context; if unset, it will instead be read from any DHCP leases where the domain name is provided via option 15. If still unavailable, this option will fall back to just using the hostname.

  The default is to use the hostname only.

### 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.
`[no] audit`

  Enable or disable local audit log messages.

  When enabled, the source will collect log messages from the local machine’s audit system. This includes messages related to the operation of the audit system, security events, and other audit-related messages. When disabled, these messages will not be collected.

  Note

  Some of these audit log messages may provide similar information as the regular local userspace and kernel log messages, but they will have a specific format and be associated with unique Event IDs.

  Default: Disabled

  Example

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

  `no`
    Disable logging of audit 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.

`[no] use-local-timestamp`

  Enable or disable usage of local timestamp for received messages.

  If this setting is enabled, the timestamp of the incoming log messages for the remote source will be replaced with the device’s local timestamp, i.e. the time of reception and handling. If disabled, the original timestamp included in the message will be preserved, i.e. the time the message was originally generated based on the sender’s time.

  Default: Disabled

  Example

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

  `no`
    Disable usage of local timestamp for received messages.

##### 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] ignore-hostname-mismatch`

  Enable to ignore certificate hostname mismatch during validation.

  If this option is enabled the subject name of the certificate will be ignored during the validation of the certificate in the TLS handshake, i.e. any mismatch between the hostname and the subject name will be ignored.

  Default: No

  Example

      example:/config/logging/source-example/#> ignore-hostname-mismatch
      example:/config/logging/source-example/#> no ignore-hostname-mismatch

  `no`
    Disable ignoring of certificate hostname mismatch during validation.
`[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.
`[no] revocation`

  Enable or disable certificate revocation checking during the TLS handshake. Default: Disabled.

  If enabled, the system will reject connections if the cached Certificate Revocation List (CRL) is outdated, fails signature verification, or if the certificate is explicitly listed as revoked in the CRL. Note: If a CRL is missing, the connection is still accepted.

  CRLs must be configured in the `config/pki` context.

  `no`
    Disable certificate revocation checking.

  For details on configuring static CRL distribution points, see the Revocation Configuration Guide.

### 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] ignore-hostname-mismatch`

  Enable to ignore certificate hostname mismatch during validation.

  If this option is enabled the subject name of the certificate will be ignored during the validation of the certificate in the TLS handshake, i.e. any mismatch between the hostname and the subject name will be ignored.

  Default: No

  Example

      example:/config/logging/destination-example/#> ignore-hostname-mismatch
      example:/config/logging/destination-example/#> no ignore-hostname-mismatch

  `no`
    Disable ignoring of certificate hostname mismatch during validation.
`[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.
`[no] revocation`

  Enable or disable certificate revocation checking during the TLS handshake. Default: Disabled.

  If enabled, the system will reject connections if the cached Certificate Revocation List (CRL) is outdated, fails signature verification, or if the certificate is explicitly listed as revoked in the CRL. Note: If a CRL is missing, the connection is still accepted.

  CRLs must be configured in the `config/pki` context.

  `no`
    Disable certificate revocation checking.

  For details on configuring static CRL distribution points, see the Revocation Configuration Guide.

### 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:/#>

Note

The logging status information will display information on all the logging configured on the system, this includes any of the default logging as well.

Anything that comes from a custom logging sink configuration should be prefixed with `sink-` when they are referred to in the status output.

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.

Related Examples and Use-Cases

- Logging to Remote Machines
- Logging and DHCP Option 7
- Logging Relay
- Logging and Receiving From Remote Clients

### 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/#>

Note

A source named `local` exists by default from the factory configuration. But for this example we explicitly configure it to show how it is done.

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  AUDIT                                   │
    │local            Yes        Yes     No                                      │
    └────────────────────────────────────────────────────────────────────────────┘

    ╒ 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 logfile 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.
    ______________________________________________________________________________
    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.

Note

To access the system shell, you must connect to the device via the console using an administrative account with the appropriate permissions. While it is possible to access the shell via SSH, this feature must first be enabled through a console session.

    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.

Warning

The system should not produce any invalid configurations for the syslog application. If you suspect that the configuration that has been generated is invalid, please contact technical support.

#### 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.

Warning

If any of the syslog applications are not running, or any of them reports its status as crashed, stopped, or similar, a system bug may have been encountered. Please contact technical support.

#### 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.

« Previous Next »