man/systemd-journal-remote.xml - systemd-stable - Rivoreo Source Code Repositories

 <?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>. 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 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&amp;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>
	<?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>. 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 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>