man/systemd-journal-remote.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2012 Zbigniew Jędrzejewski-Szmek
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="systemd-journal-remote" conditional='HAVE_MICROHTTPD'
  28           xmlns:xi="http://www.w3.org/2001/XInclude">
  29
  30   <refentryinfo>
  31     <title>systemd-journal-remote</title>
  32     <productname>systemd</productname>
  33
  34     <authorgroup>
  35       <author>
  36         <contrib>Developer</contrib>
  37         <firstname>Zbigniew</firstname>
  38         <surname>Jędrzejewski-Szmek</surname>
  39         <email>zbyszek@in.waw.pl</email>
  40       </author>
  41     </authorgroup>
  42   </refentryinfo>
  43
  44   <refmeta>
  45     <refentrytitle>systemd-journal-remote</refentrytitle>
  46     <manvolnum>8</manvolnum>
  47   </refmeta>
  48
  49   <refnamediv>
  50     <refname>systemd-journal-remote</refname>
  51     <refpurpose>Receive journal messages over the network</refpurpose>
  52   </refnamediv>
  53
  54   <refsynopsisdiv>
  55     <cmdsynopsis>
  56       <command>systemd-journal-remote</command>
  57       <arg choice="opt" rep="repeat">OPTIONS</arg>
  58       <arg choice="opt" rep="norepeat">-o/--output=<replaceable>DIR</replaceable>|<replaceable>FILE</replaceable></arg>
  59       <arg choice="opt" rep="repeat">SOURCES</arg>
  60     </cmdsynopsis>
  61   </refsynopsisdiv>
  62
  63   <refsect1>
  64     <title>Description</title>
  65
  66     <para>
  67       <filename>systemd-journal-remote</filename> is a command to
  68       receive serialized journal events and store them to the journal.
  69       Input streams are in the
  70       <ulink url="http://www.freedesktop.org/wiki/Software/systemd/export">
  71         Journal Export Format
  72       </ulink>,
  73       i.e. like the output from
  74       <command>journalctl --output=export</command>. For transport over
  75       the network, this serialized stream is usually carried over an
  76       HTTPS connection.
  77     </para>
  78   </refsect1>
  79
  80   <refsect1>
  81     <title>Sources</title>
  82
  83     <para>
  84       Sources can be either "active"
  85       (<command>systemd-journal-remote</command> requests and pulls
  86       the data), or "passive"
  87       (<command>systemd-journal-remote</command> waits for a
  88       connection and then receives events pushed by the other side).
  89     </para>
  90
  91     <para>
  92       <command>systemd-journal-remote</command> can read more than one
  93       event stream at a time. They will be interleaved in the output
  94       file. In case of "active" connections, each "source" is one
  95       stream, and in case of "passive" connections, each connection can
  96       result in a separate stream. Sockets can be configured in
  97       "accept" mode (i.e. only one connection), or "listen" mode (i.e.
  98       multiple connections, each resulting in a stream).
  99     </para>
 100
 101     <para>
 102       When there are no more connections, and no more can be created
 103       (there are no listening sockets), then
 104       <command>systemd-journal-remote</command> will exit.
 105     </para>
 106
 107     <para>Active sources can be specified in the following
 108     ways:</para>
 109
 110     <variablelist>
 111       <varlistentry>
 112         <listitem><para>When <option>-</option> is given as a
 113         positional argument, events will be read from standard input.
 114         Other positional arguments will be treated as filenames
 115         to open and read from.</para></listitem>
 116       </varlistentry>
 117
 118       <varlistentry>
 119         <term><option>--url=<replaceable>ADDRESS</replaceable></option></term>
 120
 121         <listitem><para>With the
 122         <option>--url=<replaceable>ADDRESS</replaceable></option> option,
 123         events will be retrieved using HTTP from
 124         <replaceable>ADDRESS</replaceable>. This URL should refer to the
 125         root of a remote
 126         <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 127         instance (e.g. <ulink>http://some.host:19531/</ulink> or
 128         <ulink>https://some.host:19531/</ulink>).</para></listitem>
 129       </varlistentry>
 130     </variablelist>
 131
 132     <para>Passive sources can be specified in the following
 133     ways:</para>
 134
 135     <variablelist>
 136       <varlistentry>
 137         <term><option>--listen-raw=<replaceable>ADDRESS</replaceable></option></term>
 138
 139         <listitem><para><replaceable>ADDRESS</replaceable> must be an
 140         address suitable for <option>ListenStream=</option> (cf.
 141         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 142         <command>systemd-journal-remote</command> will listen on this
 143         socket for connections. Each connection is expected to be a
 144         stream of journal events.</para>
 145         </listitem>
 146       </varlistentry>
 147
 148       <varlistentry>
 149         <term><option>--listen-http=<replaceable>ADDRESS</replaceable></option></term>
 150         <term><option>--listen-https=<replaceable>ADDRESS</replaceable></option></term>
 151
 152         <listitem><para><replaceable>ADDRESS</replaceable> must be
 153         either a negative integer, in which case it will be
 154         interpreted as the (negated) file descriptor number, or an
 155         address suitable for <option>ListenStream=</option> (c.f.
 156         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 157         In the first case, matching file descriptor must be inherited
 158         through
 159         <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>.
 160         In the second case, an HTTP or HTTPS server will be spawned on
 161         this port, respectively for <option>--listen-http</option> and
 162         <option>--listen-https</option>. Currently, only POST requests
 163         to <filename>/upload</filename> with <literal>Content-Type:
 164         application/vnd.fdo.journal</literal> are supported.</para>
 165         </listitem>
 166       </varlistentry>
 167
 168       <varlistentry>
 169         <term><varname>$LISTEN_FDS</varname></term>
 170
 171         <listitem><para><command>systemd-journal-remote</command>
 172         supports the
 173         <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>
 174         protocol. Open sockets inherited through socket activation
 175         behave like those opened with <option>--listen-raw=</option>
 176         described above, unless they are specified as an argument in
 177         <option>--listen-http=-<replaceable>n</replaceable></option>
 178         or
 179         <option>--listen-https=-<replaceable>n</replaceable></option>
 180         above. In the latter case, an HTTP or HTTPS server will be
 181         spawned using this descriptor and connections must be made
 182         over the HTTP protocol.</para>
 183         </listitem>
 184       </varlistentry>
 185
 186     </variablelist>
 187   </refsect1>
 188
 189   <refsect1>
 190     <title>Sinks</title>
 191
 192     <para>The location of the output journal can be specified
 193     with <option>-o</option> or <option>--output=</option>. For "active"
 194     sources, this option is required.
 195     </para>
 196
 197     <variablelist>
 198       <varlistentry>
 199         <term><option>--output=<replaceable>FILE</replaceable></option></term>
 200
 201         <listitem><para>Will write to this journal file. The filename
 202         must end with <filename>.journal</filename>. The file will be
 203         created if it does not exist. If necessary (journal file full,
 204         or corrupted), the file will be renamed following normal
 205         journald rules and a new journal file will be created in its
 206         stead.</para></listitem>
 207       </varlistentry>
 208
 209       <varlistentry>
 210         <term><option>--output=<replaceable>DIR</replaceable></option></term>
 211
 212         <listitem><para>Will create journal files underneath directory
 213         <replaceable>DIR</replaceable>. The directory must exist. If
 214         necessary (journal files over size, or corrupted), journal
 215         files will be rotated following normal journald rules. Names
 216         of files underneath <replaceable>DIR</replaceable> will be
 217         generated using the rules described below.</para></listitem>
 218       </varlistentry>
 219     </variablelist>
 220
 221     <para>If <option>--output=</option> is not used, the output
 222     directory <filename>/var/log/journal/remote/</filename> will be
 223     used.  In case the output file is not specified, journal files
 224     will be created underneath the selected directory. Files will be
 225     called
 226     <filename>remote-<replaceable>hostname</replaceable>.journal</filename>,
 227     where the <replaceable>hostname</replaceable> part is the
 228     escaped hostname of the source endpoint of the connection, or the
 229     numerical address if the hostname cannot be determined.</para>
 230
 231     <para>In case of "active" sources, the output file name must
 232     always be given explicitly.</para>
 233   </refsect1>
 234
 235   <refsect1>
 236     <title>Options</title>
 237
 238     <para>The following options are understood:</para>
 239
 240     <variablelist>
 241       <varlistentry>
 242         <term><option>--split-mode</option></term>
 243
 244         <listitem><para>One of <constant>none</constant> or
 245         <constant>host</constant>. For the first, only one output
 246         journal file is used. For the latter, a separate output file
 247         is used, based on the hostname of the other endpoint of a
 248         connection.</para>
 249
 250         <para>In case of "active" sources, the output file name must
 251         always be given explicitly and only <constant>none</constant>
 252         is allowed.</para></listitem>
 253       </varlistentry>
 254
 255       <varlistentry>
 256         <term><option>--compress</option></term>
 257         <term><option>--no-compress</option></term>
 258
 259         <listitem><para>Compress or not, respectively, the data in the
 260         journal using XZ.</para></listitem>
 261       </varlistentry>
 262
 263       <varlistentry>
 264         <term><option>--seal</option></term>
 265         <term><option>--no-seal</option></term>
 266
 267         <listitem><para>Periodically sign or not, respectively, the
 268         data in the journal using Forward Secure Sealing.
 269         </para></listitem>
 270       </varlistentry>
 271
 272       <varlistentry>
 273         <term><option>--getter=<replaceable>PROG --option1 --option2</replaceable></option></term>
 274
 275         <listitem><para>Program to invoke to retrieve data. The journal
 276         event stream must be generated on standard output.</para>
 277
 278         <para>Examples:</para>
 279
 280         <programlisting>--getter='curl "-HAccept: application/vnd.fdo.journal" https://some.host:19531/'</programlisting>
 281
 282         <programlisting>--getter='wget --header="Accept: application/vnd.fdo.journal" -O- https://some.host:19531/'</programlisting>
 283         </listitem>
 284       </varlistentry>
 285
 286       <xi:include href="standard-options.xml" xpointer="help" />
 287       <xi:include href="standard-options.xml" xpointer="version" />
 288     </variablelist>
 289   </refsect1>
 290
 291   <refsect1>
 292     <title>Examples</title>
 293     <para>Copy local journal events to a different journal directory:
 294     <programlisting>
 295 journalctl -o export | systemd-journal-remote -o /tmp/dir -
 296     </programlisting>
 297     </para>
 298
 299     <para>Retrieve events from a remote
 300     <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 301     instance and store them in
 302     <filename>/var/log/journal/some.host/remote-some~host.journal</filename>:
 303     <programlisting>
 304 systemd-journal-remote --url http://some.host:19531/
 305     </programlisting>
 306     </para>
 307   </refsect1>
 308
 309   <refsect1>
 310     <title>See Also</title>
 311     <para>
 312       <citerefentry><refentrytitle>systemd-journal-upload</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 313       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 314       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 315       <citerefentry><refentrytitle>systemd-journal-gatewayd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 316       <citerefentry><refentrytitle>journal-remote.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 317     </para>
 318   </refsect1>
 319 </refentry>