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