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