+++ /dev/null
-<?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. <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>. Currenntly, 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>
~ianmdlvl / elogind.git / blobdiff