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>
 184           Takes a path to a SSL key file in PEM format.
 185           Defaults to <filename>&CERTIFICATE_ROOT;/private/journal-remote.pem</filename>.
 186           This option can be used with <option>--listen-https=</option>.
 187         </para></listitem>
 188       </varlistentry>
 189
 190       <varlistentry>
 191         <term><option>--cert=</option></term>
 192
 193         <listitem><para>
 194           Takes a path to a SSL certificate file in PEM format.
 195           Defaults to <filename>&CERTIFICATE_ROOT;/certs/journal-remote.pem</filename>.
 196           This option can be used with <option>--listen-https=</option>.
 197         </para></listitem>
 198       </varlistentry>
 199
 200       <varlistentry>
 201         <term><option>--trust=</option></term>
 202
 203         <listitem><para>
 204           Takes a path to a SSL CA certificate file in PEM format,
 205           or <option>all</option>. If <option>all</option> is set,
 206           then certificate checking will be disabled.
 207           Defaults to <filename>&CERTIFICATE_ROOT;/ca/trusted.pem</filename>.
 208           This option can be used with <option>--listen-https=</option>.
 209         </para></listitem>
 210       </varlistentry>
 211
 212       <varlistentry>
 213         <term><option>--gnutls-log=</option></term>
 214
 215         <listitem><para>
 216           Takes a comma separated list of gnutls logging categories.
 217           This option can be used with <option>--listen-http=</option> or
 218           <option>--listen-https=</option>.
 219         </para></listitem>
 220       </varlistentry>
 221
 222     </variablelist>
 223   </refsect1>
 224
 225   <refsect1>
 226     <title>Sinks</title>
 227
 228     <para>The location of the output journal can be specified
 229     with <option>-o</option> or <option>--output=</option>.
 230     </para>
 231
 232     <variablelist>
 233       <varlistentry>
 234         <term><option>--output=<replaceable>FILE</replaceable></option></term>
 235
 236         <listitem><para>Will write to this journal file. The filename
 237         must end with <filename>.journal</filename>. The file will be
 238         created if it does not exist. If necessary (journal file full,
 239         or corrupted), the file will be renamed following normal
 240         journald rules and a new journal file will be created in its
 241         stead.</para></listitem>
 242       </varlistentry>
 243
 244       <varlistentry>
 245         <term><option>--output=<replaceable>DIR</replaceable></option></term>
 246
 247         <listitem><para>Will create journal files underneath directory
 248         <replaceable>DIR</replaceable>. The directory must exist. If
 249         necessary (journal files over size, or corrupted), journal
 250         files will be rotated following normal journald rules. Names
 251         of files underneath <replaceable>DIR</replaceable> will be
 252         generated using the rules described below.</para></listitem>
 253       </varlistentry>
 254     </variablelist>
 255
 256     <para>If <option>--output=</option> is not used, the output
 257     directory <filename>/var/log/journal/remote/</filename> will be
 258     used.  In case the output file is not specified, journal files
 259     will be created underneath the selected directory. Files will be
 260     called
 261     <filename>remote-<replaceable>hostname</replaceable>.journal</filename>,
 262     where the <replaceable>hostname</replaceable> part is the
 263     escaped hostname of the source endpoint of the connection, or the
 264     numerical address if the hostname cannot be determined.</para>
 265
 266     <para>In the case that "active" sources are given by the positional
 267     arguments or <option>--getter=</option> option, the output file name
 268     must always be given explicitly.</para>
 269   </refsect1>
 270
 271   <refsect1>
 272     <title>Options</title>
 273
 274     <para>The following options are understood:</para>
 275
 276     <variablelist>
 277       <varlistentry>
 278         <term><option>--split-mode</option></term>
 279
 280         <listitem><para>One of <constant>none</constant> or
 281         <constant>host</constant>. For the first, only one output
 282         journal file is used. For the latter, a separate output file
 283         is used, based on the hostname of the other endpoint of a
 284         connection.</para>
 285
 286         <para>In the case that "active" sources are given by the positional
 287         arguments or <option>--getter=</option> option, the output file name must
 288         always be given explicitly and only <constant>none</constant>
 289         is allowed.</para></listitem>
 290       </varlistentry>
 291
 292       <varlistentry>
 293         <term><option>--compress</option> [<replaceable>BOOL</replaceable>]</term>
 294
 295         <listitem><para>If this is set to <literal>yes</literal> then compress
 296         the data in the journal using XZ. The default is <literal>yes</literal>.
 297         </para></listitem>
 298       </varlistentry>
 299
 300       <varlistentry>
 301         <term><option>--seal</option> [<replaceable>BOOL</replaceable>]</term>
 302
 303         <listitem><para>If this is set to <literal>yes</literal> then
 304         periodically sign the data in the journal using Forward Secure Sealing.
 305         The default is <literal>no</literal>.</para></listitem>
 306       </varlistentry>
 307
 308       <xi:include href="standard-options.xml" xpointer="help" />
 309       <xi:include href="standard-options.xml" xpointer="version" />
 310     </variablelist>
 311   </refsect1>
 312
 313   <refsect1>
 314     <title>Examples</title>
 315     <para>Copy local journal events to a different journal directory:
 316     <programlisting>
 317 journalctl -o export | systemd-journal-remote -o /tmp/dir/foo.journal -
 318     </programlisting>
 319     </para>
 320
 321     <para>Retrieve all available events from a remote
 322     <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 323     instance and store them in
 324     <filename>/var/log/journal/remote/remote-some.host.journal</filename>:
 325     <programlisting>
 326 systemd-journal-remote --url http://some.host:19531/
 327     </programlisting>
 328     </para>
 329
 330     <para>Retrieve current boot events and wait for new events from a remote
 331     <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 332     instance, and store them in
 333     <filename>/var/log/journal/remote/remote-some.host.journal</filename>:
 334     <programlisting>
 335 systemd-journal-remote --url http://some.host:19531/entries?boot&amp;follow
 336     </programlisting>
 337     </para>
 338 </refsect1>
 339
 340   <refsect1>
 341     <title>See Also</title>
 342     <para>
 343       <citerefentry><refentrytitle>journal-remote.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 344       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 345       <citerefentry><refentrytitle>systemd-journal-gatewayd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 346       <citerefentry><refentrytitle>systemd-journal-upload.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 347       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 348     </para>
 349   </refsect1>
 350 </refentry>