Remote Journal Logging
Summary
Systemd journal can be configured to forward events to a remote server. Entries are forwarded including full metadata, and are stored in normal journal files, identically to locally generated logs. This can be used as an alternative or in addition to existing log forwarding solutions.
Owner
- Name: Zbigniew Jędrzejewski-Szmek
- Email: zbyszek@in.waw.pl
- Release notes owner:
Current status
- Targeted release: Fedora 21
- Last updated: 2014/03/31
- Tracker bug: <will be assigned by the Wrangler>
The implementation part is mostly done, but integration issues remain. See below.
Detailed Description
Systemd's journal currently provides a replacement for most functionality offered by traditional syslog daemons, with two notable exceptions: arbitrary filtering of messages and forwarding of messages over the network. This Change targets the latter.
The high-level goal is to have a mechanism where journal logging can be extended to keep a copy of logs on a remote server, without requiring any maintenance, done fairly efficiently and in a secure way.
Two new daemons are added as part of the systemd package:
- on the receiver side systemd-journal-remote accepts messages in the Journal Export Format. The export format is a simple serialization of journal entries, supporting both text and binary fields. This means that the messages are transferred intact, apart from the "cursors", which specify the location in the journal file. Received entries are stored in local journal files underneath /var/log/journal. Those files are subject to normal journald rules for rotation, and the older ones will be removed as necessary to stay within disk usage limits. Once entries have been written to the journal file, they can be read using journalctl and the journal APIs, and are available to all clients, e.g. Gnome Logs.
- on the sender side systemd-journal-upload is a journal client, which exports all available journal messages and uploads them over the network. The (local) cursor of the last message successfully forwarded is stored on disk, so when systemd-journal-upload is restarted (possibly after a reboot of the machine), it will send all recent messages found in the journal and then new ones as they arrive.
The communication between the two daemons is done over standard HTTPS, following rather simple rules, so it is possible to create alternate implementations without much work. For example, curl can be easily used to upload journal entries from a text file containing entries in the export format. Basically, the data are sent in an HTTP POST to /upload with Content-Type: application/vnd.fdo.journal. When doing "live" forwarding, the size of the transfer cannot be known in advance, so Transfer-Encoding: chunked is used. All communication is encrypted, and the identity of both sides is verified by checking for appropriate signatures on the certificates.
Benefit to Fedora
This new functionality closes an existing gap in the journal functionality and adds an alternative way of forwarding logs for remote storage. This can be used instead of or together with a local rsyslog instance. An advantage compared to using rsyslog (or another syslog implementation) is that native journal format is used throughout, avoiding any loss of fidelity.
Since this is new software, it has not been thoroughly tested and might not be as reliable as existing solutions.
Scope
- Proposal owners:
The code in systemd for systemd-journal-remote and systemd-journal-upload will have to be added. The first is done, and has already been released in the latest Rawhide systemd package. The second is mostly done, and will be submitted upstream soon. Necessary units will have to be created, and a location with suitable permissions will have to be created so that systemd-journal-remote can run unprivileged. This means that systemd-journal-remote should probably be packaged as a separate subpackage, similarly to systemd-journal-gatewayd. systemd-journal-upload uses libcurl, and thus should be also packaged as a separate subpackage to avoid introducing a new dependency for systemd.
Suitable defaults for timeouts for transfers and maximum accepted entry sizes have to be chosen.
A port will have to be picked: systemd-journal-gatewayd uses 19531, so systemd-journal-remote should probably use 19532.
Two new users will have to be created when the packages are installed.
- Other developers: N/A (not a System Wide Change)
- Release engineering: N/A (not a System Wide Change)
- Policies and guidelines: N/A (not a System Wide Change)
Upgrade/compatibility impact
This is entirely new functionality, and upgrades are not an issue. systemd-journal-upload may be backported to enable uploading from older Fedora installations, but this is not part of this Change.
How To Test
To enable receiving of messages, creating the certificates, creating a hole in the firewall, and 'systemctl enable systemd-journal-remote && systemctl start systemd-journal-remote' should be enough. To enable uploading of messages, creating the certificates and configuring the upload URL and 'systemctl enable systemd-journal-upload && systemctl start systemd-journal-upload' should be enough.
- Test basic message forwarding over HTTPS (may be done on a single machine too):
1. Generate a CA certificate and two certificates with appropriate Common Name (localhost in case of doing tests on a single machine). Install them in /etc/pki/tls.
2. Start systemd-journal-remote.service
3. Start systemd-journal-uploader.service
4. Check that messages have been forwarded: journalctl -D /var/log/journal/remote
5. Generate some local messages (e.g. with logger) and verify that they appear in the output of journalctl command shown above.
6. Restart systemd-journal-uploader.service, and check that messages are not duplicated and are still being forwarded successfully.
7. Verify that being in the 'wheel' or 'systemd-journal' groups is necessary and sufficient to read forwareded journals for otherwise unprivileged users.
- Enable both services permanently, and verify that after a reboot, they are both started, and the forwarded messages in /var/log/journal/remote are indentical to the original ones.
- Check rotation and disk space limits:
1. Configure disk usage limits for systemd-journal-remote to something smaller than the defaults (or simply use an almost filled up filesystem :))
2. Run a log generator (a Python script is planned as a part of systemd testing infrastructure), uploading to systemd-journal-remote
3. Verify that logs files are rotated properly and configured limits are obeyed.
- Check behaviour when systemd-journal-upload is "broken"
1. Stop the uploader and the sender.
2. Start the uploader.
3. Verify that it attempts to connect a few times and finally is shown as failed by systemctl.
4. Disable the watchdog on systemd-journal-remote.service by adding a config snippet.
5. Start the receiver and the uploader
6. Pause the receiver with -SIGSTOP at some arbitrary time
7. Generate some messages so the uploader tries to send stuff
8. Verify that the uploader times out and is shown as failed after a timeout.
9. Restart both
10. Verify that all messages have been forwarded, and journalctl output is identical for "local" and "remote" storage.
The details, including specific commands, will be filled in when everything is implemented. I also expect to prune the test cases to something more managable. Right now this extensive testing checklist should simply highlight what is expected to work.
User Experience
N/A (not a System Wide Change)
Dependencies
N/A (not a System Wide Change)
Contingency Plan
- Contingency mechanism: do not ship the two subpackages
- Contingency deadline: N/A (not a System Wide Change)
- Blocks release? no
- Blocks product? no
Documentation
http://www.freedesktop.org/software/systemd/man/systemd-journal-remote.html
Release Notes
Journal messages can be forwarded to remote storage, without using a syslog daemon. This functionality is available through the systemd-journal-remote and systemd-journal-upload packages.