1<?xml version='1.0'?>
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" >
5%entities;
6]>
7<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
8
9<refentry id="systemd-journal-remote" conditional='HAVE_MICROHTTPD'
10          xmlns:xi="http://www.w3.org/2001/XInclude">
11
12  <refentryinfo>
13    <title>systemd-journal-remote.service</title>
14    <productname>systemd</productname>
15  </refentryinfo>
16
17  <refmeta>
18    <refentrytitle>systemd-journal-remote.service</refentrytitle>
19    <manvolnum>8</manvolnum>
20  </refmeta>
21
22  <refnamediv>
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>
27  </refnamediv>
28
29  <refsynopsisdiv>
30    <para><filename>systemd-journal-remote.service</filename></para>
31    <para><filename>systemd-journal-remote.socket</filename></para>
32    <cmdsynopsis>
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>
37    </cmdsynopsis>
38  </refsynopsisdiv>
39
40  <refsect1>
41    <title>Description</title>
42
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://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format">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>
48
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>
56  </refsect1>
57
58  <refsect1>
59    <title>Sources</title>
60
61    <para>
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).
67    </para>
68
69    <para>
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).
77    </para>
78
79    <para>
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.
83    </para>
84
85    <para>Active sources can be specified in the following
86    ways:</para>
87
88    <variablelist>
89      <varlistentry>
90        <term><arg choice="opt" rep="repeat">SOURCES</arg></term>
91
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>
96      </varlistentry>
97
98      <varlistentry>
99        <term><option>--url=<replaceable>ADDRESS</replaceable></option></term>
100
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
105        root of a remote
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>
109      </varlistentry>
110
111      <varlistentry>
112        <term><option>--getter='<replaceable>PROG</replaceable> <arg choice="opt" rep="repeat">OPTIONS</arg>'</option></term>
113
114        <listitem><para>Program to invoke to retrieve data. The journal
115        event stream must be generated on standard output.</para>
116
117        <para>Examples:</para>
118
119        <programlisting>--getter='curl "-HAccept: application/vnd.fdo.journal" https://some.host:19531/'</programlisting>
120
121        <programlisting>--getter='wget --header="Accept: application/vnd.fdo.journal" -O- https://some.host:19531/'</programlisting>
122        </listitem>
123      </varlistentry>
124    </variablelist>
125
126    <para>Passive sources can be specified in the following
127    ways:</para>
128
129    <variablelist>
130      <varlistentry>
131        <term><option>--listen-raw=<replaceable>ADDRESS</replaceable></option></term>
132
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>
139        </listitem>
140      </varlistentry>
141
142      <varlistentry>
143        <term><option>--listen-http=<replaceable>ADDRESS</replaceable></option></term>
144        <term><option>--listen-https=<replaceable>ADDRESS</replaceable></option></term>
145
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>
159        </listitem>
160      </varlistentry>
161
162      <varlistentry>
163        <term><varname>$LISTEN_FDS</varname></term>
164
165        <listitem><para><command>systemd-journal-remote</command>
166        supports the
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>
172        or
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>
177        </listitem>
178      </varlistentry>
179
180      <varlistentry>
181        <term><option>--key=</option></term>
182
183        <listitem><para>Takes a path to a SSL secret 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>
187      </varlistentry>
188
189      <varlistentry>
190        <term><option>--cert=</option></term>
191
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>
196      </varlistentry>
197
198      <varlistentry>
199        <term><option>--trust=</option></term>
200
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>
206      </varlistentry>
207
208      <varlistentry>
209        <term><option>--gnutls-log=</option></term>
210
211        <listitem><para>
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>.
215        </para></listitem>
216      </varlistentry>
217
218    </variablelist>
219  </refsect1>
220
221  <refsect1>
222    <title>Sinks</title>
223
224    <para>The location of the output journal can be specified
225    with <option>-o</option> or <option>--output=</option>.
226    </para>
227
228    <variablelist>
229      <varlistentry>
230        <term><option>--output=<replaceable>FILE</replaceable></option></term>
231
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>
238      </varlistentry>
239
240      <varlistentry>
241        <term><option>--output=<replaceable>DIR</replaceable></option></term>
242
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>
249      </varlistentry>
250    </variablelist>
251
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
256    called
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>
261
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>
265  </refsect1>
266
267  <refsect1>
268    <title>Options</title>
269
270    <para>The following options are understood:</para>
271
272    <variablelist>
273      <varlistentry>
274        <term><option>--split-mode</option></term>
275
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
280        connection.</para>
281
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>
286      </varlistentry>
287
288      <varlistentry>
289        <term><option>--compress</option> [<replaceable>BOOL</replaceable>]</term>
290
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>.
293        </para></listitem>
294      </varlistentry>
295
296      <varlistentry>
297        <term><option>--seal</option> [<replaceable>BOOL</replaceable>]</term>
298
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>
302      </varlistentry>
303
304      <xi:include href="standard-options.xml" xpointer="help" />
305      <xi:include href="standard-options.xml" xpointer="version" />
306    </variablelist>
307  </refsect1>
308
309  <refsect1>
310    <title>Examples</title>
311    <para>Copy local journal events to a different journal directory:
312    <programlisting>
313journalctl -o export | systemd-journal-remote -o /tmp/dir/foo.journal -
314    </programlisting>
315    </para>
316
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>:
321    <programlisting>
322systemd-journal-remote --url http://some.host:19531/
323    </programlisting>
324    </para>
325
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>:
330    <programlisting>
331systemd-journal-remote --url http://some.host:19531/entries?boot&amp;follow
332    </programlisting>
333    </para>
334</refsect1>
335
336  <refsect1>
337    <title>See Also</title>
338    <para>
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>
344    </para>
345  </refsect1>
346</refentry>
347