-<?xml version='1.0'?> <!--*-nxml-*-->
+<?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">
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
-<refentry id="systemd-journal-remote" conditional='HAVE_MICROHTTPD'>
+<refentry id="systemd-journal-remote" conditional='HAVE_MICROHTTPD'
+ xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>systemd-journal-remote</title>
<refnamediv>
<refname>systemd-journal-remote</refname>
- <refpurpose>Stream journal messages over the network</refpurpose>
+ <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=DIR|FILE</arg>
+ <arg choice="opt" rep="norepeat">-o/--output=<replaceable>DIR</replaceable>|<replaceable>FILE</replaceable></arg>
<arg choice="opt" rep="repeat">SOURCES</arg>
</cmdsynopsis>
</refsynopsisdiv>
<para>
<filename>systemd-journal-remote</filename> is a command to
receive serialized journal events and store them to the journal.
- Input streams must be in the
+ 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>.
+ <command>journalctl --output=export</command>. For transport over
+ the network, this serialized stream is usually carried over an
+ HTTPS connection.
</para>
</refsect1>
<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
+ 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).
<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
+ <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>
<option>--listen-http=-<replaceable>n</replaceable></option>
or
<option>--listen-https=-<replaceable>n</replaceable></option>
- above. In this later case, an HTTP or HTTPS server will be
+ 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>
<title>Sinks</title>
<para>The location of the output journal can be specified
- with <option>-o</option> or <option>--output=</option>.
+ 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. The filename must
- end with <filename>.journal</filename>. The file will be
- created if it does not exist. When necessary (journal file
- full, or corrupted) the file will be renamed following normal
+ <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>
<term><option>--output=<replaceable>DIR</replaceable></option></term>
<listitem><para>Will create journal files underneath directory
- <replaceable>DIR</replaceable>. The directory must exist. When
- necessary (journal files over size, or corrupted) journal
+ <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, output directory
- <filename>/var/log/journal/<replaceable>machine-id</replaceable>/</filename>
- will be used, where <replaceable>machine-id</replaceable> is the
- identifier of the current system (see
- <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
- In case the output file is not specified, journal files will be
- created underneath the selected directory. Files will be called
- <filename>remote-<replaceable>variable</replaceable>.journal</filename>,
- where the <replaceable>variable</replaceable> part is generated
- based on what passive and active sources are specified. It is
- recommended to give a full output filename.</para>
-
- <para>In case of "active" sources, if the hostname is known it
- will be used in the <replaceable>variable</replaceable> part.
- Otherwise, local address and port number will be used, or
- <literal>stdin</literal> for events passed over standard
- input, and <literal>multiple</literal> if more than one source
- is specified.</para>
+ <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>
<variablelist>
<varlistentry>
- <term><option>--help</option></term>
- <term><option>-h</option></term>
+ <term><option>--split-mode</option></term>
- <listitem><para>Print a short help
- text and exit.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--version</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>
- <listitem><para>Print a short version
- string and exit.</para></listitem>
+ <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>
<varlistentry>
<term><option>--getter=<replaceable>PROG --option1 --option2</replaceable></option></term>
- <listitem><para>Program to invoke to retrieve data. Journal
+ <listitem><para>Program to invoke to retrieve data. The journal
event stream must be generated on standard output.</para>
<para>Examples:</para>
<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>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>systemd-journal-gatewayd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>
~ianmdlvl / elogind.git / blobdiff