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+ -->
   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://www.freedesktop.org/wiki/Software/systemd/export">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></listitem>
  96       </varlistentry>
  97
  98       <varlistentry>
  99         <term><option>--url=<replaceable>ADDRESS</replaceable></option></term>
 100
 101         <listitem><para>With the
 102         <option>--url=<replaceable>ADDRESS</replaceable></option> option,
 103         events will be retrieved using HTTP from
 104         <replaceable>ADDRESS</replaceable>. This URL should refer to the
 105         root of a remote
 106         <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 107         instance, e.g. http://some.host:19531/ or
 108         https://some.host:19531/.</para></listitem>
 109       </varlistentry>
 110
 111       <varlistentry>
 112         <term><option>--getter='<replaceable>PROG</replaceable> <arg choice="opt" rep="repeat">OPTIONS</arg>'</option></term>
 113
 114         <listitem><para>Program to invoke to retrieve data. The journal
 115         event stream must be generated on standard output.</para>
 116
 117         <para>Examples:</para>
 118
 119         <programlisting>--getter='curl "-HAccept: application/vnd.fdo.journal" https://some.host:19531/'</programlisting>
 120
 121         <programlisting>--getter='wget --header="Accept: application/vnd.fdo.journal" -O- https://some.host:19531/'</programlisting>
 122         </listitem>
 123       </varlistentry>
 124     </variablelist>
 125
 126     <para>Passive sources can be specified in the following
 127     ways:</para>
 128
 129     <variablelist>
 130       <varlistentry>
 131         <term><option>--listen-raw=<replaceable>ADDRESS</replaceable></option></term>
 132
 133         <listitem><para><replaceable>ADDRESS</replaceable> must be an
 134         address suitable for <option>ListenStream=</option> (cf.
 135         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 136         <command>systemd-journal-remote</command> will listen on this
 137         socket for connections. Each connection is expected to be a
 138         stream of journal events.</para>
 139         </listitem>
 140       </varlistentry>
 141
 142       <varlistentry>
 143         <term><option>--listen-http=<replaceable>ADDRESS</replaceable></option></term>
 144         <term><option>--listen-https=<replaceable>ADDRESS</replaceable></option></term>
 145
 146         <listitem><para><replaceable>ADDRESS</replaceable> must be
 147         either a negative integer, in which case it will be
 148         interpreted as the (negated) file descriptor number, or an
 149         address suitable for <option>ListenStream=</option> (c.f.
 150         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 151         In the first case, the server listens on port 19532 by default,
 152         and the matching file descriptor must be inherited through
 153         <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>.
 154         In the second case, an HTTP or HTTPS server will be spawned on
 155         this port, respectively for <option>--listen-http=</option> and
 156         <option>--listen-https=</option>. Currently, only POST requests
 157         to <filename>/upload</filename> with <literal>Content-Type:
 158         application/vnd.fdo.journal</literal> are supported.</para>
 159         </listitem>
 160       </varlistentry>
 161
 162       <varlistentry>
 163         <term><varname>$LISTEN_FDS</varname></term>
 164
 165         <listitem><para><command>systemd-journal-remote</command>
 166         supports the
 167         <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>
 168         protocol. Open sockets inherited through socket activation
 169         behave like those opened with <option>--listen-raw=</option>
 170         described above, unless they are specified as an argument in
 171         <option>--listen-http=-<replaceable>n</replaceable></option>
 172         or
 173         <option>--listen-https=-<replaceable>n</replaceable></option>
 174         above. In the latter case, an HTTP or HTTPS server will be
 175         spawned using this descriptor and connections must be made
 176         over the HTTP protocol.</para>
 177         </listitem>
 178       </varlistentry>
 179
 180       <varlistentry>
 181         <term><option>--key=</option></term>
 182
 183         <listitem><para> Takes a path to a SSL key file in PEM format. Defaults to
 184         <filename>&CERTIFICATE_ROOT;/private/journal-remote.pem</filename>. This option can be used with
 185         <option>--listen-https=</option>. If the path refers to an <constant>AF_UNIX</constant> stream socket
 186         in the file system a connection is made to it and the key read from it.</para></listitem>
 187       </varlistentry>
 188
 189       <varlistentry>
 190         <term><option>--cert=</option></term>
 191
 192         <listitem><para> Takes a path to a SSL certificate file in PEM format. Defaults to
 193         <filename>&CERTIFICATE_ROOT;/certs/journal-remote.pem</filename>. This option can be used with
 194         <option>--listen-https=</option>. If the path refers to an <constant>AF_UNIX</constant> stream socket
 195         in the file system a connection is made to it and the certificate read from it.</para></listitem>
 196       </varlistentry>
 197
 198       <varlistentry>
 199         <term><option>--trust=</option></term>
 200
 201         <listitem><para> Takes a path to a SSL CA certificate file in PEM format, or <option>all</option>. If
 202         <option>all</option> is set, then certificate checking will be disabled. Defaults to
 203         <filename>&CERTIFICATE_ROOT;/ca/trusted.pem</filename>. This option can be used with
 204         <option>--listen-https=</option>. If the path refers to an <constant>AF_UNIX</constant> stream socket
 205         in the file system a connection is made to it and the certificate read from it.</para></listitem>
 206       </varlistentry>
 207
 208       <varlistentry>
 209         <term><option>--gnutls-log=</option></term>
 210
 211         <listitem><para>
 212           Takes a comma separated list of gnutls logging categories.
 213           This option can be used with <option>--listen-http=</option> or
 214           <option>--listen-https=</option>.
 215         </para></listitem>
 216       </varlistentry>
 217
 218     </variablelist>
 219   </refsect1>
 220
 221   <refsect1>
 222     <title>Sinks</title>
 223
 224     <para>The location of the output journal can be specified
 225     with <option>-o</option> or <option>--output=</option>.
 226     </para>
 227
 228     <variablelist>
 229       <varlistentry>
 230         <term><option>--output=<replaceable>FILE</replaceable></option></term>
 231
 232         <listitem><para>Will write to this journal file. The filename
 233         must end with <filename>.journal</filename>. The file will be
 234         created if it does not exist. If necessary (journal file full,
 235         or corrupted), the file will be renamed following normal
 236         journald rules and a new journal file will be created in its
 237         stead.</para></listitem>
 238       </varlistentry>
 239
 240       <varlistentry>
 241         <term><option>--output=<replaceable>DIR</replaceable></option></term>
 242
 243         <listitem><para>Will create journal files underneath directory
 244         <replaceable>DIR</replaceable>. The directory must exist. If
 245         necessary (journal files over size, or corrupted), journal
 246         files will be rotated following normal journald rules. Names
 247         of files underneath <replaceable>DIR</replaceable> will be
 248         generated using the rules described below.</para></listitem>
 249       </varlistentry>
 250     </variablelist>
 251
 252     <para>If <option>--output=</option> is not used, the output
 253     directory <filename>/var/log/journal/remote/</filename> will be
 254     used.  In case the output file is not specified, journal files
 255     will be created underneath the selected directory. Files will be
 256     called
 257     <filename>remote-<replaceable>hostname</replaceable>.journal</filename>,
 258     where the <replaceable>hostname</replaceable> part is the
 259     escaped hostname of the source endpoint of the connection, or the
 260     numerical address if the hostname cannot be determined.</para>
 261
 262     <para>In the case that "active" sources are given by the positional
 263     arguments or <option>--getter=</option> option, the output file name
 264     must always be given explicitly.</para>
 265   </refsect1>
 266
 267   <refsect1>
 268     <title>Options</title>
 269
 270     <para>The following options are understood:</para>
 271
 272     <variablelist>
 273       <varlistentry>
 274         <term><option>--split-mode</option></term>
 275
 276         <listitem><para>One of <constant>none</constant> or
 277         <constant>host</constant>. For the first, only one output
 278         journal file is used. For the latter, a separate output file
 279         is used, based on the hostname of the other endpoint of a
 280         connection.</para>
 281
 282         <para>In the case that "active" sources are given by the positional
 283         arguments or <option>--getter=</option> option, the output file name must
 284         always be given explicitly and only <constant>none</constant>
 285         is allowed.</para></listitem>
 286       </varlistentry>
 287
 288       <varlistentry>
 289         <term><option>--compress</option> [<replaceable>BOOL</replaceable>]</term>
 290
 291         <listitem><para>If this is set to <literal>yes</literal> then compress
 292         the data in the journal using XZ. The default is <literal>yes</literal>.
 293         </para></listitem>
 294       </varlistentry>
 295
 296       <varlistentry>
 297         <term><option>--seal</option> [<replaceable>BOOL</replaceable>]</term>
 298
 299         <listitem><para>If this is set to <literal>yes</literal> then
 300         periodically sign the data in the journal using Forward Secure Sealing.
 301         The default is <literal>no</literal>.</para></listitem>
 302       </varlistentry>
 303
 304       <xi:include href="standard-options.xml" xpointer="help" />
 305       <xi:include href="standard-options.xml" xpointer="version" />
 306     </variablelist>
 307   </refsect1>
 308
 309   <refsect1>
 310     <title>Examples</title>
 311     <para>Copy local journal events to a different journal directory:
 312     <programlisting>
 313 journalctl -o export | systemd-journal-remote -o /tmp/dir/foo.journal -
 314     </programlisting>
 315     </para>
 316
 317     <para>Retrieve all available events from a remote
 318     <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 319     instance and store them in
 320     <filename>/var/log/journal/remote/remote-some.host.journal</filename>:
 321     <programlisting>
 322 systemd-journal-remote --url http://some.host:19531/
 323     </programlisting>
 324     </para>
 325
 326     <para>Retrieve current boot events and wait for new events from a remote
 327     <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 328     instance, and store them in
 329     <filename>/var/log/journal/remote/remote-some.host.journal</filename>:
 330     <programlisting>
 331 systemd-journal-remote --url http://some.host:19531/entries?boot&amp;follow
 332     </programlisting>
 333     </para>
 334 </refsect1>
 335
 336   <refsect1>
 337     <title>See Also</title>
 338     <para>
 339       <citerefentry><refentrytitle>journal-remote.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 340       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 341       <citerefentry><refentrytitle>systemd-journal-gatewayd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 342       <citerefentry><refentrytitle>systemd-journal-upload.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 343       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 344     </para>
 345   </refsect1>
 346 </refentry>