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