chiark / gitweb /
hashmap: return more information from resize_buckets()
[elogind.git] / man / systemd-journal-upload.xml
1 <?xml version='1.0'?> <!--*-nxml-*-->
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>