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-upload" conditional='HAVE_MICROHTTPD'
10          xmlns:xi="http://www.w3.org/2001/XInclude">
11
12  <refentryinfo>
13    <title>systemd-journal-upload.service</title>
14    <productname>systemd</productname>
15  </refentryinfo>
16
17  <refmeta>
18    <refentrytitle>systemd-journal-upload.service</refentrytitle>
19    <manvolnum>8</manvolnum>
20  </refmeta>
21
22  <refnamediv>
23    <refname>systemd-journal-upload.service</refname>
24    <refname>systemd-journal-upload</refname>
25    <refpurpose>Send journal messages over the network</refpurpose>
26  </refnamediv>
27
28  <refsynopsisdiv>
29    <para><filename>systemd-journal-upload.service</filename></para>
30    <cmdsynopsis>
31      <command>/usr/lib/systemd/systemd-journal-upload</command>
32      <arg choice="opt" rep="repeat">OPTIONS</arg>
33      <arg choice="opt" rep="norepeat">-u/--url=<replaceable>URL</replaceable></arg>
34      <arg choice="opt" rep="repeat">SOURCES</arg>
35    </cmdsynopsis>
36  </refsynopsisdiv>
37
38  <refsect1>
39    <title>Description</title>
40
41    <para><command>systemd-journal-upload</command> will upload journal entries to the URL specified
42    with <option>--url=</option>. This program reads journal entries from one or more journal files,
43    similarly to
44    <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
45    Unless limited by one of the options specified below, all journal entries accessible to the user
46    the program is running as will be uploaded, and then the program will wait and send new entries
47    as they become available.</para>
48
49    <para><command>systemd-journal-upload</command> transfers the raw content of journal file and
50    uses HTTP as a transport protocol.</para>
51
52    <para><filename>systemd-journal-upload.service</filename> is a system service that uses
53    <command>systemd-journal-upload</command> to upload journal entries to a server. It uses the
54    configuration in
55    <citerefentry><refentrytitle>journal-upload.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
56    At least the <varname>URL=</varname> option must be specified.</para>
57  </refsect1>
58
59  <refsect1>
60    <title>Options</title>
61
62    <variablelist>
63      <varlistentry>
64        <term><option>-u</option></term>
65        <term><option>--url=<optional>https://</optional><replaceable>URL</replaceable>[:<replaceable>PORT</replaceable>]</option></term>
66        <term><option>--url=<optional>http://</optional><replaceable>URL</replaceable>[:<replaceable>PORT</replaceable>]</option></term>
67
68        <listitem><para>Upload to the specified
69        address. <replaceable>URL</replaceable> may specify either
70        just the hostname or both the protocol and
71        hostname. <constant>https</constant> is the default.
72        The port number may be specified after a colon (<literal>:</literal>),
73        otherwise <constant>19532</constant> will be used by default.
74        </para></listitem>
75      </varlistentry>
76
77      <varlistentry>
78        <term><option>--system</option></term>
79        <term><option>--user</option></term>
80
81        <listitem><para>Limit uploaded entries to entries from system
82        services and the kernel, or to entries from services of
83        current user. This has the same meaning as
84        <option>--system</option> and <option>--user</option> options
85        for
86        <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If
87        neither is specified, all accessible entries are uploaded.
88        </para></listitem>
89      </varlistentry>
90
91      <varlistentry>
92        <term><option>-m</option></term>
93        <term><option>--merge</option></term>
94
95        <listitem><para>Upload entries interleaved from all available
96        journals, including other machines. This has the same meaning
97        as <option>--merge</option> option for
98        <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
99      </varlistentry>
100
101      <varlistentry>
102        <term><option>-D</option></term>
103        <term><option>--directory=<replaceable>DIR</replaceable></option></term>
104
105        <listitem><para>Takes a directory path as argument. Upload
106        entries from the specified journal directory
107        <replaceable>DIR</replaceable> instead of the default runtime
108        and system journal paths. This has the same meaning as
109        <option>--directory=</option> option for
110        <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
111        </para></listitem>
112      </varlistentry>
113
114      <varlistentry>
115        <term><option>--file=<replaceable>GLOB</replaceable></option></term>
116
117        <listitem><para>Takes a file glob as an argument. Upload
118        entries from the specified journal files matching
119        <replaceable>GLOB</replaceable> instead of the default runtime
120        and system journal paths. May be specified multiple times, in
121        which case files will be suitably interleaved. This has the same meaning as
122        <option>--file=</option> option for
123        <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
124        </para></listitem>
125      </varlistentry>
126
127      <varlistentry>
128        <term><option>--cursor=</option></term>
129
130        <listitem><para>Upload entries from the location in the
131        journal specified by the passed cursor. This has the same
132        meaning as <option>--cursor=</option> option for
133        <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
134      </varlistentry>
135
136      <varlistentry>
137        <term><option>--after-cursor=</option></term>
138
139        <listitem><para>Upload entries from the location in the
140        journal <emphasis>after</emphasis> the location specified by
141        the this cursor.  This has the same meaning as
142        <option>--after-cursor=</option> option for
143        <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
144        </para></listitem>
145      </varlistentry>
146
147      <varlistentry>
148        <term><option>--save-state</option><optional>=<replaceable>PATH</replaceable></optional></term>
149
150        <listitem><para>Upload entries from the location in the
151        journal <emphasis>after</emphasis> the location specified by
152        the cursor saved in file at <replaceable>PATH</replaceable>
153        (<filename>/var/lib/systemd/journal-upload/state</filename> by default).
154        After an entry is successfully uploaded, update this file
155        with the cursor of that entry.
156        </para></listitem>
157      </varlistentry>
158
159      <varlistentry>
160        <term><option>--follow</option><optional>=<replaceable>BOOL</replaceable></optional></term>
161
162        <listitem><para>
163          If set to yes, then <command>systemd-journal-upload</command> waits for input.
164        </para></listitem>
165      </varlistentry>
166
167      <varlistentry>
168        <term><option>--key=</option></term>
169
170        <listitem><para>
171          Takes a path to a SSL key file in PEM format, or <option>-</option>.
172          If <option>-</option> is set, then client certificate authentication checking
173          will be disabled.
174          Defaults to <filename>&CERTIFICATE_ROOT;/private/journal-upload.pem</filename>.
175        </para></listitem>
176      </varlistentry>
177
178      <varlistentry>
179        <term><option>--cert=</option></term>
180
181        <listitem><para>
182          Takes a path to a SSL certificate file in PEM format, or <option>-</option>.
183          If <option>-</option> is set, then client certificate authentication checking
184          will be disabled.
185          Defaults to <filename>&CERTIFICATE_ROOT;/certs/journal-upload.pem</filename>.
186        </para></listitem>
187      </varlistentry>
188
189      <varlistentry>
190        <term><option>--trust=</option></term>
191
192        <listitem><para>
193          Takes a path to a SSL CA certificate file in PEM format, or <option>-</option>/<option>all</option>.
194          If <option>-</option>/<option>all</option> is set, then certificate checking will be disabled.
195          Defaults to <filename>&CERTIFICATE_ROOT;/ca/trusted.pem</filename>.
196        </para></listitem>
197      </varlistentry>
198
199      <xi:include href="standard-options.xml" xpointer="help" />
200      <xi:include href="standard-options.xml" xpointer="version" />
201    </variablelist>
202  </refsect1>
203
204  <refsect1>
205    <title>Exit status</title>
206
207    <para>On success, 0 is returned; otherwise, a non-zero
208    failure code is returned.</para>
209  </refsect1>
210
211  <refsect1>
212    <title>Examples</title>
213    <example>
214      <title>Setting up certificates for authentication</title>
215
216      <para>Certificates signed by a trusted authority are used to
217      verify that the server to which messages are uploaded is
218      legitimate, and vice versa, that the client is trusted.</para>
219
220      <para>A suitable set of certificates can be generated with
221      <command>openssl</command>. Note, 2048 bits of key length
222      is minimally recommended to use for security reasons:</para>
223
224      <programlisting>openssl req -newkey rsa:2048 -days 3650 -x509 -nodes \
225      -out ca.pem -keyout ca.key -subj '/CN=Certificate authority/'
226
227cat &gt;ca.conf &lt;&lt;EOF
228[ ca ]
229default_ca = this
230
231[ this ]
232new_certs_dir = .
233certificate = ca.pem
234database = ./index
235private_key = ca.key
236serial = ./serial
237default_days = 3650
238default_md = default
239policy = policy_anything
240
241[ policy_anything ]
242countryName             = optional
243stateOrProvinceName     = optional
244localityName            = optional
245organizationName        = optional
246organizationalUnitName  = optional
247commonName              = supplied
248emailAddress            = optional
249EOF
250
251touch index
252echo 0001 &gt;serial
253
254SERVER=server
255CLIENT=client
256
257openssl req -newkey rsa:2048 -nodes -out $SERVER.csr -keyout $SERVER.key -subj "/CN=$SERVER/"
258openssl ca -batch -config ca.conf -notext -in $SERVER.csr -out $SERVER.pem
259
260openssl req -newkey rsa:2048 -nodes -out $CLIENT.csr -keyout $CLIENT.key -subj "/CN=$CLIENT/"
261openssl ca -batch -config ca.conf -notext -in $CLIENT.csr -out $CLIENT.pem
262</programlisting>
263
264      <para>Generated files <filename>ca.pem</filename>,
265      <filename>server.pem</filename>, and
266      <filename>server.key</filename> should be installed on server,
267      and <filename>ca.pem</filename>,
268      <filename>client.pem</filename>, and
269      <filename>client.key</filename> on the client. The location of
270      those files can be specified using
271      <varname>TrustedCertificateFile=</varname>,
272      <varname>ServerCertificateFile=</varname>,
273      and <varname>ServerKeyFile=</varname> in
274      <filename>/etc/systemd/journal-remote.conf</filename> and
275      <filename>/etc/systemd/journal-upload.conf</filename>,
276      respectively. The default locations can be queried by using
277      <command>systemd-journal-remote --help</command> and
278      <command>systemd-journal-upload --help</command>.</para>
279    </example>
280  </refsect1>
281
282  <refsect1>
283    <title>See Also</title>
284    <para>
285      <citerefentry><refentrytitle>journal-upload.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
286      <citerefentry><refentrytitle>systemd-journal-remote.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
287      <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
288      <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
289      <citerefentry><refentrytitle>systemd-journal-gatewayd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
290    </para>
291  </refsect1>
292</refentry>
293