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