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 than 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> (c.f.
 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 an
 147         address suitable for <option>ListenStream=</option> (c.f.
 148         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 149         HTTP or HTTPS server will be spawned on this port,
 150         respectively, for the first and second options. Currenntly
 151         Only POST requests to <filename>/upload</filename> with
 152         <literal>Content-Type: application/vnd.fdo.journal</literal>
 153         are supported.</para>
 154         </listitem>
 155       </varlistentry>
 156
 157       <varlistentry>
 158         <term><varname>$LISTEN_FDS</varname></term>
 159
 160         <listitem><para><command>systemd-journal-remote</command>
 161         supports the
 162         <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>
 163         protocol. Open sockets inherited through socket
 164         activation behave like those opened with
 165         <option>--listen-raw=</option> described above.
 166         </para>
 167         </listitem>
 168       </varlistentry>
 169
 170     </variablelist>
 171   </refsect1>
 172
 173   <refsect1>
 174     <title>Sinks</title>
 175
 176     <para>The location of the output journal can be specified
 177     with <option>-o</option> or <option>--output=</option>.
 178     </para>
 179
 180     <variablelist>
 181       <varlistentry>
 182         <term><option>--output=<replaceable>FILE</replaceable></option></term>
 183
 184         <listitem><para>Will write to this journal. The filename must
 185         end with <filename>.journal</filename>. The file will be
 186         created if it does not exist. When necessary (journal file
 187         full, or corrupted) the file will be renamed following normal
 188         journald rules and a new journal file will be created in it's
 189         stead. </para></listitem>
 190       </varlistentry>
 191
 192       <varlistentry>
 193         <term><option>--output=<replaceable>DIR</replaceable></option></term>
 194
 195         <listitem><para>Will create journal files underneath directory
 196         <replaceable>DIR</replaceable>. The directory must exist. When
 197         necessary (journal files over size, or corrupted) journal
 198         files will be rotated following normal journald rules. Names
 199         of files underneath <replaceable>DIR</replaceable> will be
 200         generated using the rules described below.</para></listitem>
 201       </varlistentry>
 202     </variablelist>
 203
 204     <para>If <option>--output=</option> is not used, output directory
 205     <filename>/var/log/journal/<replaceable>machine-id</replaceable>/</filename>
 206     will be used, where <replaceable>machine-id</replaceable> is the
 207     identifier of the current system (see
 208     <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 209     In case the output file is not specified, journal files will be
 210     created underneath the selected directory. Files will be called
 211     <filename>remote-<replaceable>variable</replaceable>.journal</filename>,
 212     where the <replaceable>variable</replaceable> part is generated
 213     based on what passive and active sources are specified. It is
 214     recommended to give a full output filename.</para>
 215
 216     <para>In case of "active" sources, if the hostname is known it
 217     will be used in the <replaceable>variable</replaceable> part.
 218     Otherwise, local address and port number will be used, or
 219     <literal>stdin</literal> for events passed over standard
 220     input, and <literal>multiple</literal> if more than one source
 221     is specified.</para>
 222   </refsect1>
 223
 224   <refsect1>
 225     <title>Options</title>
 226
 227     <para>The following options are understood:</para>
 228
 229     <variablelist>
 230       <varlistentry>
 231         <term><option>--help</option></term>
 232         <term><option>-h</option></term>
 233
 234         <listitem><para>Print a short help
 235         text and exit.</para></listitem>
 236       </varlistentry>
 237
 238       <varlistentry>
 239         <term><option>--version</option></term>
 240
 241         <listitem><para>Print a short version
 242         string and exit.</para></listitem>
 243       </varlistentry>
 244
 245       <varlistentry>
 246         <term><option>--compress</option></term>
 247         <term><option>--no-compress</option></term>
 248
 249         <listitem><para>Compress or not, respectively, the data in the
 250         journal using XZ.</para></listitem>
 251       </varlistentry>
 252
 253       <varlistentry>
 254         <term><option>--seal</option></term>
 255         <term><option>--no-seal</option></term>
 256
 257         <listitem><para>Periodically sign or not, respectively, the
 258         data in the journal using Forward Secure Sealing.
 259         </para></listitem>
 260       </varlistentry>
 261
 262       <varlistentry>
 263         <term><option>--getter=<replaceable>PROG --option1 --option2</replaceable></option></term>
 264
 265         <listitem><para>Program to invoke to retrieve data. Journal
 266         event stream must be generated on standard output.</para>
 267
 268         <para>Examples:</para>
 269
 270         <programlisting>--getter='curl "-HAccept: application/vnd.fdo.journal" https://some.host:19531/'</programlisting>
 271
 272         <programlisting>--getter='wget --header="Accept: application/vnd.fdo.journal" -O- https://some.host:19531/'</programlisting>
 273         </listitem>
 274       </varlistentry>
 275     </variablelist>
 276   </refsect1>
 277
 278   <refsect1>
 279     <title>Examples</title>
 280     <para>Copy local journal events to a different journal directory:
 281     <programlisting>
 282 journalctl -o export | systemd-journal-remote -o /tmp/dir -
 283     </programlisting>
 284     </para>
 285
 286     <para>Retrieve events from a remote
 287     <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 288     instance and store them in
 289     <filename>/var/log/journal/some.host/remote-some~host.journal</filename>:
 290     <programlisting>
 291 systemd-journal-remote --url http://some.host:19531/
 292     </programlisting>
 293     </para>
 294   </refsect1>
 295
 296   <refsect1>
 297     <title>See Also</title>
 298     <para>
 299       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 300       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 301       <citerefentry><refentrytitle>systemd-journal-gatewayd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 302     </para>
 303   </refsect1>
 304 </refentry>