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