systemd-netlogd

Lightweight, network-aware daemon for forwarding systemd journal logs to remote syslog servers

Forward your systemd journal to centralized logging infrastructure with zero local buffering, automatic network detection, and secure transport options (UDP, TCP, TLS, DTLS).

⚡ Quick Start

# Install (Ubuntu/Debian)
sudo apt install systemd-netlogd

# Or build from source
git clone https://github.com/systemd/systemd-netlogd.git
cd systemd-netlogd && make && sudo make install

# Configure
sudo tee /etc/systemd/netlogd.conf <<EOF
[Network]
Address=logs.example.com:514
Protocol=tcp
EOF

# Create system user
sudo useradd -r -d / -s /usr/sbin/nologin -g systemd-journal systemd-journal-netlog

# Start
sudo systemctl enable --now systemd-netlogd

That's it! Your logs are now being forwarded. View status with:

journalctl -u systemd-netlogd -f

🎯 Why systemd-netlogd?

✅ What You Get

Zero disk buffering - No local storage impact
Network-aware - Auto-start/pause with network
Secure by default - TLS/DTLS encryption support
Battle-tested - Production-ready since 2016
Resource efficient - ~2-5 MB memory, <1% CPU
Native integration - Direct systemd journal access

❌ What You Don't Need

No rsyslog/syslog-ng complexity
No local log buffering/queuing
No heavy dependencies
No manual journal export setup
No root privileges required
No configuration headaches

🚀 Key Features

🌐 Network-Aware: Automatically detects network state changes via sd-network
⚡ Zero Buffering: Sequential journal reading without local caching
🔒 Secure Transport: UDP, TCP, TLS (RFC 5425), DTLS (RFC 6012)
📋 Standard Formats: RFC 5424 (recommended), RFC 3339 (legacy BSD syslog)
🎯 Smart Filtering: Exclude sensitive facilities (auth/authpriv) and log levels
📦 Namespace Support: Forward from specific namespaces or aggregate all
🛡️ Hardened: Runs as unprivileged systemd-journal-netlog user with restricted capabilities
🔄 Fault Tolerant: Automatic reconnection with cursor persistence ensures no message loss

💡 Use Cases

✓ Centralized logging for distributed systems     ✓ Security monitoring & SIEM integration
✓ Cloud log aggregation (AWS, Azure, GCP)         ✓ Compliance & audit log forwarding
✓ Edge device telemetry collection                ✓ Multi-region log consolidation
✓ Container/Kubernetes cluster logging            ✓ IoT fleet management

📦 Installation

Package Installation (Recommended)

Ubuntu/Debian	`sudo apt install systemd-netlogd`
Fedora	Search COPR repositories
Arch Linux	AUR: `yay -S systemd-netlogd-git`

Build from Source

Click to expand build instructions

Prerequisites: systemd v230+ (v255+ recommended)

Install dependencies:

# Debian/Ubuntu
sudo apt install build-essential meson gperf libcap-dev libsystemd-dev libssl-dev libcmocka-dev

# Fedora/RHEL
sudo dnf install gcc meson gperf libcap-devel systemd-devel openssl-devel libcmocka-devel

Build and install:

git clone https://github.com/systemd/systemd-netlogd.git
cd systemd-netlogd
make                    # or: meson setup build && meson compile -C build
sudo make install       # or: sudo meson install -C build

Create system user:

sudo useradd -r -d / -s /usr/sbin/nologin -g systemd-journal systemd-journal-netlog

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now systemd-netlogd

⚙️ Configuration

Quick Configuration

