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