man/systemd-journal-upload.service.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   SPDX-License-Identifier: LGPL-2.1+
  10 -->
  11
  12 <refentry id="systemd-journal-upload" conditional='HAVE_MICROHTTPD'
  13           xmlns:xi="http://www.w3.org/2001/XInclude">
  14
  15   <refentryinfo>
  16     <title>systemd-journal-upload.service</title>
  17     <productname>systemd</productname>
  18   </refentryinfo>
  19
  20   <refmeta>
  21     <refentrytitle>systemd-journal-upload.service</refentrytitle>
  22     <manvolnum>8</manvolnum>
  23   </refmeta>
  24
  25   <refnamediv>
  26     <refname>systemd-journal-upload.service</refname>
  27     <refname>systemd-journal-upload</refname>
  28     <refpurpose>Send journal messages over the network</refpurpose>
  29   </refnamediv>
  30
  31   <refsynopsisdiv>
  32     <para><filename>systemd-journal-upload.service</filename></para>
  33     <cmdsynopsis>
  34       <command>/usr/lib/systemd/systemd-journal-upload</command>
  35       <arg choice="opt" rep="repeat">OPTIONS</arg>
  36       <arg choice="opt" rep="norepeat">-u/--url=<replaceable>URL</replaceable></arg>
  37       <arg choice="opt" rep="repeat">SOURCES</arg>
  38     </cmdsynopsis>
  39   </refsynopsisdiv>
  40
  41   <refsect1>
  42     <title>Description</title>
  43
  44     <para><command>systemd-journal-upload</command> will upload journal entries to the URL specified
  45     with <option>--url=</option>. This program reads journal entries from one or more journal files,
  46     similarly to
  47     <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
  48     Unless limited by one of the options specified below, all journal entries accessible to the user
  49     the program is running as will be uploaded, and then the program will wait and send new entries
  50     as they become available.</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.
 172           Defaults to <filename>&CERTIFICATE_ROOT;/private/journal-upload.pem</filename>.
 173         </para></listitem>
 174       </varlistentry>
 175
 176       <varlistentry>
 177         <term><option>--cert=</option></term>
 178
 179         <listitem><para>
 180           Takes a path to a SSL certificate file in PEM format.
 181           Defaults to <filename>&CERTIFICATE_ROOT;/certs/journal-upload.pem</filename>.
 182         </para></listitem>
 183       </varlistentry>
 184
 185       <varlistentry>
 186         <term><option>--trust=</option></term>
 187
 188         <listitem><para>
 189           Takes a path to a SSL CA certificate file in PEM format,
 190           or <option>all</option>. If <option>all</option> is set,
 191           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       <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>