Skip to content

Commit f1129d8

Browse files
ssahanissahani
authored
Revise systemd-netlogd documentation for clarity
Updated the documentation for systemd-netlogd, enhancing clarity and detail in the description, features, configuration options, and examples.
1 parent 9fe3f99 commit f1129d8

File tree

1 file changed

+217
-121
lines changed

1 file changed

+217
-121
lines changed

‎doc/index.rst‎

Lines changed: 217 additions & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -1,182 +1,278 @@
11
:orphan:
22

3-
systend-netlogd manual page
4-
===========================
3+
systemd-netlogd(8)
4+
==================
5+
6+
.. contents::
7+
:depth: 2
8+
:local:
9+
:backlinks: none
10+
11+
Name
12+
----
13+
14+
**systemd-netlogd** - Forward systemd journal messages to remote hosts via Syslog
15+
16+
Synopsis
17+
--------
18+
19+
::
20+
21+
systemd-netlogd [OPTIONS...]
522

623
Description
724
-----------
825

9-
Forwards messages from the journal to other hosts over the network using the Syslog Protocol (RFC 5424 and RFC 3339). It can be configured to send
10-
messages to both unicast and multicast addresses. systemd-netlogd runs with own user systemd-journal-netlog. Starts sending logs when network is up and stops
11-
sending as soon as network is down (uses sd-network). It reads from journal and forwards to network one by one. It does not use any extra disk space.
12-
systemd-netlogd supports ``UDP``, ``TCP``, ``TLS`` and ``DTLS`` (Datagram Transport Layer Security RFC 6012).
26+
**systemd-netlogd** is a lightweight, network-aware daemon for forwarding log messages from the **systemd journal** to remote hosts over the network using the **Syslog protocol** (RFC 5424 and RFC 3339). It supports unicast and multicast destinations, ensuring efficient log aggregation in distributed environments.
1327

14-
Configuration
28+
Key features:
29+
30+
- **Efficient forwarding**: Reads journal entries sequentially and transmits them one-by-one without buffering or additional disk usage.
31+
- **Network integration**: Leverages ``sd-network`` to start forwarding when the network is up and pause when it's down.
32+
- **Secure transports**: Supports UDP (default), TCP, TLS, and DTLS (RFC 6012 for datagram security).
33+
- **Flexible output**: Formats logs as RFC 5424 (default), RFC 5425 (length-prefixed for TLS), or RFC 3339.
34+
- **Isolation**: Runs as the dedicated system user ``systemd-journal-netlog``.
35+
- **Filtering**: Exclude specific syslog facilities or levels; target journal namespaces.
36+
37+
This daemon is ideal for edge devices, servers, or cloud setups requiring centralized logging with minimal resource impact.
38+
39+
Installation
40+
------------
41+
42+
Use your distribution's package manager:
43+
44+
- **Ubuntu/Debian**: ``sudo apt install systemd-netlogd``
45+
- **Fedora/RHEL**: Available via COPR repositories (search for ``systemd-netlogd``).
46+
- **Arch Linux**: Build from AUR (``systemd-netlogd-git``).
47+
48+
For building from source, see the `GitHub repository <https://github.com/systemd/systemd-netlogd>`_.
49+
50+
User Creation
1551
-------------
1652

17-
|
18-
| **useradd** -G systemd-journal systemd-journal-netlog
53+
The daemon requires a dedicated system user. Create it manually:
1954

20-
This will create a user systemd-journal-netlog
55+
.. code-block:: console
2156
22-
[NETWORK] SECTION OPTIONS
23-
-------------------------
24-
|
25-
|
26-
The "[Network]" section only applies for UDP multicast address and Port:
57+
sudo useradd -r -d / -s /usr/sbin/nologin -g systemd-journal systemd-journal-netlog
2758
28-
| ``Address=``
29-
Controls whether log messages received by the systemd daemon shall be forwarded
30-
to a unicast UDP address or multicast UDP network group in syslog RFC 5424 format.
31-
The address string format is similar to socket units. See systemd.socket(1)
59+
Or via ``sysusers.d`` (preferred):
3260

