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">
6 This file is part of systemd.
8 Copyright 2012 Zbigniew Jędrzejewski-Szmek
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.
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.
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/>.
24 <refentry id="systemd-journal-remote" conditional='HAVE_MICROHTTPD'>
27 <title>systemd-journal-remote</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Zbigniew</firstname>
34 <surname>Jędrzejewski-Szmek</surname>
35 <email>zbyszek@in.waw.pl</email>
41 <refentrytitle>systemd-journal-remote</refentrytitle>
42 <manvolnum>8</manvolnum>
46 <refname>systemd-journal-remote</refname>
47 <refpurpose>Stream journal messages over the network</refpurpose>
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>
60 <title>Description</title>
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">
69 i.e. like the output from
70 <command>journalctl --output=export</command>.
75 <title>Sources</title>
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).
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).
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.
101 <para>Active sources can be specified in the following
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>
113 <term><option>--url=<replaceable>ADDRESS</replaceable></option></term>
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
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>
126 <para>Passive sources can be specified in the following
131 <term><option>--listen-raw=<replaceable>ADDRESS</replaceable></option></term>
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>
143 <term><option>--listen-http=<replaceable>ADDRESS</replaceable></option></term>
144 <term><option>--listen-https=<replaceable>ADDRESS</replaceable></option></term>
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>
158 <term><varname>$LISTEN_FDS</varname></term>
160 <listitem><para><command>systemd-journal-remote</command>
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.
176 <para>The location of the output journal can be specified
177 with <option>-o</option> or <option>--output=</option>.
182 <term><option>--output=<replaceable>FILE</replaceable></option></term>
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>
193 <term><option>--output=<replaceable>DIR</replaceable></option></term>
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>
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>
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
225 <title>Options</title>
227 <para>The following options are understood:</para>
231 <term><option>--help</option></term>
232 <term><option>-h</option></term>
234 <listitem><para>Print a short help
235 text and exit.</para></listitem>
239 <term><option>--version</option></term>
241 <listitem><para>Print a short version
242 string and exit.</para></listitem>
246 <term><option>--compress</option></term>
247 <term><option>--no-compress</option></term>
249 <listitem><para>Compress or not, respectively, the data in the
250 journal using XZ.</para></listitem>
254 <term><option>--seal</option></term>
255 <term><option>--no-seal</option></term>
257 <listitem><para>Periodically sign or not, respectively, the
258 data in the journal using Forward Secure Sealing.
263 <term><option>--getter=<replaceable>PROG --option1 --option2</replaceable></option></term>
265 <listitem><para>Program to invoke to retrieve data. Journal
266 event stream must be generated on standard output.</para>
268 <para>Examples:</para>
270 <programlisting>--getter='curl "-HAccept: application/vnd.fdo.journal" https://some.host:19531/'</programlisting>
272 <programlisting>--getter='wget --header="Accept: application/vnd.fdo.journal" -O- https://some.host:19531/'</programlisting>
279 <title>Examples</title>
280 <para>Copy local journal events to a different journal directory:
282 journalctl -o export | systemd-journal-remote -o /tmp/dir -
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>:
291 systemd-journal-remote --url http://some.host:19531/
297 <title>See Also</title>
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>.