2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
9 <refentry id=
"systemd-journal-gatewayd.service" conditional='HAVE_MICROHTTPD'
10 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
13 <title>systemd-journal-gatewayd.service
</title>
14 <productname>systemd
</productname>
18 <refentrytitle>systemd-journal-gatewayd.service
</refentrytitle>
19 <manvolnum>8</manvolnum>
23 <refname>systemd-journal-gatewayd.service
</refname>
24 <refname>systemd-journal-gatewayd.socket
</refname>
25 <refname>systemd-journal-gatewayd
</refname>
26 <refpurpose>HTTP server for journal events
</refpurpose>
30 <para><filename>systemd-journal-gatewayd.service
</filename></para>
31 <para><filename>systemd-journal-gatewayd.socket
</filename></para>
33 <command>/usr/lib/systemd/systemd-journal-gatewayd
</command>
34 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
39 <title>Description
</title>
41 <para><command>systemd-journal-gatewayd
</command> serves journal
42 events over the network. Clients must connect using
43 HTTP. The server listens on port
19531 by default.
44 If
<option>--cert=
</option> is specified, the server expects
45 HTTPS connections.
</para>
47 <para>The program is started by
48 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
49 and expects to receive a single socket. Use
50 <command>systemctl start systemd-journal-gatewayd.socket
</command> to start
51 the service, and
<command>systemctl enable systemd-journal-gatewayd.socket
</command>
52 to have it started on boot.
</para>
56 <title>Options
</title>
58 <para>The following options are understood:
</para>
62 <term><option>--cert=
</option></term>
64 <listitem><para>Specify the path to a file containing a server
65 certificate in PEM format. This option switches
66 <command>systemd-journal-gatewayd
</command> into HTTPS mode
67 and must be used together with
68 <option>--key=
</option>.
</para></listitem>
72 <term><option>--key=
</option></term>
74 <listitem><para>Specify the path to a file containing a server
75 key in PEM format corresponding to the certificate specified
76 with
<option>--cert=
</option>.
</para></listitem>
80 <term><option>--trust=
</option></term>
82 <listitem><para>Specify the path to a file containing a
83 CA certificate in PEM format.
</para></listitem>
87 <term><option>-D
<replaceable>DIR
</replaceable></option></term>
88 <term><option>--directory=
<replaceable>DIR
</replaceable></option></term>
90 <listitem><para>Takes a directory path as argument. If
91 specified,
<command>systemd-journal-gatewayd
</command> will serve the
92 specified journal directory
<replaceable>DIR
</replaceable> instead of
93 the default runtime and system journal paths.
</para></listitem>
96 <xi:include href=
"standard-options.xml" xpointer=
"help" />
97 <xi:include href=
"standard-options.xml" xpointer=
"version" />
102 <title>Supported URLs
</title>
104 <para>The following URLs are recognized:
</para>
108 <term><uri>/browse
</uri></term>
110 <listitem><para>Interactive browsing.
</para></listitem>
114 <term><uri>/entries[?option1
&option2=value…]
</uri></term>
116 <listitem><para>Retrieval of events in various formats.
</para>
118 <para>The
<option>Accept:
</option> part of the HTTP header
119 determines the format. Supported values are described below.
122 <para>The
<option>Range:
</option> part of the HTTP header
123 determines the range of events returned. Supported values are
127 <para>GET parameters can be used to modify what events are
128 returned. Supported parameters are described below.
</para>
133 <term><uri>/machine
</uri></term>
135 <listitem><para>Return a JSON structure describing the machine.
</para>
138 <programlisting>{
"machine_id" :
"8cf7ed9d451ea194b77a9f118f3dc446",
139 "boot_id" :
"3d3c9efaf556496a9b04259ee35df7f7",
140 "hostname" :
"fedora",
141 "os_pretty_name" :
"Fedora 19 (Rawhide)",
142 "virtualization" :
"kvm",
149 <term><uri>/fields/
<replaceable>FIELD_NAME
</replaceable></uri></term>
151 <listitem><para>Return a list of values of this field present in the logs.
</para>
158 <title>Accept header
</title>
161 <option>Accept:
<replaceable>format
</replaceable></option>
164 <para>Recognized formats:
</para>
168 <term><constant>text/plain
</constant></term>
170 <listitem><para>The default. Plaintext syslog-like output,
171 one line per journal entry
172 (like
<command>journalctl --output short
</command>).
</para>
177 <term><constant>application/json
</constant></term>
179 <listitem><para>Entries are formatted as JSON data structures,
181 (like
<command>journalctl --output json
</command>).
183 url=
"https://www.freedesktop.org/wiki/Software/systemd/json">Journal
184 JSON Format
</ulink> for more information.
</para>
189 <term><constant>text/event-stream
</constant></term>
191 <listitem><para>Entries are formatted as JSON data structures,
192 wrapped in a format suitable for
<ulink
193 url=
"https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events">
194 Server-Sent Events
</ulink>
195 (like
<command>journalctl --output json-sse
</command>).
201 <term><constant>application/vnd.fdo.journal
</constant></term>
203 <listitem><para>Entries are serialized into a binary (but
204 mostly text-based) stream suitable for backups and network
206 (like
<command>journalctl --output export
</command>).
208 url=
"https://www.freedesktop.org/wiki/Software/systemd/export">Journal
209 Export Format
</ulink> for more information.
</para>
216 <title>Range header
</title>
219 <option>Range: entries=
<replaceable>cursor
</replaceable>[[:
<replaceable>num_skip
</replaceable>]:
<replaceable>num_entries
</replaceable>]
</option>
223 <option>cursor
</option> is a cursor string,
224 <option>num_skip
</option> is an integer,
225 <option>num_entries
</option> is an unsigned integer.
228 <para>Range defaults to all available events.
</para>
232 <title>URL GET parameters
</title>
234 <para>Following parameters can be used as part of the URL:
</para>
238 <term><uri>follow
</uri></term>
240 <listitem><para>wait for new events
241 (like
<command>journalctl --follow
</command>, except that
242 the number of events returned is not limited).
</para>
247 <term><uri>discrete
</uri></term>
249 <listitem><para>Test that the specified cursor refers to an
250 entry in the journal. Returns just this entry.
</para>
255 <term><uri>boot
</uri></term>
257 <listitem><para>Limit events to the current boot of the system
258 (like
<command>journalctl -b
</command>).
</para></listitem>
262 <term><uri><replaceable>KEY
</replaceable>=
<replaceable>match
</replaceable></uri></term>
264 <listitem><para>Match journal fields. See
265 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para>
272 <title>Examples
</title>
273 <para>Retrieve events from this boot from local journal
275 url=
"https://www.freedesktop.org/wiki/Software/systemd/export">Journal
276 Export Format
</ulink>:
277 <programlisting>curl --silent -H'Accept: application/vnd.fdo.journal' \
278 'http://localhost:
19531/entries?boot'
</programlisting>
281 <para>Listen for core dumps:
282 <programlisting>curl 'http://localhost:
19531/entries?follow
&MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1'
</programlisting></para>
286 <title>See Also
</title>
288 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
289 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
290 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
291 <citerefentry><refentrytitle>systemd-journald.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
292 <citerefentry><refentrytitle>systemd-journal-remote.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
293 <citerefentry><refentrytitle>systemd-journal-upload.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>