33-
| ``Protocol=``
34-
Specifies whether to use udp, tcp, tls or dtls (Datagram Transport Layer Security) protocol. Defaults to udp.
61+
.. code-block:: ini
3562
36-
| ``LogFormat=``
37-
Specifies whether to use RFC 5424, RFC 5425, or RFC 3339 format. Takes one of rfc5424, rfc5425, or rfc3339. Defaults to rfc5424. RFC 5425 is mainly useful for sending over TLS; it prepends a message length field to the RFC 5424 format.
63+
# /etc/sysusers.d/systemd-netlogd.conf
64+
# Type Name ID GECOS Home directory Shell
65+
u systemd-journal-netlog - - / /bin/nologin
3866
39-
| ``Directory=``
40-
Takes a directory path. Specifies whether to operate on the specified journal directory DIR instead of the default runtime and system journal paths.
67+
Apply with:
4168

42-
| ``Namespace=``
43-
Takes a journal namespace identifier string as argument. If not specified the data collected by the default namespace is shown.
44-
If specified shows the log data of the specified namespace instead. If the namespace is specified as "*" data from all namespaces
45-
is shown, interleaved. If the namespace identifier is prefixed with "+" data from the specified namespace and the default namespace is shown,
46-
interleaved, but no other.
69+
.. code-block:: console
4770
48-
| ``ConnectionRetrySec=``
49-
Specifies the minimum delay before subsequent attempts to contact a Log server are made.
50-
Takes a time span value. The default unit is seconds, but other units may be specified,
51-
see systemd.time(5). Defaults to 30 seconds and must not be smaller than 1 second.
71+
sudo systemd-sysusers
5272
53-
| ``TLSCertificateAuthMode=``
54-
Specifies whether to validate the certificate. Takes one of no, allow, deny, warn. Defaults to 'no' which disables certificate validation.
73+
Running the Service
74+
-------------------
5575

56-
| ``KeepAlive=``
57-
Takes a boolean argument. If true, the TCP/IP stack will send a keep alive message after 2h (depending on the configuration of
58-
/proc/sys/net/ipv4/tcp_keepalive_time) for all TCP streams accepted on this socket. This controls the SO_KEEPALIVE socket option
59-
(see socket(7) and the TCP Keepalive HOWTO for details.) Defaults to false.
76+
Enable and start via systemd:
6077

61-
| ``KeepAliveTimeSec=``
62-
Takes time (in seconds) as argument. The connection needs to remain idle before TCP starts sending keepalive probes.
63-
This controls the TCP_KEEPIDLE socket option (see socket(7) and the TCP Keepalive HOWTO for details.) Default value is 7200 seconds (2 hours).
78+
.. code-block:: console
6479
65-
| ``KeepAliveIntervalSec=``
66-
Takes time (in seconds) as argument between individual keepalive probes, if the socket option SO_KEEPALIVE has been set on this socket.
67-
This controls the TCP_KEEPINTVL socket option (see socket(7) and the TCP Keepalive HOWTO for details.) Default value is 75 seconds.
80+
sudo systemctl daemon-reload
81+
sudo systemctl enable --now systemd-netlogd.service
6882
69-
| ``KeepAliveProbes=``
70-
Takes an integer as argument. It is the number of unacknowledged probes to send before considering the connection dead and notifying
71-
the application layer. This controls the TCP_KEEPCNT socket option (see socket(7) and the TCP Keepalive HOWTO for details.) Default value is 9.
83+
- **Logs**: ``journalctl -u systemd-netlogd.service``
84+
- **Manual invocation**: ``sudo systemd-netlogd`` (for testing).
7285

73-
| ``SendBuffer=``
74-
Takes an integer argument controlling the receive or send buffer sizes of this socket, respectively. This controls the SO_SNDBUF
75-
socket options (see socket(7) for details.). The usual suffixes K, M, G are supported and are understood to the base of 1024.
86+
Configuration
87+
-------------
7688

