man: update references to systemd-journal-{remote,upload}

Fixes #8920 and #8921.

1 files changed, 365 insertions, 0 deletions

diff --git a/man/systemd-journal-remote.service.xml b/man/systemd-journal-remote.service.xml
new file mode 100644
index 0000000000..7f93f9fe7b
--- /dev/null
+++ b/man/systemd-journal-remote.service.xml
@@ -0,0 +1,365 @@
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//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+
+
+  This file is part of systemd.
+
+  Copyright 2012 Zbigniew Jędrzejewski-Szmek
+-->
+
+<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>
+
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Zbigniew</firstname>
+        <surname>Jędrzejewski-Szmek</surname>
+        <email>zbyszek@in.waw.pl</email>
+      </author>
+    </authorgroup>
+  </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>
+      <filename>systemd-journal-remote</filename> is a command to
+      receive serialized journal events and store them to the journal.
+      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>
+  </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, 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>.
+        </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>.
+        </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>.
+        </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&amp;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>