====== Syslog ====== This chapter covers some aspects related to :osdx:cfg:`system syslog`, which is a feature that allows the user to manage the underlying Syslog protocol. The syslog protocol makes the generation of log messages on various subsystems possible, as well as storing them in a local file or forwarding them to a central syslog server (which collects and stores the messages). This helps network management identify potential issues and security threats. Concepts ======== To help store log messages accross multiple devices within the system (routers, switches, etc.), a syslog server is set up to stash the log messages and filter them at a later stage. These log messages have a header with information on the date of generation, the facility that sends the message, the error code and the subsystem responsible for generating the message. Let's assume we have received the following log message from the router: .. code-block:: bash 2023-05-10 09:40:39.181655 authpriv-info , sshd[2390]: Server listening on 0.0.0.0 port 22. ``2023-05-10 09:40:39.181655`` is the timestamp marking when the message was received, while ``authpriv-info`` means the authprive feature (Security and authentication messages) has generated the message with an info code. ``sshd[2390]`` indicates the name of the subsystem that generated the message, with sshd being the name of the subsystem and (PID) the subsystem's process identifier. The rest of the message is the body of the text. Output Channels =============== The syslog feature is capable of storing log messages in many ways using output channels. One or more of these may be used at the same time: Static Channels --------------- - Console: Log messages are displayed on the console. * :osdx:cfg:`system syslog console` - Events: Log messages are sent to the event logger by default: ``running://log/events``. * :osdx:cfg:`system syslog events` - Global: Log messages are sent to the global log file by default: ``running://log/messages``. * :osdx:cfg:`system syslog global` User-Defined Channels --------------------- * File: Log messages are stored in a file under the ``running://log/user/`` directory. * :osdx:cfg:`system syslog file *` * Host: Log messages are sent to a remote syslog server. * :osdx:cfg:`system syslog host *` * User: Log messages are displayed on the user console. * :osdx:cfg:`system syslog user *` Filters ======= Each part of the inner :osdx:cfg:`system syslog` feature is capable of filtering between generated log messages. To filter the syslog, the user must first create a filter name that will be used to identify the filters that are subsequently applied (regardless of whether the user needs to apply one or more filters). For example: .. code-block:: none set system syslog file filter myfilter ... The user can then use this filter name to apply any filter type described below: * **app**: The app filter only accepts the syslog messages generated by a particular subsystem (e.g., sshd for ``service ssh`` subsystem). The name of the subsystem appears right before the message content. * :osdx:cfg:`system syslog file * filter * app *` * **level**: The level option only returns log messages whose severity is higher than (or equal to) the level selected. * :osdx:cfg:`system syslog file * filter * level *` These are the error codes, ranging from more to less severe: * Emergency: system is unusable * Alert: action must be taken immediately * Critical: critical conditions * Error: error conditions * Warning: warning conditions * Notice: normal but significant condition * Info: informational messages * Debug: debug-level messages * **regex**: The regex filter only returns log messages whose content matches the POSIX-Extended Regular Expression. * :osdx:cfg:`system syslog file * filter * regex *` * **not**: Negate the filter. * :osdx:cfg:`system syslog file * filter * not app *` * :osdx:cfg:`system syslog file * filter * not level *` * :osdx:cfg:`system syslog file * filter * not regex *` Options ======= There are options to compress the number and size of stored log files before redirecting them to an internal file. **Compression**: * :osdx:cfg:`system syslog file * archive compress` * :osdx:cfg:`system syslog global archive compress` * :osdx:cfg:`system syslog events archive compress` **Number of files**: * :osdx:cfg:`system syslog file * archive files *` * :osdx:cfg:`system syslog global archive files *` * :osdx:cfg:`system syslog events archive files *` **Size of file**: * :osdx:cfg:`system syslog file * archive size *` * :osdx:cfg:`system syslog global archive size *` * :osdx:cfg:`system syslog events archive size *` There are more options when forwarding log messages to an external server via UDP or TCP, as well as for encrypting traffic with TLS or communicating with the Syslog server on a specific interface or VRF. **Forwarding**: * :osdx:cfg:`system syslog host * local-address *` * :osdx:cfg:`system syslog host * local-interface *` * :osdx:cfg:`system syslog host * local-vrf *` * :osdx:cfg:`system syslog host * port *` * :osdx:cfg:`system syslog host * protocol *` * :osdx:cfg:`system syslog host * tls` Remote Server ============= The syslog feature allows log messages to be sent to a remote syslog server. A minimal syslog configuration that sends its logs to a remote server needs the ``filter`` option to be set: * :osdx:cfg:`system syslog host * filter * level *` By default, this configuration will send the log messages to the indicated host address via UDP and port 514. To modify the desired transmission protocol and/or remote port, the following configuration may be used: * :osdx:cfg:`system syslog host * protocol *` * :osdx:cfg:`system syslog host * port *` The underlying network interface and source IP address will be automatically chosen depending on the remote host address. This behaviour may be modified, as shown in :ref:`Source Options ` Secure Communication -------------------- The remote communication that is done by syslog is unencrypted by default. To achieve TLS encrypted communications with a compatible remote server, the ``tcp`` protocol must be used together with the syslog ``tls`` option, as shown below: .. code-block:: none system syslog host protocol tcp system syslog host tls ca system syslog host tls permitted-peer The CA certificate that was used to sign the remote server's certificate must be copied into the system. In the ``tls ca`` option, the user must specify the system path where this CA certificate is located. Then, the remote server's common name must be configured in the ``tls permitted-peer`` field. This value must match the common name found in the remote server's certificate. .. _source_options: Source Options -------------- In some scenarios, explicitly setting the source interface, VRF, or IP address from which the logs are sent to a remote syslog server may be interesting. This can be done through the following fields: * :osdx:cfg:`system syslog host * local-address *` * :osdx:cfg:`system syslog host * local-interface *` * :osdx:cfg:`system syslog host * local-vrf *` The ``local-interface`` and ``local-vrf`` options are mutually exclusive and cannot be used at the same time, since syslog internally treats VRFs as interfaces. .. warning:: If a dummy interface is set as the ``local-interface``, there will be no communication with the remote host (since dummy interfaces do not transmit any packets). To use an IP address that belongs to a dummy interface as the source syslog address, use the ``local-address`` option. .. warning:: When setting a ``local-interface`` value, make sure the specified interface contains a proper route to the indicated ``host`` value. The ``local-address`` parameter allows users to select from which IP address are logs sent. This option is useful when a user wants to set an IP address from a dummy interface as the source address, or to specify the address a physical interface must use if there are several. As a result, this option can be used together with the ``local-interface`` or ``local-vrf`` fields. .. important:: If an IP address belonging to a dummy interface is set as the ``local-address`` and the ``protocol`` option is set to ``tcp``, make sure that the remote server has the appropriate route to reach the IP address belonging to the dummy. Otherwise, the TCP connection between the local and remote system will not be established. It is important that both the ``host`` and ``local-address`` values belong to the same IP family (i.e., both values must be either IPv4 or IPv6 values). If a FQDN is used in the ``host`` field, this must also belong to an IP address from the same family as the ``local-address``.