]> git.ipfire.org Git - thirdparty/systemd.git/blob - man/systemd-journal-upload.xml
Merge pull request #34 from systemd-mailing-devs/1432619328-32030-1-git-send-email...
[thirdparty/systemd.git] / 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>