man/systemd-journal-remote.service.xml

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