Sending logs to the panel

1. Introduction

What the service does

The CSP (Central Syslog) module of Esapanel collects the logs of your servers and network devices: successful and failed sign ins, errors, warnings, firewall and VPN events. It keeps them in your subscription, lets you search and analyse them and summarizes them in reports, also as support for documenting the security measures required by the NIS2 directive.

The logs arrive with the syslog protocol, the standard that almost every network device knows. For Windows and Linux servers there is the Esapanel agent, a small program that reads the events of the server and sends them to the panel.

Who this guide is for

The IT staff of the company, or the provider that manages its systems. You need to know how to configure a server or a firewall; you do not need to know Esapanel.

The guide covers only sending the logs: how to configure servers and devices, and how to check that the logs arrive.

What you need

An active CSP subscription.
A panel user who can open the Devices page of the subscription (in the panel: the subscription, then the Devices tile).
Administrative access to the servers and devices to configure.
Servers and devices that can go out to the Internet towards the panel server, on the ports given below. No inbound port has to be opened.

In this guide names and addresses are examples (example.com, 192.0.2.10, 203.0.113.10, 2001:db8::10). The real values of your subscription are on the Devices page.

2. Where to find the values

The server and the ports of the subscription are shown at the top of the subscription page, in the Reception of the logs box: Server, Port in clear, TLS port and Port of the agents.

All the values to enter in the devices are also on the Devices page of the subscription, in the Sending the logs box at the top:

Field on the page	What it holds	In this guide
Server	The name of the server to send to. If the subscription receives on a dedicated address, that address is here	`<server>`
Port	The port of the subscription, in clear	`<port in clear>`
Protocols	"UDP or TCP, syslog RFC 3164 or RFC 5424"
Over TLS (encrypted)	The name of the server and the TLS port, as `name:port`	`<server name>` and `<TLS port>`
Port of the agents	The name of the server and the port of the agents, as `name:port`	`<port of the agents>`

Next to server and port, the Copy button copies the value.

The instructions of each device (see chapter 4) repeat these values, already filled in, and add the Address field: the IP address of the server, for devices that do not accept a name.

The ports are assigned to each subscription and differ from one subscription to another: always use those of your Devices page, never ports taken from other examples.

If the page says "The subscription has no port yet", the reception is not ready yet: contact your service provider.

3. The reception ports

Each subscription receives logs on three ports, all on the same server.

Port	How the logs arrive	For whom
Port in clear (`<port in clear>`)	UDP or TCP, not encrypted	Devices that do not support TLS; rsyslog and NXLog
TLS port (`<TLS port>`, row Over TLS (encrypted))	TCP with TLS: the logs travel encrypted. The server proves its name with its certificate; the device does not present a certificate	Routers and firewalls that support syslog over TLS
Port of the agents (`<port of the agents>`)	TCP with TLS, and the agent presents a client certificate of its own	Only the Esapanel agent, which uses it by itself

The port of the agents is not configured by hand: the agent receives it from the panel when it is installed. It only has to be allowed outbound in the firewall of the servers with the agent, before the installation: you find it in the Reception of the logs box and on the Devices page.

Which port to use

Who sends	How	Port
Windows server	Esapanel agent (recommended)	Chosen by itself: port of the agents
Windows server	NXLog Community Edition, as an alternative	Port in clear, TCP
Linux server (Debian, Ubuntu, Red Hat, Rocky, AlmaLinux)	Esapanel agent (recommended)	Chosen by itself: port of the agents
Linux server	rsyslog, as an alternative	Port in clear, TCP
Router or firewall that supports syslog over TLS	Syslog settings of the device	TLS port, with the server name
Router or firewall without TLS	Syslog settings of the device	Port in clear, UDP or TCP
Switches, access points, NAS, other devices	Syslog settings of the device	TLS port if supported, otherwise port in clear

Security in short

In clear: the logs cross the Internet readable by anyone on the path. Fine for logs that are not sensitive, or when the device offers nothing else.
TLS: the logs travel encrypted and the device checks that it is talking to the right server. The choice to prefer for NIS2, which asks to protect data in transit.
Client certificate (agent): besides encryption, the panel knows for sure which agent is sending: only the agents of your subscription, each with its own certificate, get in on the port of the agents.

TLS requirements

Use the server name, not the IP address. The certificate of the server carries its name: if the device connects to the IP address, the certificate check fails.
TCP only: there is no TLS over UDP.
The device must trust the authority that issued the certificate of the server and have the right clock, otherwise it rejects the certificate.
The Esapanel agent uses TLS by itself when the certificate of the panel is valid (not self-signed); there is nothing to configure.

