systemd/man/systemd-journal-remote.xml
Dan Dedrick 6f157e4e4f journal-remote: fix up misleading man page
The --no-seal and --no-compress options were dropped and replaced with
boolean functionality. This syncs the man page with the code.
2016-10-10 15:11:01 -04:00

325 lines
13 KiB
XML

<?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">
<!--
This file is part of systemd.
Copyright 2012 Zbigniew Jędrzejewski-Szmek
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="systemd-journal-remote" conditional='HAVE_MICROHTTPD'
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>systemd-journal-remote</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</refentrytitle>
<manvolnum>8</manvolnum>
</refmeta>
<refnamediv>
<refname>systemd-journal-remote</refname>
<refpurpose>Receive journal messages over the network</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>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="http://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>
<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>
</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>
</variablelist>
</refsect1>
<refsect1>
<title>Sinks</title>
<para>The location of the output journal can be specified
with <option>-o</option> or <option>--output=</option>. For "active"
sources, this option is required.
</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 case of "active" sources, 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 case of "active" sources, 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>
<varlistentry>
<term><option>--getter=<replaceable>PROG --option1 --option2</replaceable></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>
<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 -
</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>systemd-journal-upload</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-journal-gatewayd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
<citerefentry><refentrytitle>journal-remote.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>