<?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; ]> <!-- 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. <ulink>http://some.host:19531/</ulink> or <ulink>https://some.host:19531/</ulink>).</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></term> <term><option>--no-compress</option></term> <listitem><para>Compress or not, respectively, the data in the journal using XZ.</para></listitem> </varlistentry> <varlistentry> <term><option>--seal</option></term> <term><option>--no-seal</option></term> <listitem><para>Periodically sign or not, respectively, the data in the journal using Forward Secure Sealing. </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 events from a remote <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry> instance and store them in <filename>/var/log/journal/some.host/remote-some~host.journal</filename>: <programlisting> systemd-journal-remote --url http://some.host:19531/ </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>