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