Ports 514 and 6514 on a dedicated address

Some devices cannot choose the port and send only to the standard port 514 (syslog) or 6514 (syslog over TLS). For them the subscription can receive on a dedicated IP address, assigned by the service provider.

With a dedicated address the Devices page shows:

"The devices may send also to <dedicated address> on the standard port 514": the Receive also on the port 514 button turns it on, Stop the port 514 turns it off;
the same for 6514, with Receive also on the port 6514 and Stop the port 6514.

They are extra ports: 514 brings the logs to the port in clear of the subscription, 6514 to the TLS port. The ports of the subscription stay open. Without a dedicated address, ports 514 and 6514 are not available.

With 6514 the device connects to the dedicated address, but the certificate carries the server name: the device must be able to check that name. If it cannot, use the server name with the TLS port of the subscription.

4. Adding a device

The panel accepts only the logs of the devices of the subscription. The logs of a sender that is not among the devices are not lost at once: they wait in the Quarantine (see chapter 8).

Adding a device step by step

On the Devices page, the Add a device button opens three steps:

Category: "What do you want to add?" Server; Router and firewall; Switch and access point; Storage (NAS); Other device.
Model: the models of the category (the list is in chapter 7). If yours is not there, choose Other.
Name and instructions: the Name of the device, the one you know it by (for example "Firewall of the office"), and how the panel recognizes it.

For Windows servers and for Linux servers with the agent the third step is different: see chapters 5 and 6.

For the other devices the third step asks:

Field	What to enter
Name of the device	A name for you
Recognized by	How the panel recognizes the logs of the device (see below); the panel proposes the choice suited to the model
Address or name	The matching value
Timezone	The timezone of the clock of the device, for example `Europe/Rome`
Alert if silent for	An email if the device stops sending (see chapter 8)

Then Add and show the instructions: the device is registered and its page shows the instructions of the model, already filled in with the values of the subscription.

How a device is recognized

Recognized by	Example	When to use it
IP address	`203.0.113.10` or `2001:db8::10`	The fixed public address the device sends from. The normal choice for routers and firewalls
Network	`203.0.113.0/28`	Several fixed addresses of the same network
DNS name	`office.example.com`	An address that changes, with a DNS name (dynamic too) that follows it: the panel resolves it again from time to time
Device name	`FW-OFFICE`	The name the device writes in every log (the HOSTNAME field of syslog). It is accepted from any address, but only on the ports of your subscription: useful for a line that changes address, such as a backup line
Esapanel agent		Enrolls by itself: nothing to enter

Good to know:

The address is the one the panel sees, that is the public address of the Internet connection the device goes out from. Several devices behind the same connection (for example a switch and a NAS in the office) go out with the same address: a device recognized by that address accepts the logs of all of them. To tell them apart, recognize each one by its Device name.
The Device name is the least strict way: whoever knows the name and the port could send logs in its name. Prefer the IP address when it is fixed, or the agent on servers.
For a Linux server with rsyslog the name in the logs is the one given by the hostname command on the server.

If the Devices page says "This subscription accepts logs from any source", your plan does not check the senders: all the logs arrive, even with no devices in the list.

The limit of devices

The plan sets how many devices the subscription can have: the Devices page shows the count, for example "3 of 10 sources". Every device counts one, an agent too.

When the limit is reached, Add a device disappears and the page says "The plan allows N sources: remove one, or ask for a larger plan". To free a place, Remove a device no longer used: its next logs will go to the Quarantine.

Changing a device

In the list, the Instructions link (or the name of the device) opens its page: there you can change the Name of the device and the Model and read the instructions again. In the list you can change Timezone and Alert if silent for, with Save.

5. Windows servers

With the Esapanel agent (recommended)

The agent is a Windows service that reads the event log and sends the events to the panel. It enrolls in the subscription by itself: there are no addresses to authorize, even if the server changes address or sits behind a NAT.

What it sends:

the whole Security log (sign ins, failed sign ins, locked accounts, users and groups changed);
the warnings and errors of System and Application.

It starts from the new events: the history already in the event log is not sent. If the panel does not answer, the events wait in a queue on the disk of the server and leave when it is back; after a restart of the server the agent goes on from where it stopped.

Installation:

On the Devices page: Add a device, category Server, model Windows Server.
Write the Name of the device (for example "Mail server") and press Show the commands.
The panel shows the PowerShell commands, with the enrollment code and the name already in them. Copy the commands.
On the server, open PowerShell as administrator and run the commands. They download the agent from the panel into C:\Program Files\Esapanel, install it as a Windows service and enroll it in the subscription.
The panel page stays on "Waiting for the agent to enroll" and updates by itself. When the agent has enrolled it shows "The agent has enrolled." with the Open the device link.

