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