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