| <?xml version='1.0'?> |
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ |
| <!ENTITY % entities SYSTEM "custom-entities.ent" > |
| %entities; |
| ]> |
| <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
| |
| <refentry id="systemd-journal-remote" conditional='HAVE_MICROHTTPD' |
| xmlns:xi="http://www.w3.org/2001/XInclude"> |
| |
| <refentryinfo> |
| <title>systemd-journal-remote.service</title> |
| <productname>systemd</productname> |
| </refentryinfo> |
| |
| <refmeta> |
| <refentrytitle>systemd-journal-remote.service</refentrytitle> |
| <manvolnum>8</manvolnum> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>systemd-journal-remote.service</refname> |
| <refname>systemd-journal-remote.socket</refname> |
| <refname>systemd-journal-remote</refname> |
| <refpurpose>Receive journal messages over the network</refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <para><filename>systemd-journal-remote.service</filename></para> |
| <para><filename>systemd-journal-remote.socket</filename></para> |
| <cmdsynopsis> |
| <command>/usr/lib/systemd/systemd-journal-remote</command> |
| <arg choice="opt" rep="repeat">OPTIONS</arg> |
| <arg choice="opt" rep="norepeat">-o/--output=<replaceable>DIR</replaceable>|<replaceable>FILE</replaceable></arg> |
| <arg choice="opt" rep="repeat">SOURCES</arg> |
| </cmdsynopsis> |
| </refsynopsisdiv> |
| |
| <refsect1> |
| <title>Description</title> |
| |
| <para><command>systemd-journal-remote</command> is a command to receive serialized journal |
| events and store them to journal files. Input streams are in the |
| <ulink url="https://www.freedesktop.org/wiki/Software/systemd/export">Journal Export Format</ulink>, |
| i.e. like the output from <command>journalctl --output=export</command>. For transport over the |
| network, this serialized stream is usually carried over an HTTPS connection.</para> |
| |
| <para><filename>systemd-journal-remote.service</filename> is a system service that uses |
| <command>systemd-journal-remote</command> to listen for connections. |
| <filename>systemd-journal-remote.socket</filename> configures the network address that |
| <filename>systemd-journal-remote.service</filename> listens on. By default this is port 19532. |
| What connections are accepted and how the received data is stored can be configured through the |
| <citerefentry><refentrytitle>journal-remote.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> |
| configuration file.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Sources</title> |
| |
| <para> |
| Sources can be either "active" |
| (<command>systemd-journal-remote</command> requests and pulls |
| the data), or "passive" |
| (<command>systemd-journal-remote</command> waits for a |
| connection and then receives events pushed by the other side). |
| </para> |
| |
| <para> |
| <command>systemd-journal-remote</command> can read more than one |
| event stream at a time. They will be interleaved in the output |
| file. In case of "active" connections, each "source" is one |
| stream, and in case of "passive" connections, each connection can |
| result in a separate stream. Sockets can be configured in |
| "accept" mode (i.e. only one connection), or "listen" mode (i.e. |
| multiple connections, each resulting in a stream). |
| </para> |
| |
| <para> |
| When there are no more connections, and no more can be created |
| (there are no listening sockets), then |
| <command>systemd-journal-remote</command> will exit. |
| </para> |
| |
| <para>Active sources can be specified in the following |
| ways:</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><arg choice="opt" rep="repeat">SOURCES</arg></term> |
| |
| <listitem><para>When <option>-</option> is given as a |
| positional argument, events will be read from standard input. |
| Other positional arguments will be treated as filenames |
| to open and read from.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--url=<replaceable>ADDRESS</replaceable></option></term> |
| |
| <listitem><para>With the |
| <option>--url=<replaceable>ADDRESS</replaceable></option> option, |
| events will be retrieved using HTTP from |
| <replaceable>ADDRESS</replaceable>. This URL should refer to the |
| root of a remote |
| <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
| instance, e.g. http://some.host:19531/ or |
| https://some.host:19531/.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--getter='<replaceable>PROG</replaceable> <arg choice="opt" rep="repeat">OPTIONS</arg>'</option></term> |
| |
| <listitem><para>Program to invoke to retrieve data. The journal |
| event stream must be generated on standard output.</para> |
| |
| <para>Examples:</para> |
| |
| <programlisting>--getter='curl "-HAccept: application/vnd.fdo.journal" https://some.host:19531/'</programlisting> |
| |
| <programlisting>--getter='wget --header="Accept: application/vnd.fdo.journal" -O- https://some.host:19531/'</programlisting> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| |
| <para>Passive sources can be specified in the following |
| ways:</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><option>--listen-raw=<replaceable>ADDRESS</replaceable></option></term> |
| |
| <listitem><para><replaceable>ADDRESS</replaceable> must be an |
| address suitable for <option>ListenStream=</option> (cf. |
| <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>). |
| <command>systemd-journal-remote</command> will listen on this |
| socket for connections. Each connection is expected to be a |
| stream of journal events.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--listen-http=<replaceable>ADDRESS</replaceable></option></term> |
| <term><option>--listen-https=<replaceable>ADDRESS</replaceable></option></term> |
| |
| <listitem><para><replaceable>ADDRESS</replaceable> must be |
| either a negative integer, in which case it will be |
| interpreted as the (negated) file descriptor number, or an |
| address suitable for <option>ListenStream=</option> (c.f. |
| <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>). |
| In the first case, the server listens on port 19532 by default, |
| and the matching file descriptor must be inherited through |
| <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>. |
| In the second case, an HTTP or HTTPS server will be spawned on |
| this port, respectively for <option>--listen-http=</option> and |
| <option>--listen-https=</option>. Currently, only POST requests |
| to <filename>/upload</filename> with <literal>Content-Type: |
| application/vnd.fdo.journal</literal> are supported.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><varname>$LISTEN_FDS</varname></term> |
| |
| <listitem><para><command>systemd-journal-remote</command> |
| supports the |
| <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname> |
| protocol. Open sockets inherited through socket activation |
| behave like those opened with <option>--listen-raw=</option> |
| described above, unless they are specified as an argument in |
| <option>--listen-http=-<replaceable>n</replaceable></option> |
| or |
| <option>--listen-https=-<replaceable>n</replaceable></option> |
| above. In the latter case, an HTTP or HTTPS server will be |
| spawned using this descriptor and connections must be made |
| over the HTTP protocol.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--key=</option></term> |
| |
| <listitem><para> Takes a path to a SSL key file in PEM format. Defaults to |
| <filename>&CERTIFICATE_ROOT;/private/journal-remote.pem</filename>. This option can be used with |
| <option>--listen-https=</option>. If the path refers to an <constant>AF_UNIX</constant> stream socket |
| in the file system a connection is made to it and the key read from it.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--cert=</option></term> |
| |
| <listitem><para> Takes a path to a SSL certificate file in PEM format. Defaults to |
| <filename>&CERTIFICATE_ROOT;/certs/journal-remote.pem</filename>. This option can be used with |
| <option>--listen-https=</option>. If the path refers to an <constant>AF_UNIX</constant> stream socket |
| in the file system a connection is made to it and the certificate read from it.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--trust=</option></term> |
| |
| <listitem><para> Takes a path to a SSL CA certificate file in PEM format, or <option>all</option>. If |
| <option>all</option> is set, then certificate checking will be disabled. Defaults to |
| <filename>&CERTIFICATE_ROOT;/ca/trusted.pem</filename>. This option can be used with |
| <option>--listen-https=</option>. If the path refers to an <constant>AF_UNIX</constant> stream socket |
| in the file system a connection is made to it and the certificate read from it.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--gnutls-log=</option></term> |
| |
| <listitem><para> |
| Takes a comma separated list of gnutls logging categories. |
| This option can be used with <option>--listen-http=</option> or |
| <option>--listen-https=</option>. |
| </para></listitem> |
| </varlistentry> |
| |
| </variablelist> |
| </refsect1> |
| |
| <refsect1> |
| <title>Sinks</title> |
| |
| <para>The location of the output journal can be specified |
| with <option>-o</option> or <option>--output=</option>. |
| </para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><option>--output=<replaceable>FILE</replaceable></option></term> |
| |
| <listitem><para>Will write to this journal file. The filename |
| must end with <filename>.journal</filename>. The file will be |
| created if it does not exist. If necessary (journal file full, |
| or corrupted), the file will be renamed following normal |
| journald rules and a new journal file will be created in its |
| stead.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--output=<replaceable>DIR</replaceable></option></term> |
| |
| <listitem><para>Will create journal files underneath directory |
| <replaceable>DIR</replaceable>. The directory must exist. If |
| necessary (journal files over size, or corrupted), journal |
| files will be rotated following normal journald rules. Names |
| of files underneath <replaceable>DIR</replaceable> will be |
| generated using the rules described below.</para></listitem> |
| </varlistentry> |
| </variablelist> |
| |
| <para>If <option>--output=</option> is not used, the output |
| directory <filename>/var/log/journal/remote/</filename> will be |
| used. In case the output file is not specified, journal files |
| will be created underneath the selected directory. Files will be |
| called |
| <filename>remote-<replaceable>hostname</replaceable>.journal</filename>, |
| where the <replaceable>hostname</replaceable> part is the |
| escaped hostname of the source endpoint of the connection, or the |
| numerical address if the hostname cannot be determined.</para> |
| |
| <para>In the case that "active" sources are given by the positional |
| arguments or <option>--getter=</option> option, the output file name |
| must always be given explicitly.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Options</title> |
| |
| <para>The following options are understood:</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><option>--split-mode</option></term> |
| |
| <listitem><para>One of <constant>none</constant> or |
| <constant>host</constant>. For the first, only one output |
| journal file is used. For the latter, a separate output file |
| is used, based on the hostname of the other endpoint of a |
| connection.</para> |
| |
| <para>In the case that "active" sources are given by the positional |
| arguments or <option>--getter=</option> option, the output file name must |
| always be given explicitly and only <constant>none</constant> |
| is allowed.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--compress</option> [<replaceable>BOOL</replaceable>]</term> |
| |
| <listitem><para>If this is set to <literal>yes</literal> then compress |
| the data in the journal using XZ. The default is <literal>yes</literal>. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--seal</option> [<replaceable>BOOL</replaceable>]</term> |
| |
| <listitem><para>If this is set to <literal>yes</literal> then |
| periodically sign the data in the journal using Forward Secure Sealing. |
| The default is <literal>no</literal>.</para></listitem> |
| </varlistentry> |
| |
| <xi:include href="standard-options.xml" xpointer="help" /> |
| <xi:include href="standard-options.xml" xpointer="version" /> |
| </variablelist> |
| </refsect1> |
| |
| <refsect1> |
| <title>Examples</title> |
| <para>Copy local journal events to a different journal directory: |
| <programlisting> |
| journalctl -o export | systemd-journal-remote -o /tmp/dir/foo.journal - |
| </programlisting> |
| </para> |
| |
| <para>Retrieve all available events from a remote |
| <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
| instance and store them in |
| <filename>/var/log/journal/remote/remote-some.host.journal</filename>: |
| <programlisting> |
| systemd-journal-remote --url http://some.host:19531/ |
| </programlisting> |
| </para> |
| |
| <para>Retrieve current boot events and wait for new events from a remote |
| <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
| instance, and store them in |
| <filename>/var/log/journal/remote/remote-some.host.journal</filename>: |
| <programlisting> |
| systemd-journal-remote --url http://some.host:19531/entries?boot&follow |
| </programlisting> |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>See Also</title> |
| <para> |
| <citerefentry><refentrytitle>journal-remote.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemd-journal-gatewayd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemd-journal-upload.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
| </para> |
| </refsect1> |
| </refentry> |