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