chiark / gitweb /
service: add FailureAction= option
[elogind.git] / man / systemd-journal-gatewayd.service.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-gatewayd.service" conditional='HAVE_MICROHTTPD'
25           xmlns:xi="http://www.w3.org/2001/XInclude">
26
27   <refentryinfo>
28     <title>systemd-journal-gatewayd.service</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-gatewayd.service</refentrytitle>
43     <manvolnum>8</manvolnum>
44   </refmeta>
45
46   <refnamediv>
47     <refname>systemd-journal-gatewayd.service</refname>
48     <refname>systemd-journal-gatewayd.socket</refname>
49     <refname>systemd-journal-gatewayd</refname>
50     <refpurpose>HTTP server for journal events</refpurpose>
51   </refnamediv>
52
53   <refsynopsisdiv>
54     <para><filename>systemd-journal-gatewayd.service</filename></para>
55     <para><filename>systemd-journal-gatewayd.socket</filename></para>
56     <cmdsynopsis>
57       <command>/usr/lib/systemd/systemd-journal-gatewayd</command>
58       <arg choice="opt" rep="repeat">OPTIONS</arg>
59     </cmdsynopsis>
60   </refsynopsisdiv>
61
62   <refsect1>
63     <title>Description</title>
64
65     <para><command>systemd-journal-gatewayd</command> serves journal
66     events over the network. Clients must connect using
67     HTTP. The server listens on port 19531 by default.
68     If <option>--cert=</option> is specified, the server expects
69     HTTPS connections.</para>
70
71     <para>The program is started by
72     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
73     and expects to receive a single socket. Use
74     <command>systemctl start systemd-journal-gatewayd.socket</command> to start
75     the service, and <command>systemctl enable systemd-journal-gatewayd.socket</command>
76     to have it started on boot.</para>
77   </refsect1>
78
79   <refsect1>
80     <title>Options</title>
81
82     <para>The following options are understood:</para>
83
84     <variablelist>
85       <varlistentry>
86         <term><option>--cert=</option></term>
87
88         <listitem><para>Specify the path to a file containing a server
89         certificate in PEM format. This option switches
90         <command>systemd-journal-gatewayd</command> into HTTPS mode
91         and must be used together with
92         <option>--key=</option>.</para></listitem>
93       </varlistentry>
94
95       <varlistentry>
96         <term><option>--key=</option></term>
97
98         <listitem><para>Specify the path to a file containing a server
99         key in PEM format corresponding to the certificate specified
100         with <option>--cert=</option>.</para></listitem>
101       </varlistentry>
102
103       <xi:include href="standard-options.xml" xpointer="help" />
104       <xi:include href="standard-options.xml" xpointer="version" />
105     </variablelist>
106   </refsect1>
107
108   <refsect1>
109     <title>Supported URLs</title>
110
111     <para>The following URLs are recognized:</para>
112
113     <variablelist>
114       <varlistentry>
115         <term><uri>/browse</uri></term>
116
117         <listitem><para>Interactive browsing.</para></listitem>
118       </varlistentry>
119
120       <varlistentry>
121         <term><uri>/entries[?option1&amp;option2=value...]</uri></term>
122
123         <listitem><para>Retrieval of events in various formats.</para>
124
125         <para>The <option>Accept:</option> part of the HTTP header
126         determines the format. Supported values are described below.
127         </para>
128
129         <para>The <option>Range:</option> part of the HTTP header
130         determines the range of events returned. Supported values are
131         described below.
132         </para>
133
134         <para>GET parameters can be used to modify what events are
135         returned. Supported parameters are described below.</para>
136         </listitem>
137       </varlistentry>
138
139       <varlistentry>
140         <term><uri>/machine</uri></term>
141
142         <listitem><para>Return a JSON structure describing the machine.</para>
143
144         <para>Example:
145         <programlisting>{ "machine_id" : "8cf7ed9d451ea194b77a9f118f3dc446",
146   "boot_id" : "3d3c9efaf556496a9b04259ee35df7f7",
147   "hostname" : "fedora",
148   "os_pretty_name" : "Fedora 19 (Rawhide)",
149   "virtualization" : "kvm",
150   ...}</programlisting>
151         </para>
152         </listitem>
153       </varlistentry>
154
155       <varlistentry>
156         <term><uri>/fields/<replaceable>FIELD_NAME</replaceable></uri></term>
157
158         <listitem><para>Return a list of values of this field present in the logs.</para>
159         </listitem>
160       </varlistentry>
161     </variablelist>
162   </refsect1>
163
164   <refsect1>
165     <title>Accept header</title>
166
167     <para>
168       <option>Accept: <replaceable>format</replaceable></option>
169     </para>
170
171     <para>Recognized formats:</para>
172
173     <variablelist>
174       <varlistentry>
175         <term><constant>text/plain</constant></term>
176
177         <listitem><para>The default. Plaintext syslog-like output,
178         one line per journal entry
179         (like <command>journalctl --output short</command>).</para>
180         </listitem>
181       </varlistentry>
182
183       <varlistentry>
184         <term><constant>application/json</constant></term>
185
186         <listitem><para>Entries are formatted as JSON data structures,
187         one per line
188         (like <command>journalctl --output json</command>).
189         See <ulink
190         url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
191         JSON Format</ulink> for more information.</para>
192         </listitem>
193       </varlistentry>
194
195       <varlistentry>
196         <term><constant>application/event-stream</constant></term>
197
198         <listitem><para>Entries are formatted as JSON data structures,
199         wrapped in a format suitable for <ulink
200         url="https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events">
201         Server-Sent Events</ulink>
202         (like <command>journalctl --output json-sse</command>).
203         </para>
204         </listitem>
205       </varlistentry>
206
207       <varlistentry>
208         <term><constant>application/vnd.fdo.journal</constant></term>
209
210         <listitem><para>Entries are serialized into a binary (but
211         mostly text-based) stream suitable for backups and network
212         transfer
213         (like <command>journalctl --output export</command>).
214         See <ulink
215         url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
216         Export Format</ulink> for more information.</para>
217         </listitem>
218       </varlistentry>
219     </variablelist>
220   </refsect1>
221
222   <refsect1>
223     <title>Range header</title>
224
225     <para>
226       <option>Range: entries=<replaceable>cursor</replaceable>[[:<replaceable>num_skip</replaceable>]:<replaceable>num_entries</replaceable>]</option>
227     </para>
228
229     <para>where
230       <option>cursor</option> is a cursor string,
231       <option>num_skip</option> is an integer,
232       <option>num_entries</option> is an unsigned integer.
233     </para>
234
235     <para>Range defaults to all available events.</para>
236   </refsect1>
237
238   <refsect1>
239     <title>URL GET parameters</title>
240
241     <para>Following parameters can be used as part of the URL:</para>
242
243     <variablelist>
244       <varlistentry>
245         <term><uri>follow</uri></term>
246
247         <listitem><para>wait for new events
248         (like <command>journalctl --follow</command>, except that
249         the number of events returned is not limited).</para>
250         </listitem>
251       </varlistentry>
252
253       <varlistentry>
254         <term><uri>discrete</uri></term>
255
256         <listitem><para>Test that the specified cursor refers to an
257         entry in the journal. Returns just this entry.</para>
258         </listitem>
259       </varlistentry>
260
261       <varlistentry>
262         <term><uri>boot</uri></term>
263
264         <listitem><para>Limit events to the current boot of the system
265         (like <command>journalctl --this--boot</command>).</para></listitem>
266       </varlistentry>
267
268       <varlistentry>
269         <term><uri><replaceable>KEY</replaceable>=<replaceable>match</replaceable></uri></term>
270
271         <listitem><para>Match journal fields. See
272         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
273         </listitem>
274       </varlistentry>
275     </variablelist>
276   </refsect1>
277
278   <refsect1>
279     <title>Examples</title>
280     <para>Retrieve events from this boot from local journal
281     in <ulink
282     url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
283     Export Format</ulink>:
284     <programlisting>curl --silent -H'Accept: application/vnd.fdo.journal' \
285        'http://localhost:19531/entries?boot'</programlisting>
286     </para>
287
288     <para>Listen for core dumps:
289     <programlisting>curl 'http://localhost:19531/entries?follow&amp;MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1'</programlisting></para>
290   </refsect1>
291
292   <refsect1>
293     <title>See Also</title>
294     <para>
295       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
296       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
297       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
298       <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
299     </para>
300   </refsect1>
301
302 </refentry>