File: /etc/systemd/netlogd.conf (or /etc/systemd/netlogd.conf.d/*.conf for drop-ins)

Reload: sudo systemctl reload systemd-netlogd

Common Configuration Options

Option	Description	Default
`Address=`	Destination server (IP:port or multicast)	Required
`Protocol=`	Transport: `udp`, `tcp`, `tls`, `dtls`	`udp`
`LogFormat=`	Format: `rfc5424`, `rfc5425`, `rfc3339`	`rfc5424`
`ConnectionRetrySec=`	Retry interval on failure	`30s`
`TLSCertificateAuthMode=`	TLS validation: `deny`, `warn`, `allow`, `no`	`deny`
`TLSServerCertificate=`	Path to CA certificate PEM file	System CA
`ExcludeSyslogFacility=`	Filter out facilities (e.g., `auth authpriv`)	None
`ExcludeSyslogLevel=`	Filter out levels (e.g., `debug info`)	None

📋 View all configuration options

Option	Description	Default
`Address=`	Destination (IP:port or multicast group)	Required
`Protocol=`	`udp`, `tcp`, `tls`, `dtls`	`udp`
`LogFormat=`	`rfc5424`, `rfc5425` (TLS), `rfc3339` (legacy)	`rfc5424`
`Directory=`	Custom journal directory path	System default
`Namespace=`	Journal namespace: `*` (all), `+id` (id+default), `id`	Default
`ConnectionRetrySec=`	Reconnect delay after failure	`30s`
`TLSCertificateAuthMode=`	Certificate validation mode	`deny`
`TLSServerCertificate=`	CA/server certificate PEM path	System CA store
`KeepAlive=`	Enable TCP keepalive probes	`false`
`KeepAliveTimeSec=`	Keepalive idle timeout	`7200`
`KeepAliveIntervalSec=`	Keepalive probe interval	`75`
`KeepAliveProbes=`	Keepalive probe count	`9`
`SendBuffer=`	Socket send buffer size (bytes, K, M, G)	System default
`NoDelay=`	Disable Nagle's algorithm (lower latency)	`false`
`StructuredData=`	Static structured data `[SD-ID@PEN ...]`	None
`UseSysLogStructuredData=`	Extract `SYSLOG_STRUCTURED_DATA` from journal	`false`
`UseSysLogMsgId=`	Extract `SYSLOG_MSGID` from journal	`false`
`ExcludeSyslogFacility=`	Space-separated facility list	None
`ExcludeSyslogLevel=`	Space-separated level list	None

Facilities: kern, user, mail, daemon, auth, syslog, lpr, news, uucp, cron, authpriv, ftp, ntp, security, console, solaris-cron, local0-7

Levels: emerg, alert, crit, err, warning, notice, info, debug

📝 Configuration Examples

Basic UDP

[Network]
Address=192.168.1.100:514

Production TLS (Recommended)

[Network]
Address=logs.example.com:6514
Protocol=tls
LogFormat=rfc5425
TLSCertificateAuthMode=deny
TLSServerCertificate=/etc/pki/tls/certs/ca-bundle.crt
KeepAlive=yes
NoDelay=yes
ExcludeSyslogFacility=auth authpriv

Cloud Service (Papertrail)

[Network]
Address=logs7.papertrailapp.com:12345
Protocol=tls

High-Performance Local Network

[Network]
Address=192.168.1.100:514
Protocol=udp
ExcludeSyslogLevel=debug info
ConnectionRetrySec=5

With Structured Data

[Network]
Address=192.168.1.100:514
Protocol=tcp
LogFormat=rfc5424
StructuredData=[app@12345 env="production" region="us-east"]

📁 More examples: See examples/ directory for 10+ production-ready configurations

🔧 Advanced Usage

Tag Journal Entries with Structured Data

Click to see C example

#include <systemd/sd-journal.h>

int main() {
    sd_journal_send(
        "MESSAGE=User login successful",
        "PRIORITY=6",                    // info
        "SYSLOG_FACILITY=10",           // authpriv
        "SYSLOG_MSGID=LOGIN001",
        "SYSLOG_STRUCTURED_DATA=[auth@12345 user=\"alice\" ip=\"1.2.3.4\"]",
        NULL
    );
    return 0;
}

Compile: gcc example.c -lsystemd -o example && ./example

Configure netlogd to extract structured data:

[Network]
Address=192.168.1.100:514
LogFormat=rfc5424
UseSysLogStructuredData=yes
UseSysLogMsgId=yes

Testing and Validation

# Start a test receiver
nc -ul 514                    # UDP
nc -l 514                     # TCP

# Generate test logs
logger -p user.info "Test message"
logger -p user.warning "Warning test"

# Monitor systemd-netlogd
journalctl -u systemd-netlogd -f

# Enable debug logging
sudo systemctl edit systemd-netlogd
# Add: Environment=SYSTEMD_LOG_LEVEL=debug

# Test TLS connectivity
openssl s_client -connect server:6514 -CAfile /path/to/ca.pem

🔒 Security

systemd-netlogd runs with minimal privileges:

Dedicated systemd-journal-netlog system user (not root)
Capability restrictions via systemd hardening
Filesystem isolation and protection

Best Practices:

# ✅ DO: Use TLS for remote logging
Protocol=tls
TLSCertificateAuthMode=deny

# ✅ DO: Filter sensitive logs
ExcludeSyslogFacility=auth authpriv

# ✅ DO: Use strong certificate validation
TLSServerCertificate=/etc/pki/tls/certs/ca-bundle.crt

# ❌ DON'T: Use UDP/TCP over the internet (unencrypted)
# ❌ DON'T: Disable certificate validation in production

Audit security posture:

sudo systemd-analyze security systemd-netlogd.service

🐛 Troubleshooting

❓ No logs being forwarded

Check service status:

sudo systemctl status systemd-netlogd
journalctl -u systemd-netlogd -n 50

Verify configuration:
```
cat /etc/systemd/netlogd.conf
```

Test network connectivity:

nc -vz remote-server 514    # TCP
ping remote-server

Check user exists:
```
id systemd-journal-netlog
```

🔐 TLS connection failures

Test TLS manually:

openssl s_client -connect server:6514 -CAfile /path/to/ca.pem

Check certificate validity:

openssl x509 -in /path/to/ca.pem -noout -dates

Try relaxed validation (testing only):
```
TLSCertificateAuthMode=warn
```

View SSL errors:

journalctl -u systemd-netlogd | grep -i ssl

🚫 Connection refused

Check firewall on remote server
Verify remote syslog server is running:
```
sudo netstat -tuln | grep 514
```
Test with netcat as simple receiver:
```
nc -ul 514  # UDP
nc -l 514   # TCP
```

⚡ Performance issues / lag

Check network latency: ping remote-server
Use UDP for highest throughput
Filter debug messages: ExcludeSyslogLevel=debug info
Increase send buffer: SendBuffer=262144
Check dropped packets: netstat -su | grep drop

💡 Quick fixes:

# Generate test log
logger -p user.info "Test from systemd-netlogd"

# Enable debug mode
sudo kill -SIGUSR1 $(pidof systemd-netlogd)

# Reset state (start from scratch)
sudo systemctl stop systemd-netlogd
sudo rm /var/lib/systemd-netlogd/state
sudo systemctl start systemd-netlogd

📚 Documentation

📖 User Guides

README.md (this file)
FAQ.md - Common questions
examples/ - 10+ configs
Man Page - Full reference

🔧 Developer Guides

ARCHITECTURE.md - Internal design
CONTRIBUTING.md - Dev setup
TESTING.md - Test guide

📦 Example Configs

🤝 Contributing

We welcome contributions!

Quick Start:

🍴 Fork the repository
🌿 Create feature branch: git checkout -b feature/amazing-feature
✅ Add tests for new functionality
💬 Commit with clear messages
📫 Submit a pull request

Resources:

📖 CONTRIBUTING.md - Full contribution guide
🏗️ ARCHITECTURE.md - Understand the codebase
🧪 TESTING.md - Testing guide

Development:

# Clone and setup
git clone https://github.com/systemd/systemd-netlogd.git
cd systemd-netlogd
make

# Run tests
meson test -C build -v

# Build documentation
make -C doc

💬 Getting Help

📖 FAQ

50+ questions answered

🐛 Issues

Report bugs & request features

💬 Discussions

Ask questions & share tips

📚 Man Page

Complete reference

Before asking for help:

✅ Check the FAQ
✅ Search existing issues
✅ Try troubleshooting steps above
✅ Enable debug logging: Environment=SYSTEMD_LOG_LEVEL=debug

📄 License

LGPL-2.1-or-later — Same license as systemd

See LICENSE file for details.

🌟 Acknowledgments

Author: Susant Sahani
Contributors: See all contributors
Project: Part of the systemd ecosystem

⭐ If you find systemd-netlogd useful, please star the repository!

Documentation • Examples • FAQ • Contributing

Name		Name	Last commit message	Last commit date
Latest commit History 352 Commits
.github/workflows		.github/workflows
conf		conf
doc		doc
examples		examples
src		src
tests		tests
units		units
.ctags		.ctags
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.vimrc		.vimrc
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
FAQ.md		FAQ.md
LICENSE.GPL2		LICENSE.GPL2
LICENSE.LGPL2.1		LICENSE.LGPL2.1
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
TESTING.md		TESTING.md
TODO		TODO
meson.build		meson.build
meson_options.txt		meson_options.txt
systemd-netlogd.spec		systemd-netlogd.spec

License

systemd/systemd-netlogd

Folders and files

Latest commit

History

Repository files navigation

systemd-netlogd

⚡ Quick Start

🎯 Why systemd-netlogd?

✅ What You Get

❌ What You Don't Need

🚀 Key Features

💡 Use Cases

📦 Installation

Package Installation (Recommended)

Build from Source

⚙️ Configuration

Quick Configuration

Common Configuration Options

📝 Configuration Examples

Basic UDP

Production TLS (Recommended)

Cloud Service (Papertrail)

High-Performance Local Network

With Structured Data

🔧 Advanced Usage

Tag Journal Entries with Structured Data

Testing and Validation

🔒 Security

🐛 Troubleshooting

📚 Documentation

📖 User Guides

🔧 Developer Guides

📦 Example Configs

🤝 Contributing

💬 Getting Help

📖 FAQ

🐛 Issues

💬 Discussions

📚 Man Page

📄 License

🌟 Acknowledgments

⭐ If you find systemd-netlogd useful, please star the repository!

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 10

Packages 0

Uh oh!

Contributors 10

Uh oh!

Languages

Packages