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.
 169           Defaults to <filename>&CERTIFICATE_ROOT;/private/journal-upload.pem</filename>.
 170         </para></listitem>
 171       </varlistentry>
 172
 173       <varlistentry>
 174         <term><option>--cert=</option></term>
 175
 176         <listitem><para>
 177           Takes a path to a SSL certificate file in PEM format.
 178           Defaults to <filename>&CERTIFICATE_ROOT;/certs/journal-upload.pem</filename>.
 179         </para></listitem>
 180       </varlistentry>
 181
 182       <varlistentry>
 183         <term><option>--trust=</option></term>
 184
 185         <listitem><para>
 186           Takes a path to a SSL CA certificate file in PEM format,
 187           or <option>all</option>. If <option>all</option> is set,
 188           then certificate checking will be disabled.
 189           Defaults to <filename>&CERTIFICATE_ROOT;/ca/trusted.pem</filename>.
 190         </para></listitem>
 191       </varlistentry>
 192
 193       <xi:include href="standard-options.xml" xpointer="help" />
 194       <xi:include href="standard-options.xml" xpointer="version" />
 195     </variablelist>
 196   </refsect1>
 197
 198   <refsect1>
 199     <title>Exit status</title>
 200
 201     <para>On success, 0 is returned; otherwise, a non-zero
 202     failure code is returned.</para>
 203   </refsect1>
 204
 205   <refsect1>
 206     <title>Examples</title>
 207     <example>
 208       <title>Setting up certificates for authentication</title>
 209
 210       <para>Certificates signed by a trusted authority are used to
 211       verify that the server to which messages are uploaded is
 212       legitimate, and vice versa, that the client is trusted.</para>
 213
 214       <para>A suitable set of certificates can be generated with
 215       <command>openssl</command>. Note, 2048 bits of key length
 216       is minimally recommended to use for security reasons:</para>
 217
 218       <programlisting>openssl req -newkey rsa:2048 -days 3650 -x509 -nodes \
 219       -out ca.pem -keyout ca.key -subj '/CN=Certificate authority/'
 220
 221 cat &gt;ca.conf &lt;&lt;EOF
 222 [ ca ]
 223 default_ca = this
 224
 225 [ this ]
 226 new_certs_dir = .
 227 certificate = ca.pem
 228 database = ./index
 229 private_key = ca.key
 230 serial = ./serial
 231 default_days = 3650
 232 default_md = default
 233 policy = policy_anything
 234
 235 [ policy_anything ]
 236 countryName             = optional
 237 stateOrProvinceName     = optional
 238 localityName            = optional
 239 organizationName        = optional
 240 organizationalUnitName  = optional
 241 commonName              = supplied
 242 emailAddress            = optional
 243 EOF
 244
 245 touch index
 246 echo 0001 &gt;serial
 247
 248 SERVER=server
 249 CLIENT=client
 250
 251 openssl req -newkey rsa:2048 -nodes -out $SERVER.csr -keyout $SERVER.key -subj "/CN=$SERVER/"
 252 openssl ca -batch -config ca.conf -notext -in $SERVER.csr -out $SERVER.pem
 253
 254 openssl req -newkey rsa:2048 -nodes -out $CLIENT.csr -keyout $CLIENT.key -subj "/CN=$CLIENT/"
 255 openssl ca -batch -config ca.conf -notext -in $CLIENT.csr -out $CLIENT.pem
 256 </programlisting>
 257
 258       <para>Generated files <filename>ca.pem</filename>,
 259       <filename>server.pem</filename>, and
 260       <filename>server.key</filename> should be installed on server,
 261       and <filename>ca.pem</filename>,
 262       <filename>client.pem</filename>, and
 263       <filename>client.key</filename> on the client. The location of
 264       those files can be specified using
 265       <varname>TrustedCertificateFile=</varname>,
 266       <varname>ServerCertificateFile=</varname>,
 267       <varname>ServerKeyFile=</varname>, in
 268       <filename>/etc/systemd/journal-remote.conf</filename> and
 269       <filename>/etc/systemd/journal-upload.conf</filename>,
 270       respectively. The default locations can be queried by using
 271       <command>systemd-journal-remote --help</command> and
 272       <command>systemd-journal-upload --help</command>.</para>
 273     </example>
 274   </refsect1>
 275
 276   <refsect1>
 277     <title>See Also</title>
 278     <para>
 279       <citerefentry><refentrytitle>journal-upload.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 280       <citerefentry><refentrytitle>systemd-journal-remote.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 281       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 282       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 283       <citerefentry><refentrytitle>systemd-journal-gatewayd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 284     </para>
 285   </refsect1>
 286 </refentry>