diff options
Diffstat (limited to 'src/grp-journal/grp-remote/systemd-journal-remote/systemd-journal-remote.xml')
| -rw-r--r-- | src/grp-journal/grp-remote/systemd-journal-remote/systemd-journal-remote.xml | 324 |
1 files changed, 324 insertions, 0 deletions
diff --git a/src/grp-journal/grp-remote/systemd-journal-remote/systemd-journal-remote.xml b/src/grp-journal/grp-remote/systemd-journal-remote/systemd-journal-remote.xml new file mode 100644 index 0000000000..ee2d5c2486 --- /dev/null +++ b/src/grp-journal/grp-remote/systemd-journal-remote/systemd-journal-remote.xml @@ -0,0 +1,324 @@ +<?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&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> |