man/systemd-journal-remote.xml

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