Syslog setup

Read the following to discover how to configure Syslog interconnection on the LockSelf application.

This option only applies to Private Cloud and On-Premises configurations.

Only the Administrator account can perform this action.

_______________________________________________________________________________________

Syslog Interconnection Prerequisites

To perform the Syslog interconnection, you will need to prepare the following prerequisites:

The IP of the RSyslog server
The port of the RSyslog server
The certificates to enable TLS between LockSelf and your RSyslog server
- The certificate in CRT format
- The private key associated with the certificate
- The certificate chain (intermediate certificates + CA Root)

The authentication mode will be via certificate and fingerprint. You will also need to provide the fingerprint of the server.

Configure the RSyslog Server

RELP Package for RSyslog

Install the package as follows, depending on your distribution and package manager:

# CentOS & RockyLinux : https://centos.pkgs.org/7/centos-x86_64/rsyslog-relp-8.24.0-55.el7.x86_64.rpm.html
c[_] > sudo yum install rsyslog-relp

# Ubuntu : https://packages.ubuntu.com/bionic/admin/rsyslog-relp
c[_] > sudo apt-get install rsyslog-relp

# Debian : https://packages.debian.org/stretch/rsyslog-relp
c[_] > sudo apt install rsyslog-relp

# Alpine : https://pkgs.alpinelinux.org/package/edge/main/x86/rsyslog-relp
c[_] > sudo apk add rsyslog-relp

Server Configuration File:

The following configuration should be adapted to fit the organization of your RSyslog server configuration. However, we recommend adding this configuration in a new file in the directory:

/etc/rsyslog.d/ and naming it, for example, 1-lockself.conf.

# Load the RELP input module
module(load="imrelp" ruleset="<RULESET_NAME>")

# RELP input module configuration
input(type="imrelp" port="<PORT>"
  tls="on"
  tls.caCert="<INTERMEDIATE_AND_CA_CHAIN_PATH>"
  tls.myCert="<CERTIFICATE_PATH>"
  tls.myPrivKey="<PRIVATE_KEY_PATH>"
  tls.authMode="<AUTH_MODE>"
  tls.permittedpeer=["<PEER_IDENTIFICATOR_1>", "<PEER_IDENTIFICATOR_2>", ...]
)

# Ruleset example (output logs received from the RELP input module to '/var/log/relp_log' file)
ruleset (name="<RULESET_NAME>") { action(type="omfile" file="/var/log/relp_log") }

<RULESET_NAME>: The name of the 'ruleset' that will interpret what is received from the RELP input module. You have the option to process this output differently.
<PORT> : The port on which the RELP input module will listen.
<INTERMEDIATE_AND_CA_CHAIN_PATH> : The path to the file containing the intermediate certificates and the CA root.
<CERTIFICATE_PATH> : The path to the file containing the certificate.
<PRIVATE_KEY_PATH> : The path to the file containing the private key.
<AUTH_MODE> : The authentication mode, which can be fingerprint or name (RSyslog documentation)
<PEER_IDENTIFICATOR>: The value of the certificate field that will be used to authorize connections if valid, depending on your <AUTH_MODE>:
- tls.authMode="fingerprint": The SHA1 fingerprint of the certificate, in the format: "SHA1:<FINGERPRINT>".
  You can obtain it using the following command with Openssl:
```
c[_] > openssl x509 -noout -fingerprint -sha1 -inform pem -in <certificate-file.crt>
```
- tls.authMode="name": The DNS of the RSyslog server, in the format: "my.dns.com" or "*.dns.com". The DNS must be part of the DNSs secured by the certificate as the primary DNS or in the AltNames.

Verify the Configuration Syntax

To ensure that the RSyslog configuration is correct, you can use the following command:

c[_] > rsyslogd -N1

# OR

c[_] > rsyslogd -c <path/to/configuration/file>

Apply the New Configuration

To apply the new configuration, you can either restart the service:

# CentOS & RockyLinux:
c[_] > sudo systemctl restart rsyslog.service

# Ubuntu:
c[_] > sudo systemctl restart rsyslog.service

# Debian:
c[_] > sudo systemctl restart rsyslog.service

# Alpine:
c[_] > sudo rc-service rsyslog restart

# OR
c[_] > sudo /etc/init.d/rsyslog restart

Troubleshooting

If the configuration does not seem to be active, we recommend checking the logs of the RSyslog service:

c[_] > journalctl -u rsyslog.service

Or manually start the server with debugging to see all the logs:

c[_] > export RSYSLOG_DEBUG=debug; rsyslogd -d

Log Organization

By Date, Day, Hour, or Other

When receiving logs on the RSyslog server, you may want to organize the logs by month, day, hour, or other criteria. With RSyslog, you can make the log file name dynamic using templates.

# Templates
template (name="<TEMPLATE_NAME>" type="string" string="<TEMPLATED_DESTINATION_FILE_NAME>")

# Load the RELP input module
module(load="imrelp" ruleset="<RULESET_NAME>")

# RELP input module configuration
input(type="imrelp" port="<PORT>"
tls="on"
tls.caCert="<INTERMEDIATE_AND_CA_CHAIN_PATH>"
tls.myCert="<CERTIFICATE_PATH>"
tls.myPrivKey="<PRIVATE_KEY_PATH>"
tls.authMode="<AUTH_MODE>"
tls.permittedpeer=["<PEER_IDENTIFICATOR_1>", "<PEER_IDENTIFICATOR_2>", ...]
)

# Ruleset example (output logs received from the RELP input module to '<TEMPLATED_DESTINATION_FILE_NAME>' file)
ruleset (name="<RULESET_NAME>") { action(type="omfile" dynaFile="<TEMPLATE_NAME>") }

<TEMPLATE_NAME> : Template name, which will be called later by our output module.
<TEMPLATED_DESTINATION_FILE_NAME> : A string built from characters and timereported. You can find all extractable variables from timereported here (from date-unixtimestamp to date-tzoffsdirection, where timestamp is an alias for timereported). For example, <TEMPLATED_DESTINATION_FILE_NAME> can be:
```
/var/log/lockself/%timereported:::date-year%-%timereported:::date-month%-%timereported:::date-day%.log
```
which will generate, for example: /var/log/lockself/2023-04-06.log

Configure the RSyslog Client (On-Premises Only)

LockSelf Log File

Add a mount point in the lockself-api-3 container

Regardless of the chosen launch method (docker run, docker compose, docker swarm), you will need to add the following mount point:

- <LOG_PATH_ON_HOST>:/usr/local/var/log/lockself/application.log

The "<LOG_PATH_ON_HOST>" file can be placed anywhere on the host. You will need to replace "<LOG_PATH_ON_HOST>" with the chosen path on the host.

Activate the Interconnection

In the "env" file, you will need to add the following parameter:

logInFile=1

Once these two steps are completed, restart the lockself-api-3 container.

Install the RELP Package for RSyslog