The device appears in the Devices list with the chosen name, recognized by Esapanel agent.

The server must be able to reach, outbound:

the address of the panel written in the command (after --panel), in HTTPS: it uses it to enroll and, at start and every 6 hours, to ask for its configuration;
the server of the subscription on the port of the agents (or, without a certificate, on the TLS port or the port in clear), in TCP.

The certificate of the agent. At installation the agent creates a key of its own, which never leaves the server, and gets from the panel a client certificate valid for one year. It renews it by itself a month before it expires. The device page shows "The agent sends over TLS with its client certificate, valid until …".

Useful commands

In PowerShell as administrator:

Command	What it does
`& "C:\Program Files\Esapanel\esapanel-agent.exe" status`	Shows the name of the agent, where it sends (server, port, TLS, end of the certificate), what it reads and how much data waits in the queue
`& "C:\Program Files\Esapanel\esapanel-agent.exe" uninstall`	Stops and removes the service; the data of the agent stay
`& "C:\Program Files\Esapanel\esapanel-agent.exe" uninstall --purge`	Removes the service and deletes the data of the agent too (configuration, enrollment, key, queue)

The data of the agent (configuration, certificate, queue, its log agent.log) are in C:\ProgramData\Esapanel\Agent, readable only by administrators.

Uninstalling the agent does not remove the device from the panel: remove it with Remove on the Devices page, so it frees its place in the limit of the plan.

Updating the agent

Open the page of the device in the panel (Instructions link in the list): for an agent already enrolled it shows the commands that update the agent and keep its enrollment, so no new device is created. Run them in PowerShell as administrator.

A server reinstalled from scratch has lost its enrollment: add it again as a new device and remove the old one.

With NXLog (alternative)

If you do not want to install the agent, the section Instead of the agent: NXLog Community Edition on the same page shows an alternative with a free third-party product:

Install NXLog Community Edition from nxlog.co (the site asks for a free registration before the download).
Run in PowerShell as administrator the commands the page shows: they keep a copy of the previous configuration, download the one of the panel and restart NXLog.

NXLog sends the same events as the agent (all of Security, warnings and errors of System and Application) to the port in clear, in TCP, with syslog RFC 5424.

With NXLog the device does not register by itself: the first logs arrive in the Quarantine. From there authorize the address of the server (Authorize the address) or its name (Authorize the device name); see chapter 8. Then, on the page of the device, choose the model Windows Server.

6. Linux servers

For servers of the Debian family (Debian, Ubuntu) and of the Red Hat family (Red Hat, Rocky, AlmaLinux) the panel offers two ways: the Esapanel agent, recommended, and rsyslog.

With the Esapanel agent (recommended)

The agent is a systemd service that reads the journal of the server.

What it sends:

all the messages of the journal with severity warning or worse (warning, error, critical, …);
all the sign-in messages (facilities auth and authpriv: sshd, sudo, su, login), at any severity. For SSH sign ins it reports user and address, successful and failed.

As on Windows: it enrolls by itself, no address to authorize, queue on disk if the panel does not answer, nothing lost after a restart; it starts from the new messages.

Installation:

On the Devices page: Add a device, category Server, model Linux Debian / Ubuntu or Linux Red Hat / Rocky / AlmaLinux.
The page proposes With the agent of Esapanel (recommended). Write the Name of the device and press Show the commands.
Copy the commands and run them on the server as root (or with sudo). They download the agent for the architecture of the server (amd64 or arm64) into /usr/local/bin/esapanel-agent, install it as the systemd service esapanel-agent and enroll it in the subscription. curl is needed.
The page goes from "Waiting for the agent to enroll" to "The agent has enrolled." with the Open the device link.

The panel recognizes by itself whether the server belongs to the Debian or the Red Hat family. Outbound connections and the certificate work as for Windows (see chapter 5).

Useful commands (as root):

Command	What it does
`esapanel-agent status`	Name, where it sends (server, port, TLS, end of the certificate), queue
`esapanel-agent uninstall`	Stops and removes the service; the data stay
`esapanel-agent uninstall --purge`	Removes the service and deletes the data of the agent too
`systemctl status esapanel-agent`	The state of the service

The data of the agent are in /var/lib/esapanel-agent, with its log agent.log.

Updating: the page of the device of an agent already enrolled shows the commands that update it and keep its enrollment. A server reinstalled from scratch is added again as a new device, removing the old one.

With rsyslog (alternative)

rsyslog is the syslog service already present in many distributions. It does not require installing the agent.

