WeOS
5.29.0

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

Related Documentation

- Logging Configuration
- Logging Relay

## 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 destination called file-1. This destination will be set to write the log messages to a file called from-remotes.log, which 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 logfile 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

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

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.

« Previous Next »