77-
| ``NoDelay=``
78-
Takes a boolean argument. TCP Nagle's algorithm works by combining a number of small outgoing messages, and sending them all at once.
79-
This controls the TCP_NODELAY socket option (see tcp(7)). Defaults to false.
89+
Read from ``/etc/systemd/netlogd.conf`` and drop-ins in ``/etc/systemd/netlogd.conf.d/*.conf`` (INI format).
8090

81-
| Optional settings
91+
Options are in the ``[Network]`` section. Reload changes:
8292

83-
| ``StructuredData=``
84-
Specifies the meta information about the syslog message, which can be used for Cloud Based syslog servers, such as Loggly.
93+
.. code-block:: console
8594
86-
| ``UseSysLogStructuredData=``
87-
A boolean. Specifies whether to extract SYSLOG_STRUCTURED_DATA= from journal. Defaults to false.
95+
sudo systemctl reload systemd-netlogd.service
8896
89-
| ``UseSysLogMsgId=``
90-
A boolean. Specifies whether to extract SYSLOG_MSGID= from journal. Defaults to false.
97+
[Network] Section Options
98+
-------------------------
9199

92-
EXAMPLES
100+
.. tabularcolumns:: |p{3cm}|p{1.5cm}|p{1.5cm}|p{7cm}|
101+
102+
+--------------------+----------+-------------+-------------------------------------------------------------+
103+
| Option | Type | Default | Description |
104+
+====================+==========+=============+=============================================================+
105+
| ``Address=`` | string | *(required)*| Destination (unicast ``IP:PORT`` or multicast ``GROUP:PORT``). See :manpage:`systemd.socket(5)`. |
106+
+--------------------+----------+-------------+-------------------------------------------------------------+
107+
| ``Protocol=`` | enum | ``udp`` | ``udp``, ``tcp``, ``tls``, ``dtls``. |
108+
+--------------------+----------+-------------+-------------------------------------------------------------+
109+
| ``LogFormat=`` | enum | ``rfc5424``| ``rfc5424``, ``rfc5425`` (TLS-friendly), ``rfc3339``. |
110+
+--------------------+----------+-------------+-------------------------------------------------------------+
111+
| ``Directory=`` | path | *system* | Custom journal directory. |
112+
+--------------------+----------+-------------+-------------------------------------------------------------+
113+
| ``Namespace=`` | string | *default* | Filter: ID, ``*`` (all), ``+ID`` (ID + default). |
114+
+--------------------+----------+-------------+-------------------------------------------------------------+
115+
| ``ConnectionRetrySec=`` | time | ``30s`` | Reconnect delay (≥1s). See :manpage:`systemd.time(5)`. |
116+
+--------------------+----------+-------------+-------------------------------------------------------------+
117+
| ``TLSCertificateAuthMode=`` | enum | ``no`` | ``no``, ``allow``, ``deny``, ``warn`` (validation modes). |
118+
+--------------------+----------+-------------+-------------------------------------------------------------+
119+
| ``TLSServerCertificate=`` | path | – | PEM CA/server cert for validation. |
120+
+--------------------+----------+-------------+-------------------------------------------------------------+
121+
| ``KeepAlive=`` | bool | ``false`` | Enable TCP keepalives (``SO_KEEPALIVE``). See :manpage:`socket(7)`. |
122+
+--------------------+----------+-------------+-------------------------------------------------------------+
123+
| ``KeepAliveTimeSec=`` | sec | ``7200`` | Idle before probes (``TCP_KEEPIDLE``). |
124+
+--------------------+----------+-------------+-------------------------------------------------------------+
125+
| ``KeepAliveIntervalSec=`` | sec | ``75`` | Probe interval (``TCP_KEEPINTVL``). |
126+
+--------------------+----------+-------------+-------------------------------------------------------------+
127+
| ``KeepAliveProbes=`` | int | ``9`` | Probes before close (``TCP_KEEPCNT``). |
128+
+--------------------+----------+-------------+-------------------------------------------------------------+
129+
| ``SendBuffer=`` | size | *system* | Send buffer (``SO_SNDBUF``; K/M/G suffixes). |
130+
+--------------------+----------+-------------+-------------------------------------------------------------+
131+
| ``NoDelay=`` | bool | ``false`` | Disable Nagle (``TCP_NODELAY``). See :manpage:`tcp(7)`. |
132+
+--------------------+----------+-------------+-------------------------------------------------------------+
133+
| ``StructuredData=``| string | – | Fixed SD-ID (e.g., for Loggly). |
134+
+--------------------+----------+-------------+-------------------------------------------------------------+
135+
| ``UseSysLogStructuredData=`` | bool | ``false`` | Extract ``SYSLOG_STRUCTURED_DATA`` from journal. |
136+
+--------------------+----------+-------------+-------------------------------------------------------------+
137+
| ``UseSysLogMsgId=``| bool | ``false`` | Extract ``SYSLOG_MSGID`` from journal. |
138+
+--------------------+----------+-------------+-------------------------------------------------------------+
139+
| ``ExcludeSyslogFacility=`` | list | – | Skip facilities (e.g., ``auth,authpriv``). |
140+
+--------------------+----------+-------------+-------------------------------------------------------------+
141+
| ``ExcludeSyslogLevel=`` | list | – | Skip levels (e.g., ``debug``). |
142+
+--------------------+----------+-------------+-------------------------------------------------------------+
143+
144+
**Facilities**: ``kern``, ``user``, ``mail``, ``daemon``, ``auth``, ``syslog``, ``lpr``, ``news``, ``uucp``, ``cron``, ``authpriv``, ``ftp``, ``ntp``, ``security``, ``console``, ``solaris-cron``, ``local0``–``local7``.
145+
146+
**Levels**: ``emerg``, ``alert``, ``crit``, ``err``, ``warning``, ``notice``, ``info``, ``debug``.
147+
148+
Examples
93149
--------
94150

95-
- Example 1. UDP Multicast::
151+
UDP Multicast
152+
^^^^^^^^^^^^^
153+
154+
.. code-block:: ini
155+
156+
[Network]
157+
Address=239.0.0.1:6000
158+
159+
Unicast UDP (RFC 3339)
160+
^^^^^^^^^^^^^^^^^^^^^
161+
162+
.. code-block:: ini
96163
97-
.. code-block:: bash
164+
[Network]
165+
Address=192.168.8.101:514
166+
LogFormat=rfc3339
98167
99-
[Network]
100-
Address=239.0.0.1:6000
168+
Custom Structured Data
169+
^^^^^^^^^^^^^^^^^^^^^
101170

102-
- Example 2. UDP::
171+
.. code-block:: ini
103172
104-
.. code-block:: bash
173+
[Network]
174+
Address=192.168.8.101:514
175+
StructuredData=[1ab456b6-90bb-6578-abcd-5b734584aaaa@41058]
105176
106-
[Network]
107-
Address=192.168.8.101:514
177+
TLS
178+
^^^
108179

109-
- Example 3. Structured Data::
180+
.. code-block:: ini
110181
111-
.. code-block:: bash
182+
[Network]
183+
Address=192.168.8.101:514
184+
Protocol=tls
185+
LogFormat=rfc5425
186+
TLSCertificateAuthMode=deny
112187
113-
[Network]
114-
Address=192.168.8.101:514
115-
StructuredData=[1ab456b6-90bb-6578-abcd-5b734584aaaa@41058]
188+
DTLS
189+
^^^^
116190

117-
- Example 4. TLS::
191+
.. code-block:: ini
118192
119-
.. code-block:: bash
193+
[Network]
194+
Address=192.168.8.101:4433
195+
Protocol=dtls
196+
TLSCertificateAuthMode=warn
120197
121-
[Network]
122-
Address=192.168.8.101:514
123-
Protocol=tls
198+
Extract Journal Metadata
199+
^^^^^^^^^^^^^^^^^^^^^^^^
124200

125-
- Example 5. DTLS::
201+
.. code-block:: ini
126202
127-
.. code-block:: bash
203+
[Network]
204+
Address=192.168.8.101:514
205+
LogFormat=rfc5424
206+
UseSysLogStructuredData=yes
207+
UseSysLogMsgId=yes
128208
129-
[Network]
130-
Address=192.168.8.101:4433
131-
Protocol=dtls
209+
TCP with Filtering
210+
^^^^^^^^^^^^^^^^^^
132211

133-
- Example 6. Custom Structured Data and Message Id::
212+
.. code-block:: ini
134213
135-
.. code-block:: bash
214+
[Network]
215+
Address=192.168.8.101:514
216+
Protocol=tcp
217+
ExcludeSyslogFacility=auth,authpriv
218+
ExcludeSyslogLevel=debug
136219
137-
[Network]
138-
Address=192.168.8.101:514
139-
#Protocol=udp
140-
LogFormat=rfc5424
141-
UseSysLogStructuredData=yes
142-
UseSysLogMsgId=yes
220+
Using Structured Data and Message IDs
221+
-------------------------------------
143222

144-
- Example 7. TCP::
223+
Tag journal entries for extraction:
145224

146-
.. code-block:: bash
225+
.. code-block:: c
147226
148-
[Network]
149-
Address=192.168.8.101:514
150-
Protocol=tcp
227+
#include <systemd/sd-journal.h>
151228
152-
- Example 8. TLS with certificate authentication mode::
229+
int main(void) {
230+
sd_journal_send(
231+
"MESSAGE=%s", "Message to process",
232+
"PRIORITY=%i", 4, // warning
233+
"SYSLOG_FACILITY=%i", 1, // user
234+
"SYSLOG_MSGID=%s", "1011",
235+
"SYSLOG_STRUCTURED_DATA=%s", R"([exampleSDID@32473 iut="3" eventSource="Application"])",
236+
NULL);
237+
return 0;
238+
}
153239
154-
.. code-block:: bash
240+
Compile: ``gcc example.c -lsystemd``.
155241

156-
[Network]
157-
Address=192.168.8.101:514
158-
Protocol=tls
159-
TLSCertificateAuthMode=warn
242+
Files
243+
-----
160244

161-
- Example 9. DTLS with certificate authentication mode::
245+
/etc/systemd/netlogd.conf
246+
Main configuration.
162247

163-
.. code-block:: bash
248+
/etc/systemd/netlogd.conf.d/*.conf
249+
Drop-in snippets.
164250
165-
[Network]
166-
Address=192.168.8.101:514
167-
Protocol=tls
168-
TLSCertificateAuthMode=deny
251+
/lib/systemd/system/systemd-netlogd.service
252+
Service unit.
169253

254+
Troubleshooting
255+
---------------
170256

171-
- Use case of UseSysLogStructuredData= and UseSysLogMsgId=::
257+
- **No forwarding**: Check ``journalctl -u systemd-netlogd``; verify network and permissions.
258+
- **TLS errors**: Use ``openssl verify -CAfile cert.pem server.crt``; set ``TLSCertificateAuthMode=allow`` for testing.
259+
- **Test setup**: Generate logs with ``logger -p user.info "Test"``; receive with ``nc -u -l 514``.
260+
- **Debug mode**: Override service: ``systemctl edit systemd-netlogd`` and add ``StandardOutput=journal+console``.
172261

173-
.. code-block:: bash
262+
See Also
263+
--------
264+
265+
:manpage:`systemd.socket(5)`, :manpage:`systemd.time(5)`, :manpage:`socket(7)`, :manpage:`tcp(7)`, :manpage:`systemd-journald(8)`
266+
267+
- RFC 5424, RFC 5425, RFC 3339, RFC 6012
268+
- Project: https://github.com/systemd/systemd-netlogd
269+
270+
Author
271+
------
272+
273+
Susant Sahani <[email protected]>
274+
275+
Colophon
276+
--------
174277

175-
sd_journal_send(
176-
"MESSAGE=%s", "Message to process",
177-
"PRIORITY=%s", "4",
178-
"SYSLOG_FACILITY=%s", "1",
179-
"SYSLOG_MSGID=%s", "1011",
180-
"SYSLOG_STRUCTURED_DATA=%s", R"([exampleSDID@32473 iut="3" eventSource="Application"])",
181-
NULL
182-
);
278+
This page is part of systemd-netlogd (version 1.4.4, October 27, 2025).

0 commit comments

Comments
 (0)