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 <!ENTITY % entities SYSTEM
"custom-entities.ent" >
9 SPDX-License-Identifier: LGPL-2.1+
11 Copyright © 2012 Zbigniew Jędrzejewski-Szmek
14 <refentry id=
"systemd-journal-remote" conditional='HAVE_MICROHTTPD'
15 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
18 <title>systemd-journal-remote.service
</title>
19 <productname>systemd
</productname>
23 <contrib>Developer
</contrib>
24 <firstname>Zbigniew
</firstname>
25 <surname>Jędrzejewski-Szmek
</surname>
26 <email>zbyszek@in.waw.pl
</email>
32 <refentrytitle>systemd-journal-remote.service
</refentrytitle>
33 <manvolnum>8</manvolnum>
37 <refname>systemd-journal-remote.service
</refname>
38 <refname>systemd-journal-remote.socket
</refname>
39 <refname>systemd-journal-remote
</refname>
40 <refpurpose>Receive journal messages over the network
</refpurpose>
44 <para><filename>systemd-journal-remote.service
</filename></para>
45 <para><filename>systemd-journal-remote.socket
</filename></para>
47 <command>/usr/lib/systemd/systemd-journal-remote
</command>
48 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
49 <arg choice=
"opt" rep=
"norepeat">-o/--output=
<replaceable>DIR
</replaceable>|
<replaceable>FILE
</replaceable></arg>
50 <arg choice=
"opt" rep=
"repeat">SOURCES
</arg>
55 <title>Description
</title>
57 <para><command>systemd-journal-remote
</command> is a command to receive serialized journal
58 events and store them to journal files. Input streams are in the
59 <ulink url=
"https://www.freedesktop.org/wiki/Software/systemd/export">Journal Export Format
</ulink>,
60 i.e. like the output from
<command>journalctl --output=export
</command>. For transport over the
61 network, this serialized stream is usually carried over an HTTPS connection.
</para>
63 <para><filename>systemd-journal-remote.service
</filename> is a system service that uses
64 <command>systemd-journal-remote
</command> to listen for connections.
65 <filename>systemd-journal-remote.socket
</filename> configures the network address that
66 <filename>systemd-journal-remote.service
</filename> listens on. By default this is port
19532.
67 What connections are accepted and how the received data is stored can be configured through the
68 <citerefentry><refentrytitle>journal-remote.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
69 configuration file.
</para>
73 <title>Sources
</title>
76 Sources can be either
"active"
77 (
<command>systemd-journal-remote
</command> requests and pulls
78 the data), or
"passive"
79 (
<command>systemd-journal-remote
</command> waits for a
80 connection and then receives events pushed by the other side).
84 <command>systemd-journal-remote
</command> can read more than one
85 event stream at a time. They will be interleaved in the output
86 file. In case of
"active" connections, each
"source" is one
87 stream, and in case of
"passive" connections, each connection can
88 result in a separate stream. Sockets can be configured in
89 "accept" mode (i.e. only one connection), or
"listen" mode (i.e.
90 multiple connections, each resulting in a stream).
94 When there are no more connections, and no more can be created
95 (there are no listening sockets), then
96 <command>systemd-journal-remote
</command> will exit.
99 <para>Active sources can be specified in the following
104 <term><arg choice=
"opt" rep=
"repeat">SOURCES
</arg></term>
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. http://some.host:
19531/ or
122 https://some.host:
19531/.
</para></listitem>
126 <term><option>--getter='
<replaceable>PROG
</replaceable> <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>'
</option></term>
128 <listitem><para>Program to invoke to retrieve data. The journal
129 event stream must be generated on standard output.
</para>
131 <para>Examples:
</para>
133 <programlisting>--getter='curl
"-HAccept: application/vnd.fdo.journal" https://some.host:
19531/'
</programlisting>
135 <programlisting>--getter='wget
--header=
"Accept: application/vnd.fdo.journal" -O- https://some.host:
19531/'
</programlisting>
140 <para>Passive sources can be specified in the following
145 <term><option>--listen-raw=
<replaceable>ADDRESS
</replaceable></option></term>
147 <listitem><para><replaceable>ADDRESS
</replaceable> must be an
148 address suitable for
<option>ListenStream=
</option> (cf.
149 <citerefentry><refentrytitle>systemd.socket
</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
150 <command>systemd-journal-remote
</command> will listen on this
151 socket for connections. Each connection is expected to be a
152 stream of journal events.
</para>
157 <term><option>--listen-http=
<replaceable>ADDRESS
</replaceable></option></term>
158 <term><option>--listen-https=
<replaceable>ADDRESS
</replaceable></option></term>
160 <listitem><para><replaceable>ADDRESS
</replaceable> must be
161 either a negative integer, in which case it will be
162 interpreted as the (negated) file descriptor number, or an
163 address suitable for
<option>ListenStream=
</option> (c.f.
164 <citerefentry><refentrytitle>systemd.socket
</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
165 In the first case, the server listens on port
19532 by default,
166 and the matching file descriptor must be inherited through
167 <varname>$LISTEN_FDS
</varname>/
<varname>$LISTEN_PID
</varname>.
168 In the second case, an HTTP or HTTPS server will be spawned on
169 this port, respectively for
<option>--listen-http=
</option> and
170 <option>--listen-https=
</option>. Currently, only POST requests
171 to
<filename>/upload
</filename> with
<literal>Content-Type:
172 application/vnd.fdo.journal
</literal> are supported.
</para>
177 <term><varname>$LISTEN_FDS
</varname></term>
179 <listitem><para><command>systemd-journal-remote
</command>
181 <varname>$LISTEN_FDS
</varname>/
<varname>$LISTEN_PID
</varname>
182 protocol. Open sockets inherited through socket activation
183 behave like those opened with
<option>--listen-raw=
</option>
184 described above, unless they are specified as an argument in
185 <option>--listen-http=-
<replaceable>n
</replaceable></option>
187 <option>--listen-https=-
<replaceable>n
</replaceable></option>
188 above. In the latter case, an HTTP or HTTPS server will be
189 spawned using this descriptor and connections must be made
190 over the HTTP protocol.
</para>
195 <term><option>--key=
</option></term>
198 Takes a path to a SSL key file in PEM format.
199 Defaults to
<filename>&CERTIFICATE_ROOT;/private/journal-remote.pem
</filename>.
200 This option can be used with
<option>--listen-https=
</option>.
205 <term><option>--cert=
</option></term>
208 Takes a path to a SSL certificate file in PEM format.
209 Defaults to
<filename>&CERTIFICATE_ROOT;/certs/journal-remote.pem
</filename>.
210 This option can be used with
<option>--listen-https=
</option>.
215 <term><option>--trust=
</option></term>
218 Takes a path to a SSL CA certificate file in PEM format,
219 or
<option>all
</option>. If
<option>all
</option> is set,
220 then certificate checking will be disabled.
221 Defaults to
<filename>&CERTIFICATE_ROOT;/ca/trusted.pem
</filename>.
222 This option can be used with
<option>--listen-https=
</option>.
227 <term><option>--gnutls-log=
</option></term>
230 Takes a comma separated list of gnutls logging categories.
231 This option can be used with
<option>--listen-http=
</option> or
232 <option>--listen-https=
</option>.
242 <para>The location of the output journal can be specified
243 with
<option>-o
</option> or
<option>--output=
</option>.
248 <term><option>--output=
<replaceable>FILE
</replaceable></option></term>
250 <listitem><para>Will write to this journal file. The filename
251 must end with
<filename>.journal
</filename>. The file will be
252 created if it does not exist. If necessary (journal file full,
253 or corrupted), the file will be renamed following normal
254 journald rules and a new journal file will be created in its
255 stead.
</para></listitem>
259 <term><option>--output=
<replaceable>DIR
</replaceable></option></term>
261 <listitem><para>Will create journal files underneath directory
262 <replaceable>DIR
</replaceable>. The directory must exist. If
263 necessary (journal files over size, or corrupted), journal
264 files will be rotated following normal journald rules. Names
265 of files underneath
<replaceable>DIR
</replaceable> will be
266 generated using the rules described below.
</para></listitem>
270 <para>If
<option>--output=
</option> is not used, the output
271 directory
<filename>/var/log/journal/remote/
</filename> will be
272 used. In case the output file is not specified, journal files
273 will be created underneath the selected directory. Files will be
275 <filename>remote-
<replaceable>hostname
</replaceable>.journal
</filename>,
276 where the
<replaceable>hostname
</replaceable> part is the
277 escaped hostname of the source endpoint of the connection, or the
278 numerical address if the hostname cannot be determined.
</para>
280 <para>In the case that
"active" sources are given by the positional
281 arguments or
<option>--getter=
</option> option, the output file name
282 must always be given explicitly.
</para>
286 <title>Options
</title>
288 <para>The following options are understood:
</para>
292 <term><option>--split-mode
</option></term>
294 <listitem><para>One of
<constant>none
</constant> or
295 <constant>host
</constant>. For the first, only one output
296 journal file is used. For the latter, a separate output file
297 is used, based on the hostname of the other endpoint of a
300 <para>In the case that
"active" sources are given by the positional
301 arguments or
<option>--getter=
</option> option, the output file name must
302 always be given explicitly and only
<constant>none
</constant>
303 is allowed.
</para></listitem>
307 <term><option>--compress
</option> [
<replaceable>BOOL
</replaceable>]
</term>
309 <listitem><para>If this is set to
<literal>yes
</literal> then compress
310 the data in the journal using XZ. The default is
<literal>yes
</literal>.
315 <term><option>--seal
</option> [
<replaceable>BOOL
</replaceable>]
</term>
317 <listitem><para>If this is set to
<literal>yes
</literal> then
318 periodically sign the data in the journal using Forward Secure Sealing.
319 The default is
<literal>no
</literal>.
</para></listitem>
322 <xi:include href=
"standard-options.xml" xpointer=
"help" />
323 <xi:include href=
"standard-options.xml" xpointer=
"version" />
328 <title>Examples
</title>
329 <para>Copy local journal events to a different journal directory:
331 journalctl -o export | systemd-journal-remote -o /tmp/dir/foo.journal -
335 <para>Retrieve all available events from a remote
336 <citerefentry><refentrytitle>systemd-journal-gatewayd
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
337 instance and store them in
338 <filename>/var/log/journal/remote/remote-some.host.journal
</filename>:
340 systemd-journal-remote --url http://some.host:
19531/
344 <para>Retrieve current boot events and wait for new events from a remote
345 <citerefentry><refentrytitle>systemd-journal-gatewayd
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
346 instance, and store them in
347 <filename>/var/log/journal/remote/remote-some.host.journal
</filename>:
349 systemd-journal-remote --url http://some.host:
19531/entries?boot
&follow
355 <title>See Also
</title>
357 <citerefentry><refentrytitle>journal-remote.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
358 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
359 <citerefentry><refentrytitle>systemd-journal-gatewayd.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
360 <citerefentry><refentrytitle>systemd-journal-upload.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
361 <citerefentry><refentrytitle>systemd-journald.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>