WeOSLogging and Receiving From Remote Clients
About
This document describes how to configure the logging system in WeOS to receive logs from remote clients. For this use case, remote log messages will be received and written to a file on the device. This is for the sake of demonstration and can be easily modified to suit your needs, e.g. sending logs to dedicated log servers, see the Logging Relay for an example of how to achieve something like that.
Prerequisites
This document assumes that you have a basic understanding of the WeOS logging system. If you are not familiar with the logging system, please refer to the Logging Configuration page.
Introduction
The WeOS logging system can be configured to receive log messages from remote clients. This can be useful for debugging purposes, monitoring the network, or relaying logs to a central log server.
In this example, we will configure a logging sink on the device to receive and write log messages from remote clients. Consider a scenario, similar to the one shown in Figure 1, where we have a number of hosts connected to a switch S1.
.---------.
| |
| S1 |
| |
'----+----'
|vlan1: .1
|
|
---+-------------+-------------+--- 192.168.1.0/24
| | |
|.10 |.20 |.30
.--+--. .--+--. .--+--.
| H1 | | H2 | | H3 |
'-----' '-----' '-----'
Figure 1: Example network topology with a switch **S1** and a number of hosts. The switch S1 is connected to the hosts on the 192.168.1.0/24 subnet.
We will configure the switch S1 to receive log messages from any host located in the 192.168.1.0/24 subnet, that are connected to its vlan1 interface.
In the next sections, we will cover the configuration steps required on the switch S1.
Configuration
The major focus of this example is to configure the switch to receive log messages from remote clients. We also need to specify a destination file where the logs will be written.
Step 1: Configure the Logging Sources
For this example scenario, we will configure the switch to be able to receive log messages from any host located on the subnet 192.168.1.0/24, located on the vlan1 interface. An individual source definition will be created for each of the remote transport protocols UDP, TCP, and TLS. Then we can connect these three sources to a single sink.
UDP Source
We create a source called all-udp that listens on the vlan1 interface for log messages from remote clients using UDP:
S1:/#> configure S1:/config/#> logging S1:/config/logging/#> source all-udp S1:/config/logging/source-all-udp/#> type remote S1:/config/logging/source-all-udp/#> transport udp S1:/config/logging/source-all-udp/#> listen vlan1 S1:/config/logging/source-all-udp/#> end S1:/config/logging/#>
TCP Source
We create a source called all-tcp that listens on the vlan1 interface for log messages from remote clients using TCP:
S1:/config/logging/#> source all-tcp S1:/config/logging/source-all-tcp/#> type remote S1:/config/logging/source-all-tcp/#> transport tcp S1:/config/logging/source-all-tcp/#> listen vlan1 S1:/config/logging/source-all-tcp/#> end S1:/config/logging/#>
TLS Source
We create a source called all-tls that listens on the vlan1 interface for log messages from remote clients using TLS:
S1:/config/logging/#> source all-tls S1:/config/logging/source-all-tls/#> type remote S1:/config/logging/source-all-tls/#> transport tls S1:/config/logging/source-all-tls/#> listen vlan1 S1:/config/logging/source-all-tls/#> certificate my-cert S1:/config/logging/source-all-tls/#> ca-certificate my-ca-cert S1:/config/logging/source-all-tls/#> peer-verify trusted S1:/config/logging/source-all-tls/#> end S1:/config/logging/#>
Note
We assume that the certificates my-cert and my-ca-cert have been previously created and are available on the device. Refer to the Certificate Management page for more information on how to manage certificates.
When setting peer-verify trusted, any client that connects to the switch with
TLS must present a certificate that is signed by the CA certificate
my-ca-cert.
Step 2: Configure the Logging Destination
We will configure a logging sink called remote-sink that will write the log messages received from the remote clients to a file called from-remotes.log, that will be stored on the internal RAM disk:
S1:/config/logging/#> destination file-1 S1:/config/logging/destination-file-1/#> type file S1:/config/logging/destination-file-1/#> media internal S1:/config/logging/destination-file-1/#> file from-remotes.log S1:/config/logging/destination-file-1/#> end S1:/config/logging/#>
Step 3: Configure the Logging Sink
Now that we have configured the source and destination components, we can connect them by creating a sink, that we will call remote-sink:
S1:/config/logging/#> sink remote-sink S1:/config/logging/sink-remote-sink/#> source all-udp all-tcp all-tls S1:/config/logging/sink-remote-sink/#> destination file-1 S1:/config/logging/sink-remote-sink/#> end S1:/config/logging/#>
The overview of the configuration should now look something like this:
S1:/config/logging/#> show Console syslog : Disabled External logging : Disabled Secure mode : Enabled ╒ Sources ═══════════════════════════════════════════════════════════════════╕ │NAME │ │Type: local USERSPACE KERNEL │ │local Yes Yes │ │Type: remote TRANSPORT LISTEN PORT FORMAT │ │all-udp udp vlan1 (192.168.1.1) 514 rfc5424 │ │all-tcp tcp vlan1 (192.168.1.1) 601 rfc5424 │ │all-tls tls vlan1 (192.168.1.1) 6514 rfc5424 │ └────────────────────────────────────────────────────────────────────────────┘ ╒ Destinations ══════════════════════════════════════════════════════════════╕ │NAME │ │Type: file MEDIA PATH │ │file-1 internal from-remotes.log │ └────────────────────────────────────────────────────────────────────────────┘ ╒ Filters ═══════════════════════════════════════════════════════════════════╕ │NAME INVERT TYPE FILTER │ ├────────────────────────────────────────────────────────────────────────────┤ │No filter(s) currently configured... │ └────────────────────────────────────────────────────────────────────────────┘ ╒ Sinks ═════════════════════════════════════════════════════════════════════╕ │NAME SOURCES DESTINATIONS OP FILTERS │ │remote-sink all-udp file-1 │ │ all-tcp │ │ all-tls │ └────────────────────────────────────────────────────────────────────────────┘ ╒ Configuration Warnings: 1 ═════════════════════════════════════════════════╕ │# Description │ │1 Secure Mode is currently enabled for logging, but at least one remote │ │ source is configured. This means that this source, or sources, will │ │ not be able to receive log messages. If a remote source is intended to │ │ receive log messages, Secure Mode must be disabled. │ └────────────────────────────────────────────────────────────────────────────┘
As we can see from the output above, we have a configuration warning that is displayed:
╒ Configuration Warnings: 1 ═════════════════════════════════════════════════╕ │# Description │ │1 Secure Mode is currently enabled for logging, but at least one remote │ │ source is configured. This means that this source, or sources, will │ │ not be able to receive log messages. If a remote source is intended to │ │ receive log messages, Secure Mode must be disabled. │ └────────────────────────────────────────────────────────────────────────────┘
This warning is displayed because the secure mode is enabled for logging, but we have configured remote sources. This means that the remote sources will not be able to receive log messages. If we want the remote sources to receive log messages, we must disable the secure mode:
S1:/config/logging/#> no secure-mode
With this configuration all remote clients sending log messages to S1, should be logged to the file from-remotes.log, located in the internal RAM log folder. Leave the configuration context to apply the changes:
S1:/config/logging/#> leave Applying configuration. Configuration activated. Remember "copy run start" to save to flash (NVRAM). S1:/#>
Verification
If everything is configured correctly, we should be able to see the log messages from the remote clients in the from-remotes.log file. We can verify this by checking the contents of the file:
S1:/#> show log://from-remotes.log [...] May 27 14:43:56 192.168.1.10 admin: test-1 May 27 14:43:57 192.168.1.20 admin: test-2 May 27 14:43:57 192.168.1.30 admin: test-3 ______________________________________________________________________________ log://from-remotes.log Mon May 27 14:43:57 2024 S1:/#>
In the example above, we have generated log messages from three different hosts H1, H2, and H3.
Tip
If we want the log messages to be written to the file with their hostnames
instead of their IP addresses, we can configure the source to use the
keep-hostname option. This will keep the hostname of the remote client in
the log message:
S1:/#> configure S1:/config/#> logging S1:/config/logging/#> source all-udp S1:/config/logging/source-all-udp/#> keep-hostname S1:/config/logging/source-all-udp/#> end S1:/config/logging/#> S1:/config/logging/#> source all-tcp S1:/config/logging/source-all-tcp/#> keep-hostname S1:/config/logging/source-all-tcp/#> end S1:/config/logging/#> source all-tls S1:/config/logging/source-all-tls/#> keep-hostname S1:/config/logging/source-all-tls/#> end S1:/config/logging/#> leave Applying configuration. Configuration activated. Remember “copy run start” to save to flash (NVRAM). S1:/#> </pre
We can also take a look at the logging source status output:
S1:/#> show logging source
╒ Sources ═════════════════════════════════════════════════════════════════════╕
│TYPE NAME DESCRIPTION PROCESSED │
│remote sink-all-udp 192.168.1.1 61 │
│remote sink-all-tcp tcp,192.168.1.20 65 │
│remote sink-all-tls tls,192.168.1.30 63 │
│unix-dgram local-userspace /dev/log 298 │
│file local-kernel /dev/kmsg 50 │
└──────────────────────────────────────────────────────────────────────────────┘
S1:/#>
We should be able to see that the PROCESSED column for the remote sources is increasing, which means that the log messages are being received and processed by the switch.
For the remote sources using a connection-oriented transport protocol, TCP and TLS (Uses TCP as the underlying transport), we can also check the number of connections that are currently established:
S1:/#> show logging source connection
╒ Source Connections ══════════════════════════════════════════════════════════╕
│SOURCE LISTEN_SOCKET NUM_CONNECTIONS │
│sink-all-tcp 192.168.1.1:601 1 │
│sink-all-tls 192.168.1.1:6514 1 │
└──────────────────────────────────────────────────────────────────────────────┘
S1:/#>
Since UDP is a connectionless protocol, we do not have any connection information for the UDP source.
Troubleshooting
The following is an example of a number of things to check if the logging system is not working as expected:
-
Ensure that secure-mode is disabled if you want to receive log messages from remote clients,
no secure-mode. -
Ensure that the clients can simply reach the switch, using ping for example. If the clients cannot reach the switch, they will not be able to send log messages.
-
If TLS is used, ensure that the certificates are correctly configured and that the clients are presenting a certificate that is signed by the CA certificate.
-
If non-standard ports are used, ensure that the clients are sending log messages to the correct port, and that the switch is listening on the correct port.
Conclusion
In this document, we’ve explored how to set up and manage remote logging in our application. We’ve seen how to configure our system to receive logs from a remote source, and how we can connect these sources to a sink to write the logs to a file, in this case.