man/systemd-journal-upload.service.xml

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