chiark / gitweb /
man: add sd_event_add_child(3)
[elogind.git] / man / systemd-journal-remote.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 2012 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-remote" conditional='HAVE_MICROHTTPD'
25           xmlns:xi="http://www.w3.org/2001/XInclude">
26
27   <refentryinfo>
28     <title>systemd-journal-remote</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-remote</refentrytitle>
43     <manvolnum>8</manvolnum>
44   </refmeta>
45
46   <refnamediv>
47     <refname>systemd-journal-remote</refname>
48     <refpurpose>Receive journal messages over the network</refpurpose>
49   </refnamediv>
50
51   <refsynopsisdiv>
52     <cmdsynopsis>
53       <command>systemd-journal-remote</command>
54       <arg choice="opt" rep="repeat">OPTIONS</arg>
55       <arg choice="opt" rep="norepeat">-o/--output=<replaceable>DIR</replaceable>|<replaceable>FILE</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       <filename>systemd-journal-remote</filename> is a command to
65       receive serialized journal events and store them to the journal.
66       Input streams are in the
67       <ulink url="http://www.freedesktop.org/wiki/Software/systemd/export">
68         Journal Export Format
69       </ulink>,
70       i.e. like the output from
71       <command>journalctl --output=export</command>. For transport over
72       the network, this serialized stream is usually carried over an
73       HTTPS connection.
74     </para>
75   </refsect1>
76
77   <refsect1>
78     <title>Sources</title>
79
80     <para>
81       Sources can be either "active"
82       (<command>systemd-journal-remote</command> requests and pulls
83       the data), or "passive"
84       (<command>systemd-journal-remote</command> waits for a
85       connection and then receives events pushed by the other side).
86     </para>
87
88     <para>
89       <command>systemd-journal-remote</command> can read more than one
90       event stream at a time. They will be interleaved in the output
91       file. In case of "active" connections, each "source" is one
92       stream, and in case of "passive" connections, each connection can
93       result in a separate stream. Sockets can be configured in
94       "accept" mode (i.e. only one connection), or "listen" mode (i.e.
95       multiple connections, each resulting in a stream).
96     </para>
97
98     <para>
99       When there are no more connections, and no more can be created
100       (there are no listening sockets), then
101       <command>systemd-journal-remote</command> will exit.
102     </para>
103
104     <para>Active sources can be specified in the following
105     ways:</para>
106
107     <variablelist>
108       <varlistentry>
109         <listitem><para>When <option>-</option> is given as a
110         positional argument, events will be read from standard input.
111         Other positional arguments will be treated as filenames
112         to open and read from.</para></listitem>
113       </varlistentry>
114
115       <varlistentry>
116         <term><option>--url=<replaceable>ADDRESS</replaceable></option></term>
117
118         <listitem><para>With the
119         <option>--url=<replaceable>ADDRESS</replaceable></option> option,
120         events will be retrieved using HTTP from
121         <replaceable>ADDRESS</replaceable>. This URL should refer to the
122         root of a remote
123         <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
124         instance (e.g. <ulink>http://some.host:19531/</ulink> or
125         <ulink>https://some.host:19531/</ulink>).</para></listitem>
126       </varlistentry>
127     </variablelist>
128
129     <para>Passive sources can be specified in the following
130     ways:</para>
131
132     <variablelist>
133       <varlistentry>
134         <term><option>--listen-raw=<replaceable>ADDRESS</replaceable></option></term>
135
136         <listitem><para><replaceable>ADDRESS</replaceable> must be an
137         address suitable for <option>ListenStream=</option> (cf.
138         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
139         <command>systemd-journal-remote</command> will listen on this
140         socket for connections. Each connection is expected to be a
141         stream of journal events.</para>
142         </listitem>
143       </varlistentry>
144
145       <varlistentry>
146         <term><option>--listen-http=<replaceable>ADDRESS</replaceable></option></term>
147         <term><option>--listen-https=<replaceable>ADDRESS</replaceable></option></term>
148
149         <listitem><para><replaceable>ADDRESS</replaceable> must be
150         either a negative integer, in which case it will be
151         interpreted as the (negated) file descriptor number, or an
152         address suitable for <option>ListenStream=</option> (c.f.
153         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
154         In the first case, matching file descriptor must be inherited
155         through
156         <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>.
157         In the second case, an HTTP or HTTPS server will be spawned on
158         this port, respectively for <option>--listen-http</option> and
159         <option>--listen-https</option>. Currenntly, only POST requests
160         to <filename>/upload</filename> with <literal>Content-Type:
161         application/vnd.fdo.journal</literal> are supported.</para>
162         </listitem>
163       </varlistentry>
164
165       <varlistentry>
166         <term><varname>$LISTEN_FDS</varname></term>
167
168         <listitem><para><command>systemd-journal-remote</command>
169         supports the
170         <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>
171         protocol. Open sockets inherited through socket activation
172         behave like those opened with <option>--listen-raw=</option>
173         described above, unless they are specified as an argument in
174         <option>--listen-http=-<replaceable>n</replaceable></option>
175         or
176         <option>--listen-https=-<replaceable>n</replaceable></option>
177         above. In the latter case, an HTTP or HTTPS server will be
178         spawned using this descriptor and connections must be made
179         over the HTTP protocol.</para>
180         </listitem>
181       </varlistentry>
182
183     </variablelist>
184   </refsect1>
185
186   <refsect1>
187     <title>Sinks</title>
188
189     <para>The location of the output journal can be specified
190     with <option>-o</option> or <option>--output=</option>. For "active"
191     sources, this option is required.
192     </para>
193
194     <variablelist>
195       <varlistentry>
196         <term><option>--output=<replaceable>FILE</replaceable></option></term>
197
198         <listitem><para>Will write to this journal file. The filename
199         must end with <filename>.journal</filename>. The file will be
200         created if it does not exist. If necessary (journal file full,
201         or corrupted), the file will be renamed following normal
202         journald rules and a new journal file will be created in its
203         stead.</para></listitem>
204       </varlistentry>
205
206       <varlistentry>
207         <term><option>--output=<replaceable>DIR</replaceable></option></term>
208
209         <listitem><para>Will create journal files underneath directory
210         <replaceable>DIR</replaceable>. The directory must exist. If
211         necessary (journal files over size, or corrupted), journal
212         files will be rotated following normal journald rules. Names
213         of files underneath <replaceable>DIR</replaceable> will be
214         generated using the rules described below.</para></listitem>
215       </varlistentry>
216     </variablelist>
217
218     <para>If <option>--output=</option> is not used, the output
219     directory <filename>/var/log/journal/remote/</filename> will be
220     used.  In case the output file is not specified, journal files
221     will be created underneath the selected directory. Files will be
222     called
223     <filename>remote-<replaceable>hostname</replaceable>.journal</filename>,
224     where the <replaceable>hostname</replaceable> part is the
225     escaped hostname of the source endpoint of the connection, or the
226     numerical address if the hostname cannot be determined.</para>
227
228     <para>In case of "active" sources, the output file name must
229     always be given explicitly.</para>
230   </refsect1>
231
232   <refsect1>
233     <title>Options</title>
234
235     <para>The following options are understood:</para>
236
237     <variablelist>
238       <varlistentry>
239         <term><option>--split-mode</option></term>
240
241         <listitem><para>One of <constant>none</constant> or
242         <constant>host</constant>. For the first, only one output
243         journal file is used. For the latter, a separate output file
244         is used, based on the hostname of the other endpoint of a
245         connection.</para>
246
247         <para>In case of "active" sources, the output file name must
248         always be given explicitly and only <constant>none</constant>
249         is allowed.</para></listitem>
250       </varlistentry>
251
252       <varlistentry>
253         <term><option>--compress</option></term>
254         <term><option>--no-compress</option></term>
255
256         <listitem><para>Compress or not, respectively, the data in the
257         journal using XZ.</para></listitem>
258       </varlistentry>
259
260       <varlistentry>
261         <term><option>--seal</option></term>
262         <term><option>--no-seal</option></term>
263
264         <listitem><para>Periodically sign or not, respectively, the
265         data in the journal using Forward Secure Sealing.
266         </para></listitem>
267       </varlistentry>
268
269       <varlistentry>
270         <term><option>--getter=<replaceable>PROG --option1 --option2</replaceable></option></term>
271
272         <listitem><para>Program to invoke to retrieve data. The journal
273         event stream must be generated on standard output.</para>
274
275         <para>Examples:</para>
276
277         <programlisting>--getter='curl "-HAccept: application/vnd.fdo.journal" https://some.host:19531/'</programlisting>
278
279         <programlisting>--getter='wget --header="Accept: application/vnd.fdo.journal" -O- https://some.host:19531/'</programlisting>
280         </listitem>
281       </varlistentry>
282
283       <xi:include href="standard-options.xml" xpointer="help" />
284       <xi:include href="standard-options.xml" xpointer="version" />
285     </variablelist>
286   </refsect1>
287
288   <refsect1>
289     <title>Examples</title>
290     <para>Copy local journal events to a different journal directory:
291     <programlisting>
292 journalctl -o export | systemd-journal-remote -o /tmp/dir -
293     </programlisting>
294     </para>
295
296     <para>Retrieve events from a remote
297     <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
298     instance and store them in
299     <filename>/var/log/journal/some.host/remote-some~host.journal</filename>:
300     <programlisting>
301 systemd-journal-remote --url http://some.host:19531/
302     </programlisting>
303     </para>
304   </refsect1>
305
306   <refsect1>
307     <title>See Also</title>
308     <para>
309       <citerefentry><refentrytitle>systemd-journal-upload</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
310       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
311       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
312       <citerefentry><refentrytitle>systemd-journal-gatewayd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
313     </para>
314   </refsect1>
315 </refentry>