2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY % entities SYSTEM
"custom-entities.ent" >
7 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
9 <refentry id=
"systemd-journal-remote" conditional='HAVE_MICROHTTPD'
10 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
13 <title>systemd-journal-remote.service
</title>
14 <productname>systemd
</productname>
18 <refentrytitle>systemd-journal-remote.service
</refentrytitle>
19 <manvolnum>8</manvolnum>
23 <refname>systemd-journal-remote.service
</refname>
24 <refname>systemd-journal-remote.socket
</refname>
25 <refname>systemd-journal-remote
</refname>
26 <refpurpose>Receive journal messages over the network
</refpurpose>
30 <para><filename>systemd-journal-remote.service
</filename></para>
31 <para><filename>systemd-journal-remote.socket
</filename></para>
33 <command>/usr/lib/systemd/systemd-journal-remote
</command>
34 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
35 <arg choice=
"opt" rep=
"norepeat">-o/--output=
<replaceable>DIR
</replaceable>|
<replaceable>FILE
</replaceable></arg>
36 <arg choice=
"opt" rep=
"repeat">SOURCES
</arg>
41 <title>Description
</title>
43 <para><command>systemd-journal-remote
</command> is a command to receive serialized journal
44 events and store them to journal files. Input streams are in the
45 <ulink url=
"https://www.freedesktop.org/wiki/Software/systemd/export">Journal Export Format
</ulink>,
46 i.e. like the output from
<command>journalctl --output=export
</command>. For transport over the
47 network, this serialized stream is usually carried over an HTTPS connection.
</para>
49 <para><filename>systemd-journal-remote.service
</filename> is a system service that uses
50 <command>systemd-journal-remote
</command> to listen for connections.
51 <filename>systemd-journal-remote.socket
</filename> configures the network address that
52 <filename>systemd-journal-remote.service
</filename> listens on. By default this is port
19532.
53 What connections are accepted and how the received data is stored can be configured through the
54 <citerefentry><refentrytitle>journal-remote.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
55 configuration file.
</para>
59 <title>Sources
</title>
62 Sources can be either
"active"
63 (
<command>systemd-journal-remote
</command> requests and pulls
64 the data), or
"passive"
65 (
<command>systemd-journal-remote
</command> waits for a
66 connection and then receives events pushed by the other side).
70 <command>systemd-journal-remote
</command> can read more than one
71 event stream at a time. They will be interleaved in the output
72 file. In case of
"active" connections, each
"source" is one
73 stream, and in case of
"passive" connections, each connection can
74 result in a separate stream. Sockets can be configured in
75 "accept" mode (i.e. only one connection), or
"listen" mode (i.e.
76 multiple connections, each resulting in a stream).
80 When there are no more connections, and no more can be created
81 (there are no listening sockets), then
82 <command>systemd-journal-remote
</command> will exit.
85 <para>Active sources can be specified in the following
90 <term><arg choice=
"opt" rep=
"repeat">SOURCES
</arg></term>
92 <listitem><para>When
<option>-
</option> is given as a
93 positional argument, events will be read from standard input.
94 Other positional arguments will be treated as filenames
95 to open and read from.
</para></listitem>
99 <term><option>--url=
<replaceable>ADDRESS
</replaceable></option></term>
101 <listitem><para>With the
102 <option>--url=
<replaceable>ADDRESS
</replaceable></option> option,
103 events will be retrieved using HTTP from
104 <replaceable>ADDRESS
</replaceable>. This URL should refer to the
106 <citerefentry><refentrytitle>systemd-journal-gatewayd
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
107 instance, e.g. http://some.host:
19531/ or
108 https://some.host:
19531/.
</para></listitem>
112 <term><option>--getter='
<replaceable>PROG
</replaceable> <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>'
</option></term>
114 <listitem><para>Program to invoke to retrieve data. The journal
115 event stream must be generated on standard output.
</para>
117 <para>Examples:
</para>
119 <programlisting>--getter='curl
"-HAccept: application/vnd.fdo.journal" https://some.host:
19531/'
</programlisting>
121 <programlisting>--getter='wget
--header=
"Accept: application/vnd.fdo.journal" -O- https://some.host:
19531/'
</programlisting>
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> (cf.
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
147 either a negative integer, in which case it will be
148 interpreted as the (negated) file descriptor number, or an
149 address suitable for
<option>ListenStream=
</option> (c.f.
150 <citerefentry><refentrytitle>systemd.socket
</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
151 In the first case, the server listens on port
19532 by default,
152 and the matching file descriptor must be inherited through
153 <varname>$LISTEN_FDS
</varname>/
<varname>$LISTEN_PID
</varname>.
154 In the second case, an HTTP or HTTPS server will be spawned on
155 this port, respectively for
<option>--listen-http=
</option> and
156 <option>--listen-https=
</option>. Currently, only POST requests
157 to
<filename>/upload
</filename> with
<literal>Content-Type:
158 application/vnd.fdo.journal
</literal> are supported.
</para>
163 <term><varname>$LISTEN_FDS
</varname></term>
165 <listitem><para><command>systemd-journal-remote
</command>
167 <varname>$LISTEN_FDS
</varname>/
<varname>$LISTEN_PID
</varname>
168 protocol. Open sockets inherited through socket activation
169 behave like those opened with
<option>--listen-raw=
</option>
170 described above, unless they are specified as an argument in
171 <option>--listen-http=-
<replaceable>n
</replaceable></option>
173 <option>--listen-https=-
<replaceable>n
</replaceable></option>
174 above. In the latter case, an HTTP or HTTPS server will be
175 spawned using this descriptor and connections must be made
176 over the HTTP protocol.
</para>
181 <term><option>--key=
</option></term>
184 Takes a path to a SSL key file in PEM format.
185 Defaults to
<filename>&CERTIFICATE_ROOT;/private/journal-remote.pem
</filename>.
186 This option can be used with
<option>--listen-https=
</option>.
191 <term><option>--cert=
</option></term>
194 Takes a path to a SSL certificate file in PEM format.
195 Defaults to
<filename>&CERTIFICATE_ROOT;/certs/journal-remote.pem
</filename>.
196 This option can be used with
<option>--listen-https=
</option>.
201 <term><option>--trust=
</option></term>
204 Takes a path to a SSL CA certificate file in PEM format,
205 or
<option>all
</option>. If
<option>all
</option> is set,
206 then certificate checking will be disabled.
207 Defaults to
<filename>&CERTIFICATE_ROOT;/ca/trusted.pem
</filename>.
208 This option can be used with
<option>--listen-https=
</option>.
213 <term><option>--gnutls-log=
</option></term>
216 Takes a comma separated list of gnutls logging categories.
217 This option can be used with
<option>--listen-http=
</option> or
218 <option>--listen-https=
</option>.
228 <para>The location of the output journal can be specified
229 with
<option>-o
</option> or
<option>--output=
</option>.
234 <term><option>--output=
<replaceable>FILE
</replaceable></option></term>
236 <listitem><para>Will write to this journal file. The filename
237 must end with
<filename>.journal
</filename>. The file will be
238 created if it does not exist. If necessary (journal file full,
239 or corrupted), the file will be renamed following normal
240 journald rules and a new journal file will be created in its
241 stead.
</para></listitem>
245 <term><option>--output=
<replaceable>DIR
</replaceable></option></term>
247 <listitem><para>Will create journal files underneath directory
248 <replaceable>DIR
</replaceable>. The directory must exist. If
249 necessary (journal files over size, or corrupted), journal
250 files will be rotated following normal journald rules. Names
251 of files underneath
<replaceable>DIR
</replaceable> will be
252 generated using the rules described below.
</para></listitem>
256 <para>If
<option>--output=
</option> is not used, the output
257 directory
<filename>/var/log/journal/remote/
</filename> will be
258 used. In case the output file is not specified, journal files
259 will be created underneath the selected directory. Files will be
261 <filename>remote-
<replaceable>hostname
</replaceable>.journal
</filename>,
262 where the
<replaceable>hostname
</replaceable> part is the
263 escaped hostname of the source endpoint of the connection, or the
264 numerical address if the hostname cannot be determined.
</para>
266 <para>In the case that
"active" sources are given by the positional
267 arguments or
<option>--getter=
</option> option, the output file name
268 must always be given explicitly.
</para>
272 <title>Options
</title>
274 <para>The following options are understood:
</para>
278 <term><option>--split-mode
</option></term>
280 <listitem><para>One of
<constant>none
</constant> or
281 <constant>host
</constant>. For the first, only one output
282 journal file is used. For the latter, a separate output file
283 is used, based on the hostname of the other endpoint of a
286 <para>In the case that
"active" sources are given by the positional
287 arguments or
<option>--getter=
</option> option, the output file name must
288 always be given explicitly and only
<constant>none
</constant>
289 is allowed.
</para></listitem>
293 <term><option>--compress
</option> [
<replaceable>BOOL
</replaceable>]
</term>
295 <listitem><para>If this is set to
<literal>yes
</literal> then compress
296 the data in the journal using XZ. The default is
<literal>yes
</literal>.
301 <term><option>--seal
</option> [
<replaceable>BOOL
</replaceable>]
</term>
303 <listitem><para>If this is set to
<literal>yes
</literal> then
304 periodically sign the data in the journal using Forward Secure Sealing.
305 The default is
<literal>no
</literal>.
</para></listitem>
308 <xi:include href=
"standard-options.xml" xpointer=
"help" />
309 <xi:include href=
"standard-options.xml" xpointer=
"version" />
314 <title>Examples
</title>
315 <para>Copy local journal events to a different journal directory:
317 journalctl -o export | systemd-journal-remote -o /tmp/dir/foo.journal -
321 <para>Retrieve all available events from a remote
322 <citerefentry><refentrytitle>systemd-journal-gatewayd
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
323 instance and store them in
324 <filename>/var/log/journal/remote/remote-some.host.journal
</filename>:
326 systemd-journal-remote --url http://some.host:
19531/
330 <para>Retrieve current boot events and wait for new events from a remote
331 <citerefentry><refentrytitle>systemd-journal-gatewayd
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
332 instance, and store them in
333 <filename>/var/log/journal/remote/remote-some.host.journal
</filename>:
335 systemd-journal-remote --url http://some.host:
19531/entries?boot
&follow
341 <title>See Also
</title>
343 <citerefentry><refentrytitle>journal-remote.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
344 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
345 <citerefentry><refentrytitle>systemd-journal-gatewayd.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
346 <citerefentry><refentrytitle>systemd-journal-upload.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
347 <citerefentry><refentrytitle>systemd-journald.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>