diff options
Diffstat (limited to 'man/systemd-journal-remote.service.xml')
| -rw-r--r-- | man/systemd-journal-remote.service.xml | 378 |
1 files changed, 378 insertions, 0 deletions
diff --git a/man/systemd-journal-remote.service.xml b/man/systemd-journal-remote.service.xml new file mode 100644 index 0000000..aa96e52 --- /dev/null +++ b/man/systemd-journal-remote.service.xml @@ -0,0 +1,378 @@ +<?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://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format">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> + + <xi:include href="version-info.xml" xpointer="v239"/></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> + + <xi:include href="version-info.xml" xpointer="v239"/></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> + + <xi:include href="version-info.xml" xpointer="v239"/> + </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> + + <xi:include href="version-info.xml" xpointer="v239"/> + </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> + + <xi:include href="version-info.xml" xpointer="v239"/> + </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> + + <xi:include href="version-info.xml" xpointer="v239"/> + </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> + + <xi:include href="version-info.xml" xpointer="v239"/></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> + + <xi:include href="version-info.xml" xpointer="v239"/></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> + + <xi:include href="version-info.xml" xpointer="v239"/></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> + + <xi:include href="version-info.xml" xpointer="v239"/></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>-o <replaceable>FILE</replaceable></option></term> + <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> + + <xi:include href="version-info.xml" xpointer="v239"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>-o <replaceable>DIR</replaceable></option></term> + <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> + + <xi:include href="version-info.xml" xpointer="v239"/></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> + + <xi:include href="version-info.xml" xpointer="v239"/></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> + + <xi:include href="version-info.xml" xpointer="v239"/></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> + + <xi:include href="version-info.xml" xpointer="v239"/></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> |