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