When adding the server choose Use rsyslog instead.
Fill in the fields (see chapter 4): usually Recognized by = Device name, with the name given by the hostname command on the server; or IP address, if the server goes out with a fixed address.
Add and show the instructions. The page of the device shows the commands to run as root:
they install rsyslog, if missing (Debian 12 and later no longer install it);
they download from the panel the file /etc/rsyslog.d/90-esapanel.conf (with Show the file you can read it first);
on Red Hat, Rocky and AlmaLinux they add the port of the subscription to the ports SELinux allows to rsyslog (where SELinux is off the command gives an error that can be ignored);
they restart rsyslog and send a test log ("Esapanel test").

The configuration file sends all the logs of the server to the port in clear, in TCP, with syslog RFC 5424, and keeps a queue on disk: if the panel does not answer, the logs wait on the server.

The commands download the file from a link of the subscription. The link holds only name, address and port, no secret. New code for the links (at the bottom of the Devices page) stops the commands copied before; the configuration already on the servers keeps working.

Other servers

For a server that is neither Windows nor of the Debian or Red Hat family, choose the model Other of the Server category and use the general settings of chapter 7.

7. Routers, firewalls and other devices

Routers, firewalls, switches, access points and NAS send their logs with their own syslog settings, from the web interface or the command line. First add the device in the panel (see chapter 4), usually recognized by the public IP address it sends from; then configure it.

General settings

Setting of the device	Value
Syslog server	`<server>`, or the Address if the device wants an IP address
Port	`<port in clear>` (or 514 on the dedicated address, if on)
Protocol	UDP or TCP
Format	syslog RFC 5424 or RFC 3164 (the "classic" one): both are fine
Level of the messages	At least informational, warnings and errors; for firewalls and VPNs also traffic and sign-in events, if you need them

With TLS, if the device supports it:

Setting of the device	Value
Syslog server	`<server name>` of the Over TLS (encrypted) row: the name, never the IP address
Port	`<TLS port>` (or 6514 on the dedicated address, if on)
Protocol	TCP with TLS
Client certificate	None: the device does not have to present one

UDP or TCP? For devices UDP is enough. TCP keeps the logs in order and does not lose them on a busy line; with UDP the logs sent while the reception is stopped (for example during a restart of the server) are lost.

The time of the logs. Every log has the time the panel receives it, always right, used to search and sort the logs. It also has the time written by the device:

with RFC 5424 the device states its timezone, and the time stays as it is;
with RFC 3164 the device writes the time of its clock without a timezone. Set the Timezone of the device in the panel (for example Europe/Rome, which includes daylight saving time): the panel turns that time into the right instant. "Time as it arrives" leaves it as it is.

The timezone is set when the device is added (the panel proposes yours) and changed in the Devices list; a change applies to the following logs. In any case keep the clock of the device in sync (NTP).

Models with their own instructions

For these models the page of the device shows where the settings are in the menus, or the commands to copy, already filled in with the values of the subscription:

Category	Models
Router and firewall	DrayTek Vigor; Zyxel ZyWALL / USG FLEX; Fortinet FortiGate; Cisco ASA; Check Point; MikroTik; pfSense / OPNsense; Sophos Firewall; SonicWall; WatchGuard Firebox
Switch and access point	Cisco IOS (Catalyst); HPE Aruba; Ubiquiti UniFi; MikroTik
Storage (NAS)	Synology DSM; QNAP QTS

Some notes from the instructions:

pfSense and OPNsense: step-by-step guide in Sending logs from pfSense and OPNsense.
MikroTik: step-by-step guide in Sending logs from MikroTik. The firewall rules need a log prefix with the action (for example DROP-WAN): the RouterOS line does not say whether the packet passed.
DrayTek Vigor: System Maintenance › SysLog / Mail Alert Setup: enable SysLog, enter server and port, choose the kinds of messages to send.
Zyxel: if the model cannot change the port, the dedicated address with port 514 is needed.
Cisco ASA: use UDP: with TCP, if the server does not answer, the ASA can stop passing traffic.
Synology and QNAP: choose the RFC 5424 format (on Synology "IETF").

Menus change with the firmware version: if the path given does not match, look for the "syslog" or "remote log" settings of the device and use the values of the general settings.

For a model not in the list choose Other: the page shows the general values. The same goes for the devices of the Other device category (for example a printer or a UPS that sends syslog).

8. Checking that the logs arrive

The page of the device

After adding it, the page of the device shows:

Recognized by: how the panel recognizes it;
Last log: "Last log from <address>, <when>", or "No log yet";
until something arrives, "Waiting for the first log of the device: this page updates by itself".

