Journald
========

What is "journald"?
~~~~~~~~~~~~~~~~~~~

Journald is a system for collecting logs and data from devices running "systemd".  Many distributions
have moved away standard syslog services in favor of "journald".  The concept is to replace standard
"text" base logging for a more "database" binary logging approach.  

While this method has advantages,  there are several limitations.  Software like "Sagan" doesn't natively
read "journald" files.  Journald also lacks the ability to send logs to a remote host.  Journald relies on
services like ``syslog-ng`` and ``rsyslog`` to send logs to a remote host.  While there are some methods
to send logs to a remote host via Journald,  most are not mature and more of a "proof of concept"
than a solution.   This makes using a service like ``syslog-ng`` or ``rsyslog`` the best method to send 
logs generated by Journald. 


Analyzing journald logs locally
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Using the "Journald" command ``journalctl``, it is possible to create a JSON stream representing Journald
data.  Using Sagan built in JSON processing,  it is possible to analyze this data.   As Journald writes 
log data,  the ``journalctl`` converts it to JSON and sends it to ``stdout``.   This can be redirected to 
a named pipe (FIFO).   For example,  ``journalctl -f -o json > /var/sagan/fifo/journald.fifo`` will direct
log data to a named pipe which Sagan can read.   Within the Sagan configuration file,  you would want to
set the following options::

    input-type: json                       # pipe or json
    json-map: "$RULE_PATH/json-input.map"  # mapping file if input-type: json
    json-software: journald                # by "software" type. 

Analyzing journald logs remotely
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In situations where ``syslog-ng`` or ``rsyslog`` is not an option,  you can using ``journalctl`` to send
logs to a remote host in raw JSON.  For example, ``journalctl -f -o json | nc 192.168.1.1 1514``.  This
would using ``netcat`` to send logs to 192.168.1.1 on port 1514.  Your receiver would need to be configuration
to accepts incoming connection and date in a __raw__ format (non-syslog).   Sagan could then be used 
on the receiving side to analyze data from various devices.   You would likely want to wrap the "journalctl"
in a script and infinite loop so ``journalctl`` will automatically restart if the TCP log connection is broken.

