systemd-journal-remote.xml revision 3802a3d3d7af51ddff31943d5514382f01265770
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannThis file is part of systemd.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannCopyright 2012 Zbigniew Jędrzejewski-Szmek
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannsystemd is free software; you can redistribute it and/or modify it
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannunder the terms of the GNU Lesser General Public License as published by
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannthe Free Software Foundation; either version 2.1 of the License, or
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann(at your option) any later version.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannsystemd is distributed in the hope that it will be useful, but
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannWITHOUT ANY WARRANTY; without even the implied warranty of
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannLesser General Public License for more details.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel HoltmannYou should have received a copy of the GNU Lesser General Public License
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannalong with systemd; If not, see <http://www.gnu.org/licenses/>.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann<refentry id="systemd-journal-remote" conditional='HAVE_MICROHTTPD'
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <refentryinfo>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <authorgroup>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </authorgroup>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </refentryinfo>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <refentrytitle>systemd-journal-remote</refentrytitle>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <refpurpose>Receive journal messages over the network</refpurpose>
5476ad087c0f2d45ab0dab1bab9ef3e9d70418bcMarcel Holtmann </refnamediv>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <refsynopsisdiv>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <cmdsynopsis>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <arg choice="opt" rep="repeat">OPTIONS</arg>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <arg choice="opt" rep="norepeat">-o/--output=<replaceable>DIR</replaceable>|<replaceable>FILE</replaceable></arg>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <arg choice="opt" rep="repeat">SOURCES</arg>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </cmdsynopsis>
5476ad087c0f2d45ab0dab1bab9ef3e9d70418bcMarcel Holtmann </refsynopsisdiv>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <filename>systemd-journal-remote</filename> is a command to
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann receive serialized journal events and store them to the journal.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann Input streams are in the
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <ulink url="http://www.freedesktop.org/wiki/Software/systemd/export">
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann Journal Export Format
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann i.e. like the output from
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <command>journalctl --output=export</command>. For transport over
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann the network, this serialized stream is usually carried over an
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann HTTPS connection.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann Sources can be either "active"
5476ad087c0f2d45ab0dab1bab9ef3e9d70418bcMarcel Holtmann (<command>systemd-journal-remote</command> requests and pulls
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann the data), or "passive"
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann (<command>systemd-journal-remote</command> waits for a
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann connection and then receives events pushed by the other side).
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <command>systemd-journal-remote</command> can read more than one
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann event stream at a time. They will be interleaved in the output
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann file. In case of "active" connections, each "source" is one
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann stream, and in case of "passive" connections, each connection can
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann result in a separate stream. Sockets can be configured in
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann "accept" mode (i.e. only one connection), or "listen" mode (i.e.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann multiple connections, each resulting in a stream).
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann When there are no more connections, and no more can be created
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann (there are no listening sockets), then
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <command>systemd-journal-remote</command> will exit.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <para>Active sources can be specified in the following
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <variablelist>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <varlistentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <listitem><para>When <option>-</option> is given as a
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann positional argument, events will be read from standard input.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann Other positional arguments will be treated as filenames
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </varlistentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <varlistentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <term><option>--url=<replaceable>ADDRESS</replaceable></option></term>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <option>--url=<replaceable>ADDRESS</replaceable></option> option,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann events will be retrieved using HTTP from
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <replaceable>ADDRESS</replaceable>. This URL should refer to the
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann root of a remote
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann instance (e.g. <ulink>http://some.host:19531/</ulink> or
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <ulink>https://some.host:19531/</ulink>).</para></listitem>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </varlistentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </variablelist>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <para>Passive sources can be specified in the following
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <variablelist>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <varlistentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <term><option>--listen-raw=<replaceable>ADDRESS</replaceable></option></term>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <listitem><para><replaceable>ADDRESS</replaceable> must be an
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann address suitable for <option>ListenStream=</option> (cf.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <command>systemd-journal-remote</command> will listen on this
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann socket for connections. Each connection is expected to be a
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann stream of journal events.</para>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </varlistentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <varlistentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <term><option>--listen-http=<replaceable>ADDRESS</replaceable></option></term>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <term><option>--listen-https=<replaceable>ADDRESS</replaceable></option></term>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <listitem><para><replaceable>ADDRESS</replaceable> must be
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann either a negative integer, in which case it will be
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann interpreted as the (negated) file descriptor number, or an
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann address suitable for <option>ListenStream=</option> (c.f.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
5476ad087c0f2d45ab0dab1bab9ef3e9d70418bcMarcel Holtmann In the first case, matching file descriptor must be inherited
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann In the second case, an HTTP or HTTPS server will be spawned on
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann this port, respectively for <option>--listen-http</option> and
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <option>--listen-https</option>. Currenntly, only POST requests
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann to <filename>/upload</filename> with <literal>Content-Type:
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann application/vnd.fdo.journal</literal> are supported.</para>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </varlistentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <varlistentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <listitem><para><command>systemd-journal-remote</command>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann protocol. Open sockets inherited through socket activation
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann behave like those opened with <option>--listen-raw=</option>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann described above, unless they are specified as an argument in
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <option>--listen-http=-<replaceable>n</replaceable></option>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <option>--listen-https=-<replaceable>n</replaceable></option>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann above. In the latter case, an HTTP or HTTPS server will be
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann spawned using this descriptor and connections must be made
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann over the HTTP protocol.</para>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </varlistentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </variablelist>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <para>The location of the output journal can be specified
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann with <option>-o</option> or <option>--output=</option>. For "active"
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann sources, this option is required.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <variablelist>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <varlistentry>
5476ad087c0f2d45ab0dab1bab9ef3e9d70418bcMarcel Holtmann <term><option>--output=<replaceable>FILE</replaceable></option></term>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <listitem><para>Will write to this journal file. The filename
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann must end with <filename>.journal</filename>. The file will be
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann created if it does not exist. If necessary (journal file full,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann or corrupted), the file will be renamed following normal
5476ad087c0f2d45ab0dab1bab9ef3e9d70418bcMarcel Holtmann journald rules and a new journal file will be created in its
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </varlistentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <varlistentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <term><option>--output=<replaceable>DIR</replaceable></option></term>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <listitem><para>Will create journal files underneath directory
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <replaceable>DIR</replaceable>. The directory must exist. If
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann necessary (journal files over size, or corrupted), journal
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann files will be rotated following normal journald rules. Names
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann of files underneath <replaceable>DIR</replaceable> will be
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann generated using the rules described below.</para></listitem>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </varlistentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </variablelist>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <para>If <option>--output=</option> is not used, the output
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann directory <filename>/var/log/journal/remote/</filename> will be
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann used. In case the output file is not specified, journal files
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann will be created underneath the selected directory. Files will be
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <filename>remote-<replaceable>hostname</replaceable>.journal</filename>,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann where the <replaceable>hostname</replaceable> part is the
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann escaped hostname of the source endpoint of the connection, or the
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann numerical address if the hostname cannot be determined.</para>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <para>In case of "active" sources, the output file name must
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann always be given explicitly.</para>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <para>The following options are understood:</para>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <variablelist>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <varlistentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <listitem><para>One of <constant>none</constant> or
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <constant>host</constant>. For the first, only one output
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann journal file is used. For the latter, a separate output file
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann is used, based on the hostname of the other endpoint of a
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann connection.</para>
5476ad087c0f2d45ab0dab1bab9ef3e9d70418bcMarcel Holtmann <para>In case of "active" sources, the output file name must
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann always be given explicitly and only <constant>none</constant>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </varlistentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <varlistentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <listitem><para>Compress or not, respectively, the data in the
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </varlistentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <varlistentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <listitem><para>Periodically sign or not, respectively, the
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann data in the journal using Forward Secure Sealing.
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </varlistentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <varlistentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <term><option>--getter=<replaceable>PROG --option1 --option2</replaceable></option></term>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <listitem><para>Program to invoke to retrieve data. The journal
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann event stream must be generated on standard output.</para>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <programlisting>--getter='curl "-HAccept: application/vnd.fdo.journal" https://some.host:19531/'</programlisting>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <programlisting>--getter='wget --header="Accept: application/vnd.fdo.journal" -O- https://some.host:19531/'</programlisting>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </varlistentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <xi:include href="standard-options.xml" xpointer="help" />
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <xi:include href="standard-options.xml" xpointer="version" />
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </variablelist>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <para>Copy local journal events to a different journal directory:
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <programlisting>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannjournalctl -o export | systemd-journal-remote -o /tmp/dir -
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </programlisting>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <para>Retrieve events from a remote
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann instance and store them in
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <filename>/var/log/journal/some.host/remote-some~host.journal</filename>:
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <programlisting>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmannsystemd-journal-remote --url http://some.host:19531/
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann </programlisting>
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <citerefentry><refentrytitle>systemd-journal-upload</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
94f5bbc626f2a4102debd9b17c964170a887cb49Marcel Holtmann <citerefentry><refentrytitle>systemd-journal-gatewayd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>