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>
183 <listitem><para> Takes a path to a SSL key file in PEM format. Defaults to
184 <filename>&CERTIFICATE_ROOT;/private/journal-remote.pem
</filename>. This option can be used with
185 <option>--listen-https=
</option>. If the path refers to an
<constant>AF_UNIX
</constant> stream socket
186 in the file system a connection is made to it and the key read from it.
</para></listitem>
190 <term><option>--cert=
</option></term>
192 <listitem><para> Takes a path to a SSL certificate file in PEM format. Defaults to
193 <filename>&CERTIFICATE_ROOT;/certs/journal-remote.pem
</filename>. This option can be used with
194 <option>--listen-https=
</option>. If the path refers to an
<constant>AF_UNIX
</constant> stream socket
195 in the file system a connection is made to it and the certificate read from it.
</para></listitem>
199 <term><option>--trust=
</option></term>
201 <listitem><para> Takes a path to a SSL CA certificate file in PEM format, or
<option>all
</option>. If
202 <option>all
</option> is set, then certificate checking will be disabled. Defaults to
203 <filename>&CERTIFICATE_ROOT;/ca/trusted.pem
</filename>. This option can be used with
204 <option>--listen-https=
</option>. If the path refers to an
<constant>AF_UNIX
</constant> stream socket
205 in the file system a connection is made to it and the certificate read from it.
</para></listitem>
209 <term><option>--gnutls-log=
</option></term>
212 Takes a comma separated list of gnutls logging categories.
213 This option can be used with
<option>--listen-http=
</option> or
214 <option>--listen-https=
</option>.
224 <para>The location of the output journal can be specified
225 with
<option>-o
</option> or
<option>--output=
</option>.
230 <term><option>--output=
<replaceable>FILE
</replaceable></option></term>
232 <listitem><para>Will write to this journal file. The filename
233 must end with
<filename>.journal
</filename>. The file will be
234 created if it does not exist. If necessary (journal file full,
235 or corrupted), the file will be renamed following normal
236 journald rules and a new journal file will be created in its
237 stead.
</para></listitem>
241 <term><option>--output=
<replaceable>DIR
</replaceable></option></term>
243 <listitem><para>Will create journal files underneath directory
244 <replaceable>DIR
</replaceable>. The directory must exist. If
245 necessary (journal files over size, or corrupted), journal
246 files will be rotated following normal journald rules. Names
247 of files underneath
<replaceable>DIR
</replaceable> will be
248 generated using the rules described below.
</para></listitem>
252 <para>If
<option>--output=
</option> is not used, the output
253 directory
<filename>/var/log/journal/remote/
</filename> will be
254 used. In case the output file is not specified, journal files
255 will be created underneath the selected directory. Files will be
257 <filename>remote-
<replaceable>hostname
</replaceable>.journal
</filename>,
258 where the
<replaceable>hostname
</replaceable> part is the
259 escaped hostname of the source endpoint of the connection, or the
260 numerical address if the hostname cannot be determined.
</para>
262 <para>In the case that
"active" sources are given by the positional
263 arguments or
<option>--getter=
</option> option, the output file name
264 must always be given explicitly.
</para>
268 <title>Options
</title>
270 <para>The following options are understood:
</para>
274 <term><option>--split-mode
</option></term>
276 <listitem><para>One of
<constant>none
</constant> or
277 <constant>host
</constant>. For the first, only one output
278 journal file is used. For the latter, a separate output file
279 is used, based on the hostname of the other endpoint of a
282 <para>In the case that
"active" sources are given by the positional
283 arguments or
<option>--getter=
</option> option, the output file name must
284 always be given explicitly and only
<constant>none
</constant>
285 is allowed.
</para></listitem>
289 <term><option>--compress
</option> [
<replaceable>BOOL
</replaceable>]
</term>
291 <listitem><para>If this is set to
<literal>yes
</literal> then compress
292 the data in the journal using XZ. The default is
<literal>yes
</literal>.
297 <term><option>--seal
</option> [
<replaceable>BOOL
</replaceable>]
</term>
299 <listitem><para>If this is set to
<literal>yes
</literal> then
300 periodically sign the data in the journal using Forward Secure Sealing.
301 The default is
<literal>no
</literal>.
</para></listitem>
304 <xi:include href=
"standard-options.xml" xpointer=
"help" />
305 <xi:include href=
"standard-options.xml" xpointer=
"version" />
310 <title>Examples
</title>
311 <para>Copy local journal events to a different journal directory:
313 journalctl -o export | systemd-journal-remote -o /tmp/dir/foo.journal -
317 <para>Retrieve all available events from a remote
318 <citerefentry><refentrytitle>systemd-journal-gatewayd
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
319 instance and store them in
320 <filename>/var/log/journal/remote/remote-some.host.journal
</filename>:
322 systemd-journal-remote --url http://some.host:
19531/
326 <para>Retrieve current boot events and wait for new events from a remote
327 <citerefentry><refentrytitle>systemd-journal-gatewayd
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
328 instance, and store them in
329 <filename>/var/log/journal/remote/remote-some.host.journal
</filename>:
331 systemd-journal-remote --url http://some.host:
19531/entries?boot
&follow
337 <title>See Also
</title>
339 <citerefentry><refentrytitle>journal-remote.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
340 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
341 <citerefentry><refentrytitle>systemd-journal-gatewayd.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
342 <citerefentry><refentrytitle>systemd-journal-upload.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
343 <citerefentry><refentrytitle>systemd-journald.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>