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