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+
12 <refentry id=
"systemd-journal-remote" conditional='HAVE_MICROHTTPD'
13 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
16 <title>systemd-journal-remote.service
</title>
17 <productname>systemd
</productname>
21 <refentrytitle>systemd-journal-remote.service
</refentrytitle>
22 <manvolnum>8</manvolnum>
26 <refname>systemd-journal-remote.service
</refname>
27 <refname>systemd-journal-remote.socket
</refname>
28 <refname>systemd-journal-remote
</refname>
29 <refpurpose>Receive journal messages over the network
</refpurpose>
33 <para><filename>systemd-journal-remote.service
</filename></para>
34 <para><filename>systemd-journal-remote.socket
</filename></para>
36 <command>/usr/lib/systemd/systemd-journal-remote
</command>
37 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
38 <arg choice=
"opt" rep=
"norepeat">-o/--output=
<replaceable>DIR
</replaceable>|
<replaceable>FILE
</replaceable></arg>
39 <arg choice=
"opt" rep=
"repeat">SOURCES
</arg>
44 <title>Description
</title>
46 <para><command>systemd-journal-remote
</command> is a command to receive serialized journal
47 events and store them to journal files. Input streams are in the
48 <ulink url=
"https://www.freedesktop.org/wiki/Software/systemd/export">Journal Export Format
</ulink>,
49 i.e. like the output from
<command>journalctl --output=export
</command>. For transport over the
50 network, this serialized stream is usually carried over an HTTPS connection.
</para>
52 <para><filename>systemd-journal-remote.service
</filename> is a system service that uses
53 <command>systemd-journal-remote
</command> to listen for connections.
54 <filename>systemd-journal-remote.socket
</filename> configures the network address that
55 <filename>systemd-journal-remote.service
</filename> listens on. By default this is port
19532.
56 What connections are accepted and how the received data is stored can be configured through the
57 <citerefentry><refentrytitle>journal-remote.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
58 configuration file.
</para>
62 <title>Sources
</title>
65 Sources can be either
"active"
66 (
<command>systemd-journal-remote
</command> requests and pulls
67 the data), or
"passive"
68 (
<command>systemd-journal-remote
</command> waits for a
69 connection and then receives events pushed by the other side).
73 <command>systemd-journal-remote
</command> can read more than one
74 event stream at a time. They will be interleaved in the output
75 file. In case of
"active" connections, each
"source" is one
76 stream, and in case of
"passive" connections, each connection can
77 result in a separate stream. Sockets can be configured in
78 "accept" mode (i.e. only one connection), or
"listen" mode (i.e.
79 multiple connections, each resulting in a stream).
83 When there are no more connections, and no more can be created
84 (there are no listening sockets), then
85 <command>systemd-journal-remote
</command> will exit.
88 <para>Active sources can be specified in the following
93 <term><arg choice=
"opt" rep=
"repeat">SOURCES
</arg></term>
95 <listitem><para>When
<option>-
</option> is given as a
96 positional argument, events will be read from standard input.
97 Other positional arguments will be treated as filenames
98 to open and read from.
</para></listitem>
102 <term><option>--url=
<replaceable>ADDRESS
</replaceable></option></term>
104 <listitem><para>With the
105 <option>--url=
<replaceable>ADDRESS
</replaceable></option> option,
106 events will be retrieved using HTTP from
107 <replaceable>ADDRESS
</replaceable>. This URL should refer to the
109 <citerefentry><refentrytitle>systemd-journal-gatewayd
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
110 instance, e.g. http://some.host:
19531/ or
111 https://some.host:
19531/.
</para></listitem>
115 <term><option>--getter='
<replaceable>PROG
</replaceable> <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>'
</option></term>
117 <listitem><para>Program to invoke to retrieve data. The journal
118 event stream must be generated on standard output.
</para>
120 <para>Examples:
</para>
122 <programlisting>--getter='curl
"-HAccept: application/vnd.fdo.journal" https://some.host:
19531/'
</programlisting>
124 <programlisting>--getter='wget
--header=
"Accept: application/vnd.fdo.journal" -O- https://some.host:
19531/'
</programlisting>
129 <para>Passive sources can be specified in the following
134 <term><option>--listen-raw=
<replaceable>ADDRESS
</replaceable></option></term>
136 <listitem><para><replaceable>ADDRESS
</replaceable> must be an
137 address suitable for
<option>ListenStream=
</option> (cf.
138 <citerefentry><refentrytitle>systemd.socket
</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
139 <command>systemd-journal-remote
</command> will listen on this
140 socket for connections. Each connection is expected to be a
141 stream of journal events.
</para>
146 <term><option>--listen-http=
<replaceable>ADDRESS
</replaceable></option></term>
147 <term><option>--listen-https=
<replaceable>ADDRESS
</replaceable></option></term>
149 <listitem><para><replaceable>ADDRESS
</replaceable> must be
150 either a negative integer, in which case it will be
151 interpreted as the (negated) file descriptor number, or an
152 address suitable for
<option>ListenStream=
</option> (c.f.
153 <citerefentry><refentrytitle>systemd.socket
</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
154 In the first case, the server listens on port
19532 by default,
155 and the matching file descriptor must be inherited through
156 <varname>$LISTEN_FDS
</varname>/
<varname>$LISTEN_PID
</varname>.
157 In the second case, an HTTP or HTTPS server will be spawned on
158 this port, respectively for
<option>--listen-http=
</option> and
159 <option>--listen-https=
</option>. Currently, only POST requests
160 to
<filename>/upload
</filename> with
<literal>Content-Type:
161 application/vnd.fdo.journal
</literal> are supported.
</para>
166 <term><varname>$LISTEN_FDS
</varname></term>
168 <listitem><para><command>systemd-journal-remote
</command>
170 <varname>$LISTEN_FDS
</varname>/
<varname>$LISTEN_PID
</varname>
171 protocol. Open sockets inherited through socket activation
172 behave like those opened with
<option>--listen-raw=
</option>
173 described above, unless they are specified as an argument in
174 <option>--listen-http=-
<replaceable>n
</replaceable></option>
176 <option>--listen-https=-
<replaceable>n
</replaceable></option>
177 above. In the latter case, an HTTP or HTTPS server will be
178 spawned using this descriptor and connections must be made
179 over the HTTP protocol.
</para>
184 <term><option>--key=
</option></term>
187 Takes a path to a SSL key file in PEM format.
188 Defaults to
<filename>&CERTIFICATE_ROOT;/private/journal-remote.pem
</filename>.
189 This option can be used with
<option>--listen-https=
</option>.
194 <term><option>--cert=
</option></term>
197 Takes a path to a SSL certificate file in PEM format.
198 Defaults to
<filename>&CERTIFICATE_ROOT;/certs/journal-remote.pem
</filename>.
199 This option can be used with
<option>--listen-https=
</option>.
204 <term><option>--trust=
</option></term>
207 Takes a path to a SSL CA certificate file in PEM format,
208 or
<option>all
</option>. If
<option>all
</option> is set,
209 then certificate checking will be disabled.
210 Defaults to
<filename>&CERTIFICATE_ROOT;/ca/trusted.pem
</filename>.
211 This option can be used with
<option>--listen-https=
</option>.
216 <term><option>--gnutls-log=
</option></term>
219 Takes a comma separated list of gnutls logging categories.
220 This option can be used with
<option>--listen-http=
</option> or
221 <option>--listen-https=
</option>.
231 <para>The location of the output journal can be specified
232 with
<option>-o
</option> or
<option>--output=
</option>.
237 <term><option>--output=
<replaceable>FILE
</replaceable></option></term>
239 <listitem><para>Will write to this journal file. The filename
240 must end with
<filename>.journal
</filename>. The file will be
241 created if it does not exist. If necessary (journal file full,
242 or corrupted), the file will be renamed following normal
243 journald rules and a new journal file will be created in its
244 stead.
</para></listitem>
248 <term><option>--output=
<replaceable>DIR
</replaceable></option></term>
250 <listitem><para>Will create journal files underneath directory
251 <replaceable>DIR
</replaceable>. The directory must exist. If
252 necessary (journal files over size, or corrupted), journal
253 files will be rotated following normal journald rules. Names
254 of files underneath
<replaceable>DIR
</replaceable> will be
255 generated using the rules described below.
</para></listitem>
259 <para>If
<option>--output=
</option> is not used, the output
260 directory
<filename>/var/log/journal/remote/
</filename> will be
261 used. In case the output file is not specified, journal files
262 will be created underneath the selected directory. Files will be
264 <filename>remote-
<replaceable>hostname
</replaceable>.journal
</filename>,
265 where the
<replaceable>hostname
</replaceable> part is the
266 escaped hostname of the source endpoint of the connection, or the
267 numerical address if the hostname cannot be determined.
</para>
269 <para>In the case that
"active" sources are given by the positional
270 arguments or
<option>--getter=
</option> option, the output file name
271 must always be given explicitly.
</para>
275 <title>Options
</title>
277 <para>The following options are understood:
</para>
281 <term><option>--split-mode
</option></term>
283 <listitem><para>One of
<constant>none
</constant> or
284 <constant>host
</constant>. For the first, only one output
285 journal file is used. For the latter, a separate output file
286 is used, based on the hostname of the other endpoint of a
289 <para>In the case that
"active" sources are given by the positional
290 arguments or
<option>--getter=
</option> option, the output file name must
291 always be given explicitly and only
<constant>none
</constant>
292 is allowed.
</para></listitem>
296 <term><option>--compress
</option> [
<replaceable>BOOL
</replaceable>]
</term>
298 <listitem><para>If this is set to
<literal>yes
</literal> then compress
299 the data in the journal using XZ. The default is
<literal>yes
</literal>.
304 <term><option>--seal
</option> [
<replaceable>BOOL
</replaceable>]
</term>
306 <listitem><para>If this is set to
<literal>yes
</literal> then
307 periodically sign the data in the journal using Forward Secure Sealing.
308 The default is
<literal>no
</literal>.
</para></listitem>
311 <xi:include href=
"standard-options.xml" xpointer=
"help" />
312 <xi:include href=
"standard-options.xml" xpointer=
"version" />
317 <title>Examples
</title>
318 <para>Copy local journal events to a different journal directory:
320 journalctl -o export | systemd-journal-remote -o /tmp/dir/foo.journal -
324 <para>Retrieve all available events from a remote
325 <citerefentry><refentrytitle>systemd-journal-gatewayd
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
326 instance and store them in
327 <filename>/var/log/journal/remote/remote-some.host.journal
</filename>:
329 systemd-journal-remote --url http://some.host:
19531/
333 <para>Retrieve current boot events and wait for new events from a remote
334 <citerefentry><refentrytitle>systemd-journal-gatewayd
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
335 instance, and store them in
336 <filename>/var/log/journal/remote/remote-some.host.journal
</filename>:
338 systemd-journal-remote --url http://some.host:
19531/entries?boot
&follow
344 <title>See Also
</title>
346 <citerefentry><refentrytitle>journal-remote.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
347 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
348 <citerefentry><refentrytitle>systemd-journal-gatewayd.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
349 <citerefentry><refentrytitle>systemd-journal-upload.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
350 <citerefentry><refentrytitle>systemd-journald.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>