man/systemd-journal-remote.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   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
  26   <refentryinfo>
  27     <title>systemd-journal-remote</title>
  28     <productname>systemd</productname>
  29
  30     <authorgroup>
  31       <author>
  32         <contrib>Developer</contrib>
  33         <firstname>Zbigniew</firstname>
  34         <surname>Jędrzejewski-Szmek</surname>
  35         <email>zbyszek@in.waw.pl</email>
  36       </author>
  37     </authorgroup>
  38   </refentryinfo>
  39
  40   <refmeta>
  41     <refentrytitle>systemd-journal-remote</refentrytitle>
  42     <manvolnum>8</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  46     <refname>systemd-journal-remote</refname>
  47     <refpurpose>Stream journal messages over the network</refpurpose>
  48   </refnamediv>
  49
  50   <refsynopsisdiv>
  51     <cmdsynopsis>
  52       <command>systemd-journal-remote</command>
  53       <arg choice="opt" rep="repeat">OPTIONS</arg>
  54       <arg choice="opt" rep="norepeat">-o/--output=DIR|FILE</arg>
  55       <arg choice="opt" rep="repeat">SOURCES</arg>
  56     </cmdsynopsis>
  57   </refsynopsisdiv>
  58
  59   <refsect1>
  60     <title>Description</title>
  61
  62     <para>
  63       <filename>systemd-journal-remote</filename> is a command to
  64       receive serialized journal events and store them to the journal.
  65       Input streams must be in the
  66       <ulink url="http://www.freedesktop.org/wiki/Software/systemd/export">
  67         Journal Export Format
  68       </ulink>,
  69       i.e. like the output from
  70       <command>journalctl --output=export</command>.
  71     </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         <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. <ulink>http://some.host:19531/</ulink> or
 122         <ulink>https://some.host:19531/</ulink>).</para></listitem>
 123       </varlistentry>
 124     </variablelist>
 125
 126     <para>Passive sources can be specified in the following
 127     ways:</para>
 128
 129     <variablelist>
 130       <varlistentry>
 131         <term><option>--listen-raw=<replaceable>ADDRESS</replaceable></option></term>
 132
 133         <listitem><para><replaceable>ADDRESS</replaceable> must be an
 134         address suitable for <option>ListenStream=</option> (cf.
 135         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 136         <command>systemd-journal-remote</command> will listen on this
 137         socket for connections. Each connection is expected to be a
 138         stream of journal events.</para>
 139         </listitem>
 140       </varlistentry>
 141
 142       <varlistentry>
 143         <term><option>--listen-http=<replaceable>ADDRESS</replaceable></option></term>
 144         <term><option>--listen-https=<replaceable>ADDRESS</replaceable></option></term>
 145
 146         <listitem><para><replaceable>ADDRESS</replaceable> must be
 147         either a negative integer, in which case it will be
 148         interpreted as the (negated) file descriptor number, or an
 149         address suitable for <option>ListenStream=</option> (c.f.
 150         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 151         In the first case, matching file descriptor must be inherited
 152         through
 153         <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>.
 154         In the second case, an HTTP or HTTPS server will be spawned on
 155         this port, respectively for <option>--listen-http</option> and
 156         <option>--listen-https</option>. Currenntly, only POST requests
 157         to <filename>/upload</filename> with <literal>Content-Type:
 158         application/vnd.fdo.journal</literal> are supported.</para>
 159         </listitem>
 160       </varlistentry>
 161
 162       <varlistentry>
 163         <term><varname>$LISTEN_FDS</varname></term>
 164
 165         <listitem><para><command>systemd-journal-remote</command>
 166         supports the
 167         <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>
 168         protocol. Open sockets inherited through socket activation
 169         behave like those opened with <option>--listen-raw=</option>
 170         described above, unless they are specified as an argument in
 171         <option>--listen-http=-<replaceable>n</replaceable></option>
 172         or
 173         <option>--listen-https=-<replaceable>n</replaceable></option>
 174         above. In the latter case, an HTTP or HTTPS server will be
 175         spawned using this descriptor and connections must be made
 176         over the HTTP protocol.</para>
 177         </listitem>
 178       </varlistentry>
 179
 180     </variablelist>
 181   </refsect1>
 182
 183   <refsect1>
 184     <title>Sinks</title>
 185
 186     <para>The location of the output journal can be specified
 187     with <option>-o</option> or <option>--output=</option>.
 188     </para>
 189
 190     <variablelist>
 191       <varlistentry>
 192         <term><option>--output=<replaceable>FILE</replaceable></option></term>
 193
 194         <listitem><para>Will write to this journal. The filename must
 195         end with <filename>.journal</filename>. The file will be
 196         created if it does not exist. If necessary (journal file
 197         full, or corrupted), the file will be renamed following normal
 198         journald rules and a new journal file will be created in its
 199         stead.</para></listitem>
 200       </varlistentry>
 201
 202       <varlistentry>
 203         <term><option>--output=<replaceable>DIR</replaceable></option></term>
 204
 205         <listitem><para>Will create journal files underneath directory
 206         <replaceable>DIR</replaceable>. The directory must exist. If
 207         necessary (journal files over size, or corrupted), journal
 208         files will be rotated following normal journald rules. Names
 209         of files underneath <replaceable>DIR</replaceable> will be
 210         generated using the rules described below.</para></listitem>
 211       </varlistentry>
 212     </variablelist>
 213
 214     <para>If <option>--output=</option> is not used, the output directory
 215     <filename>/var/log/journal/<replaceable>machine-id</replaceable>/</filename>
 216     will be used, where <replaceable>machine-id</replaceable> is the
 217     identifier of the current system (see
 218     <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 219     In case the output file is not specified, journal files will be
 220     created underneath the selected directory. Files will be called
 221     <filename>remote-<replaceable>variable</replaceable>.journal</filename>,
 222     where the <replaceable>variable</replaceable> part is generated
 223     based on what passive and active sources are specified. It is
 224     recommended to give a full output filename.</para>
 225
 226     <para>In case of "active" sources, if the hostname is known, it
 227     will be used in the <replaceable>variable</replaceable> part.
 228     Otherwise, local address and port number will be used, or
 229     <literal>stdin</literal> for events passed over standard
 230     input, and <literal>multiple</literal> if more than one source
 231     is specified.</para>
 232   </refsect1>
 233
 234   <refsect1>
 235     <title>Options</title>
 236
 237     <para>The following options are understood:</para>
 238
 239     <variablelist>
 240       <varlistentry>
 241         <term><option>--help</option></term>
 242         <term><option>-h</option></term>
 243
 244         <listitem><para>Print a short help
 245         text and exit.</para></listitem>
 246       </varlistentry>
 247
 248       <varlistentry>
 249         <term><option>--version</option></term>
 250
 251         <listitem><para>Print a short version
 252         string and exit.</para></listitem>
 253       </varlistentry>
 254
 255       <varlistentry>
 256         <term><option>--compress</option></term>
 257         <term><option>--no-compress</option></term>
 258
 259         <listitem><para>Compress or not, respectively, the data in the
 260         journal using XZ.</para></listitem>
 261       </varlistentry>
 262
 263       <varlistentry>
 264         <term><option>--seal</option></term>
 265         <term><option>--no-seal</option></term>
 266
 267         <listitem><para>Periodically sign or not, respectively, the
 268         data in the journal using Forward Secure Sealing.
 269         </para></listitem>
 270       </varlistentry>
 271
 272       <varlistentry>
 273         <term><option>--getter=<replaceable>PROG --option1 --option2</replaceable></option></term>
 274
 275         <listitem><para>Program to invoke to retrieve data. The journal
 276         event stream must be generated on standard output.</para>
 277
 278         <para>Examples:</para>
 279
 280         <programlisting>--getter='curl "-HAccept: application/vnd.fdo.journal" https://some.host:19531/'</programlisting>
 281
 282         <programlisting>--getter='wget --header="Accept: application/vnd.fdo.journal" -O- https://some.host:19531/'</programlisting>
 283         </listitem>
 284       </varlistentry>
 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 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/some.host/remote-some~host.journal</filename>:
 300     <programlisting>
 301 systemd-journal-remote --url http://some.host:19531/
 302     </programlisting>
 303     </para>
 304   </refsect1>
 305
 306   <refsect1>
 307     <title>See Also</title>
 308     <para>
 309       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 310       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 311       <citerefentry><refentrytitle>systemd-journal-gatewayd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 312     </para>
 313   </refsect1>
 314 </refentry>