To try, create an event on the device: for example a sign in to its administration interface. The rsyslog commands send a test log by themselves.

For an agent the Devices list also shows "Agent <version>, last heartbeat <when>": the agent sends a heartbeat every 5 minutes, even when the server has no events. Just enrolled it shows "Enrolled: waiting for the first heartbeat of the agent".

The logs received are in the Logs tile of the subscription.

The Quarantine

The logs that reach the ports of your subscription from a sender that is not among the devices go to the Quarantine (Quarantine tile). They stay a few days (the page says how many), then they are deleted. They are grouped by Address and Device name, with the number of logs and the period.

For each sender:

Button	What it does
Authorize the address	The sender becomes a device recognized by its address; its logs in quarantine move into the subscription
Authorize the device name	The same, recognized by the name it writes in the logs, from any address
Discard	Deletes its logs in quarantine; the next ones go back to the quarantine
Ignore the address / Ignore the name	Its logs in quarantine are deleted and the next ones dropped on arrival, only counted. It does not count among the devices. Stop ignoring, in the Ignored senders list, undoes it

An authorized sender counts among the devices of the plan: if the limit is reached, the page asks to remove one from the Devices page. After authorizing it, choose its Model on the page of the device.

Ignore only senders you know and do not want, such as a test device: their logs are not kept anywhere.

The Quarantine is the first place to look when a configured device does not show up: often its logs arrive, but from an address different from the one entered.

Alert if a device is silent

The Alert if silent for column of the Devices list (Never, 15 minutes, 1 hour, 6 hours, 24 hours) sends an email when a device has sent no logs for longer than that, for example a firewall switched off or an office without connection, and another when it starts again. In the list the device shows "Silent since …".

Choose it for the devices that send all the time: many send only when something happens.
For agents it is always useful: the heartbeat every 5 minutes counts as activity, so a quiet server does not look switched off.
If logs arrived in the Quarantine meanwhile, the email names their senders: often the device has a new address.

9. Common problems

Nothing arrives

The Quarantine. If the logs are there, the device sends but is not recognized: authorize it, or correct the address or the name in the Devices list. Remember that what counts is the public address the device goes out to the Internet with, not the one of the internal network.
Port and protocol. Check that port and protocol are those of the Devices page: the port in clear accepts UDP and TCP; the TLS port only TCP with TLS. A device configured in clear on the TLS port, or with TLS on the port in clear, delivers nothing.
The outbound firewall. Your firewall must let traffic out towards the panel server on the port used (UDP and/or TCP). For the agent: the address of the panel in the command, in HTTPS, and the Port of the agents of the Devices page.
Ports 514 and 6514 work only on the dedicated address and only if turned on on the Devices page.
An ignored sender. Check the Ignored senders list in the Quarantine.
An agent. Run the status command and look at the log of the agent (agent.log in the data folder): if data wait in the queue, the agent does not reach the server.

The time of the logs is wrong

If the device sends RFC 3164, set its Timezone in the Devices list and save: it applies to the following logs.
Check that the clock of the device is right (NTP).
The time of reception of the panel is always right: searching and sorting the logs use it.

The enrollment of the agent is refused

The agent writes "the panel refused the enrollment", followed by the reason.

Reason	What to do
The enrollment code is not valid, or the subscription is not active	Someone gave a New code (section Codes of the agents and of the links, at the bottom of the Devices page): the commands copied before no longer enroll agents. Copy the commands from the page again. If the subscription is suspended, contact your service provider
The subscription already has the maximum number of devices	Remove a device no longer used, or ask for a larger plan
Too many requests	Wait a minute and try again

The enrollment code lets anyone add devices to the subscription: give it only to whoever installs the agent. If it ended up where it should not, give a New code: the agents already enrolled keep working.

The agent sends without a client certificate

If the page of the device says "The agent sends without a client certificate", the agent was installed before the certificates existed, or the panel could not sign it yet. The agent asks for the certificate by itself at start; if the message stays, reinstall it as a new device:

uninstall the agent with uninstall --purge;
remove the old device with Remove (so it does not count in the limit);
add the server as a new device and run the commands of the page.

TLS errors

The name: the device must connect to the server name of the Over TLS (encrypted) row, not to the IP address, otherwise the certificate check fails.
The authority: if the device rejects the certificate of the server, it probably does not know the authority that issued it. On some devices the list of authorities is updated with the firmware or imported by hand: ask your service provider which authority the certificate uses.
The clock: a wrong clock makes the certificate look expired or not yet valid.
The protocol: TLS only over TCP.
If the device cannot use TLS, send to the port in clear.