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