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