2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
6 <refentry id=
"systemd-journal-gatewayd.service" conditional='HAVE_MICROHTTPD'
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
10 <title>systemd-journal-gatewayd.service
</title>
11 <productname>systemd
</productname>
15 <refentrytitle>systemd-journal-gatewayd.service
</refentrytitle>
16 <manvolnum>8</manvolnum>
20 <refname>systemd-journal-gatewayd.service
</refname>
21 <refname>systemd-journal-gatewayd.socket
</refname>
22 <refname>systemd-journal-gatewayd
</refname>
23 <refpurpose>HTTP server for journal events
</refpurpose>
27 <para><filename>systemd-journal-gatewayd.service
</filename></para>
28 <para><filename>systemd-journal-gatewayd.socket
</filename></para>
30 <command>/usr/lib/systemd/systemd-journal-gatewayd
</command>
31 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
36 <title>Description
</title>
38 <para><command>systemd-journal-gatewayd
</command> serves journal
39 events over the network. Clients must connect using
40 HTTP. The server listens on port
19531 by default.
41 If
<option>--cert=
</option> is specified, the server expects
42 HTTPS connections.
</para>
44 <para>The program is started by
45 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
46 and expects to receive a single socket. Use
47 <command>systemctl start systemd-journal-gatewayd.socket
</command> to start
48 the service, and
<command>systemctl enable systemd-journal-gatewayd.socket
</command>
49 to have it started on boot.
</para>
53 <title>Options
</title>
55 <para>The following options are understood:
</para>
59 <term><option>--cert=
</option></term>
61 <listitem><para>Specify the path to a file containing a server
62 certificate in PEM format. This option switches
63 <command>systemd-journal-gatewayd
</command> into HTTPS mode
64 and must be used together with
65 <option>--key=
</option>.
</para></listitem>
69 <term><option>--key=
</option></term>
71 <listitem><para>Specify the path to a file containing a server
72 key in PEM format corresponding to the certificate specified
73 with
<option>--cert=
</option>.
</para></listitem>
77 <term><option>--trust=
</option></term>
79 <listitem><para>Specify the path to a file containing a
80 CA certificate in PEM format.
</para></listitem>
84 <term><option>-D
<replaceable>DIR
</replaceable></option></term>
85 <term><option>--directory=
<replaceable>DIR
</replaceable></option></term>
87 <listitem><para>Takes a directory path as argument. If
88 specified,
<command>systemd-journal-gatewayd
</command> will serve the
89 specified journal directory
<replaceable>DIR
</replaceable> instead of
90 the default runtime and system journal paths.
</para></listitem>
93 <xi:include href=
"standard-options.xml" xpointer=
"help" />
94 <xi:include href=
"standard-options.xml" xpointer=
"version" />
99 <title>Supported URLs
</title>
101 <para>The following URLs are recognized:
</para>
105 <term><uri>/browse
</uri></term>
107 <listitem><para>Interactive browsing.
</para></listitem>
111 <term><uri>/entries[?option1
&option2=value…]
</uri></term>
113 <listitem><para>Retrieval of events in various formats.
</para>
115 <para>The
<option>Accept:
</option> part of the HTTP header
116 determines the format. Supported values are described below.
119 <para>The
<option>Range:
</option> part of the HTTP header
120 determines the range of events returned. Supported values are
124 <para>GET parameters can be used to modify what events are
125 returned. Supported parameters are described below.
</para>
130 <term><uri>/machine
</uri></term>
132 <listitem><para>Return a JSON structure describing the machine.
</para>
135 <programlisting>{
"machine_id" :
"8cf7ed9d451ea194b77a9f118f3dc446",
136 "boot_id" :
"3d3c9efaf556496a9b04259ee35df7f7",
137 "hostname" :
"fedora",
138 "os_pretty_name" :
"Fedora 19 (Rawhide)",
139 "virtualization" :
"kvm",
146 <term><uri>/fields/
<replaceable>FIELD_NAME
</replaceable></uri></term>
148 <listitem><para>Return a list of values of this field present in the logs.
</para>
155 <title>Accept header
</title>
158 <option>Accept:
<replaceable>format
</replaceable></option>
161 <para>Recognized formats:
</para>
165 <term><constant>text/plain
</constant></term>
167 <listitem><para>The default. Plaintext syslog-like output,
168 one line per journal entry
169 (like
<command>journalctl --output short
</command>).
</para>
174 <term><constant>application/json
</constant></term>
176 <listitem><para>Entries are formatted as JSON data structures,
178 (like
<command>journalctl --output json
</command>).
180 url=
"https://www.freedesktop.org/wiki/Software/systemd/json">Journal
181 JSON Format
</ulink> for more information.
</para>
186 <term><constant>text/event-stream
</constant></term>
188 <listitem><para>Entries are formatted as JSON data structures,
189 wrapped in a format suitable for
<ulink
190 url=
"https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events">
191 Server-Sent Events
</ulink>
192 (like
<command>journalctl --output json-sse
</command>).
198 <term><constant>application/vnd.fdo.journal
</constant></term>
200 <listitem><para>Entries are serialized into a binary (but
201 mostly text-based) stream suitable for backups and network
203 (like
<command>journalctl --output export
</command>).
205 url=
"https://www.freedesktop.org/wiki/Software/systemd/export">Journal
206 Export Format
</ulink> for more information.
</para>
213 <title>Range header
</title>
216 <option>Range: entries=
<replaceable>cursor
</replaceable>[[:
<replaceable>num_skip
</replaceable>]:
<replaceable>num_entries
</replaceable>]
</option>
220 <option>cursor
</option> is a cursor string,
221 <option>num_skip
</option> is an integer,
222 <option>num_entries
</option> is an unsigned integer.
225 <para>Range defaults to all available events.
</para>
229 <title>URL GET parameters
</title>
231 <para>Following parameters can be used as part of the URL:
</para>
235 <term><uri>follow
</uri></term>
237 <listitem><para>wait for new events
238 (like
<command>journalctl --follow
</command>, except that
239 the number of events returned is not limited).
</para>
244 <term><uri>discrete
</uri></term>
246 <listitem><para>Test that the specified cursor refers to an
247 entry in the journal. Returns just this entry.
</para>
252 <term><uri>boot
</uri></term>
254 <listitem><para>Limit events to the current boot of the system
255 (like
<command>journalctl -b
</command>).
</para></listitem>
259 <term><uri><replaceable>KEY
</replaceable>=
<replaceable>match
</replaceable></uri></term>
261 <listitem><para>Match journal fields. See
262 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para>
269 <title>Examples
</title>
270 <para>Retrieve events from this boot from local journal
272 url=
"https://www.freedesktop.org/wiki/Software/systemd/export">Journal
273 Export Format
</ulink>:
274 <programlisting>curl --silent -H'Accept: application/vnd.fdo.journal' \
275 'http://localhost:
19531/entries?boot'
</programlisting>
278 <para>Listen for core dumps:
279 <programlisting>curl 'http://localhost:
19531/entries?follow
&MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1'
</programlisting></para>
283 <title>See Also
</title>
285 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
286 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
287 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
288 <citerefentry><refentrytitle>systemd-journald.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
289 <citerefentry><refentrytitle>systemd-journal-remote.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
290 <citerefentry><refentrytitle>systemd-journal-upload.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>