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