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