347 lines
15 KiB
XML
347 lines
15 KiB
XML
<?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 secret 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>
|