man/systemd-journal-upload.service.xml

   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>
  75
  76         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
  77       </varlistentry>
  78
  79       <varlistentry>
  80         <term><option>--system</option></term>
  81         <term><option>--user</option></term>
  82
  83         <listitem><para>Limit uploaded entries to entries from system
  84         services and the kernel, or to entries from services of
  85         current user. This has the same meaning as
  86         <option>--system</option> and <option>--user</option> options
  87         for
  88         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If
  89         neither is specified, all accessible entries are uploaded.
  90         </para>
  91
  92         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
  93       </varlistentry>
  94
  95       <varlistentry>
  96         <term><option>-m</option></term>
  97         <term><option>--merge</option></term>
  98
  99         <listitem><para>Upload entries interleaved from all available
 100         journals, including other machines. This has the same meaning
 101         as <option>--merge</option> option for
 102         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
 103
 104         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 105       </varlistentry>
 106
 107       <varlistentry>
 108         <term><option>--namespace=<replaceable>NAMESPACE</replaceable></option></term>
 109
 110         <listitem><para>Takes a journal namespace identifier string as argument. Upload
 111         entries from the specified journal namespace
 112         <replaceable>NAMESPACE</replaceable> instead of the default namespace. This has the same meaning as
 113         <option>--namespace=</option> option for
 114         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 115         </para>
 116
 117         <xi:include href="version-info.xml" xpointer="v254"/></listitem>
 118       </varlistentry>
 119
 120       <varlistentry>
 121         <term><option>-D</option></term>
 122         <term><option>--directory=<replaceable>DIR</replaceable></option></term>
 123
 124         <listitem><para>Takes a directory path as argument. Upload
 125         entries from the specified journal directory
 126         <replaceable>DIR</replaceable> instead of the default runtime
 127         and system journal paths. This has the same meaning as
 128         <option>--directory=</option> option for
 129         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 130         </para>
 131
 132         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 133       </varlistentry>
 134
 135       <varlistentry>
 136         <term><option>--file=<replaceable>GLOB</replaceable></option></term>
 137
 138         <listitem><para>Takes a file glob as an argument. Upload
 139         entries from the specified journal files matching
 140         <replaceable>GLOB</replaceable> instead of the default runtime
 141         and system journal paths. May be specified multiple times, in
 142         which case files will be suitably interleaved. This has the same meaning as
 143         <option>--file=</option> option for
 144         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 145         </para>
 146
 147         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 148       </varlistentry>
 149
 150       <varlistentry>
 151         <term><option>--cursor=</option></term>
 152
 153         <listitem><para>Upload entries from the location in the
 154         journal specified by the passed cursor. This has the same
 155         meaning as <option>--cursor=</option> option for
 156         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
 157
 158         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 159       </varlistentry>
 160
 161       <varlistentry>
 162         <term><option>--after-cursor=</option></term>
 163
 164         <listitem><para>Upload entries from the location in the
 165         journal <emphasis>after</emphasis> the location specified by
 166         the this cursor.  This has the same meaning as
 167         <option>--after-cursor=</option> option for
 168         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 169         </para>
 170
 171         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 172       </varlistentry>
 173
 174       <varlistentry>
 175         <term><option>--save-state</option><optional>=<replaceable>PATH</replaceable></optional></term>
 176
 177         <listitem><para>Upload entries from the location in the
 178         journal <emphasis>after</emphasis> the location specified by
 179         the cursor saved in file at <replaceable>PATH</replaceable>
 180         (<filename>/var/lib/systemd/journal-upload/state</filename> by default).
 181         After an entry is successfully uploaded, update this file
 182         with the cursor of that entry.
 183         </para>
 184
 185         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 186       </varlistentry>
 187
 188       <varlistentry>
 189         <term><option>--follow</option><optional>=<replaceable>BOOL</replaceable></optional></term>
 190
 191         <listitem><para>
 192           If set to yes, then <command>systemd-journal-upload</command> waits for input.
 193         </para>
 194
 195           <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 196       </varlistentry>
 197
 198       <varlistentry>
 199         <term><option>--key=</option></term>
 200
 201         <listitem><para>
 202           Takes a path to a SSL key file in PEM format, or <option>-</option>.
 203           If <option>-</option> is set, then client certificate authentication checking
 204           will be disabled.
 205           Defaults to <filename>&CERTIFICATE_ROOT;/private/journal-upload.pem</filename>.
 206         </para>
 207
 208           <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 209       </varlistentry>
 210
 211       <varlistentry>
 212         <term><option>--cert=</option></term>
 213
 214         <listitem><para>
 215           Takes a path to a SSL certificate file in PEM format, or <option>-</option>.
 216           If <option>-</option> is set, then client certificate authentication checking
 217           will be disabled.
 218           Defaults to <filename>&CERTIFICATE_ROOT;/certs/journal-upload.pem</filename>.
 219         </para>
 220
 221           <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 222       </varlistentry>
 223
 224       <varlistentry>
 225         <term><option>--trust=</option></term>
 226
 227         <listitem><para>
 228           Takes a path to a SSL CA certificate file in PEM format, or <option>-</option>/<option>all</option>.
 229           If <option>-</option>/<option>all</option> is set, then certificate checking will be disabled.
 230           Defaults to <filename>&CERTIFICATE_ROOT;/ca/trusted.pem</filename>.
 231         </para>
 232
 233           <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 234       </varlistentry>
 235
 236       <xi:include href="standard-options.xml" xpointer="help" />
 237       <xi:include href="standard-options.xml" xpointer="version" />
 238     </variablelist>
 239   </refsect1>
 240
 241   <refsect1>
 242     <title>Exit status</title>
 243
 244     <para>On success, 0 is returned; otherwise, a non-zero
 245     failure code is returned.</para>
 246   </refsect1>
 247
 248   <refsect1>
 249     <title>Examples</title>
 250     <example>
 251       <title>Setting up certificates for authentication</title>
 252
 253       <para>Certificates signed by a trusted authority are used to
 254       verify that the server to which messages are uploaded is
 255       legitimate, and vice versa, that the client is trusted.</para>
 256
 257       <para>A suitable set of certificates can be generated with
 258       <command>openssl</command>. Note, 2048 bits of key length
 259       is minimally recommended to use for security reasons:</para>
 260
 261       <programlisting>openssl req -newkey rsa:2048 -days 3650 -x509 -nodes \
 262       -out ca.pem -keyout ca.key -subj '/CN=Certificate authority/'
 263
 264 cat &gt;ca.conf &lt;&lt;EOF
 265 [ ca ]
 266 default_ca = this
 267
 268 [ this ]
 269 new_certs_dir = .
 270 certificate = ca.pem
 271 database = ./index
 272 private_key = ca.key
 273 serial = ./serial
 274 default_days = 3650
 275 default_md = default
 276 policy = policy_anything
 277
 278 [ policy_anything ]
 279 countryName             = optional
 280 stateOrProvinceName     = optional
 281 localityName            = optional
 282 organizationName        = optional
 283 organizationalUnitName  = optional
 284 commonName              = supplied
 285 emailAddress            = optional
 286 EOF
 287
 288 touch index
 289 echo 0001 &gt;serial
 290
 291 SERVER=server
 292 CLIENT=client
 293
 294 openssl req -newkey rsa:2048 -nodes -out $SERVER.csr -keyout $SERVER.key -subj "/CN=$SERVER/"
 295 openssl ca -batch -config ca.conf -notext -in $SERVER.csr -out $SERVER.pem
 296
 297 openssl req -newkey rsa:2048 -nodes -out $CLIENT.csr -keyout $CLIENT.key -subj "/CN=$CLIENT/"
 298 openssl ca -batch -config ca.conf -notext -in $CLIENT.csr -out $CLIENT.pem
 299 </programlisting>
 300
 301       <para>Generated files <filename>ca.pem</filename>,
 302       <filename>server.pem</filename>, and
 303       <filename>server.key</filename> should be installed on server,
 304       and <filename>ca.pem</filename>,
 305       <filename>client.pem</filename>, and
 306       <filename>client.key</filename> on the client. The location of
 307       those files can be specified using
 308       <varname>TrustedCertificateFile=</varname>,
 309       <varname>ServerCertificateFile=</varname>,
 310       and <varname>ServerKeyFile=</varname> in
 311       <filename>/etc/systemd/journal-remote.conf</filename> and
 312       <filename>/etc/systemd/journal-upload.conf</filename>,
 313       respectively. The default locations can be queried by using
 314       <command>systemd-journal-remote --help</command> and
 315       <command>systemd-journal-upload --help</command>.</para>
 316     </example>
 317   </refsect1>
 318
 319   <refsect1>
 320     <title>See Also</title>
 321     <para><simplelist type="inline">
 322       <member><citerefentry><refentrytitle>journal-upload.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 323       <member><citerefentry><refentrytitle>systemd-journal-remote.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 324       <member><citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 325       <member><citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 326       <member><citerefentry><refentrytitle>systemd-journal-gatewayd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 327     </simplelist></para>
 328   </refsect1>
 329 </refentry>