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