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 or
<constant>AF_UNIX
</constant> stream socket to read the
62 server certificate from. The certificate must be in PEM format. This option switches
63 <command>systemd-journal-gatewayd
</command> into HTTPS mode and must be used together with
64 <option>--key=
</option>.
</para></listitem>
68 <term><option>--key=
</option></term>
70 <listitem><para>Specify the path to a file or
<constant>AF_UNIX
</constant> stream socket to read the
71 server key corresponding to the certificate specified with
<option>--cert=
</option> from. The key
72 must be in PEM format.
</para></listitem>
76 <term><option>--trust=
</option></term>
78 <listitem><para>Specify the path to a file or
<constant>AF_UNIX
</constant> stream socket to read a CA
79 certificate from. The certificate must be in PEM format.
</para></listitem>
83 <term><option>-D
<replaceable>DIR
</replaceable></option></term>
84 <term><option>--directory=
<replaceable>DIR
</replaceable></option></term>
86 <listitem><para>Takes a directory path as argument. If
87 specified,
<command>systemd-journal-gatewayd
</command> will serve the
88 specified journal directory
<replaceable>DIR
</replaceable> instead of
89 the default runtime and system journal paths.
</para></listitem>
92 <xi:include href=
"standard-options.xml" xpointer=
"help" />
93 <xi:include href=
"standard-options.xml" xpointer=
"version" />
98 <title>Supported URLs
</title>
100 <para>The following URLs are recognized:
</para>
104 <term><uri>/browse
</uri></term>
106 <listitem><para>Interactive browsing.
</para></listitem>
110 <term><uri>/entries[?option1
&option2=value…]
</uri></term>
112 <listitem><para>Retrieval of events in various formats.
</para>
114 <para>The
<option>Accept:
</option> part of the HTTP header
115 determines the format. Supported values are described below.
118 <para>The
<option>Range:
</option> part of the HTTP header
119 determines the range of events returned. Supported values are
123 <para>GET parameters can be used to modify what events are
124 returned. Supported parameters are described below.
</para>
129 <term><uri>/machine
</uri></term>
131 <listitem><para>Return a JSON structure describing the machine.
</para>
134 <programlisting>{
"machine_id" :
"8cf7ed9d451ea194b77a9f118f3dc446",
135 "boot_id" :
"3d3c9efaf556496a9b04259ee35df7f7",
136 "hostname" :
"fedora",
137 "os_pretty_name" :
"Fedora 19 (Rawhide)",
138 "virtualization" :
"kvm",
145 <term><uri>/fields/
<replaceable>FIELD_NAME
</replaceable></uri></term>
147 <listitem><para>Return a list of values of this field present in the logs.
</para>
154 <title>Accept header
</title>
157 <option>Accept:
<replaceable>format
</replaceable></option>
160 <para>Recognized formats:
</para>
164 <term><constant>text/plain
</constant></term>
166 <listitem><para>The default. Plaintext syslog-like output,
167 one line per journal entry
168 (like
<command>journalctl --output short
</command>).
</para>
173 <term><constant>application/json
</constant></term>
175 <listitem><para>Entries are formatted as JSON data structures,
177 (like
<command>journalctl --output json
</command>).
179 url=
"https://www.freedesktop.org/wiki/Software/systemd/json">Journal
180 JSON Format
</ulink> for more information.
</para>
185 <term><constant>text/event-stream
</constant></term>
187 <listitem><para>Entries are formatted as JSON data structures,
188 wrapped in a format suitable for
<ulink
189 url=
"https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events">
190 Server-Sent Events
</ulink>
191 (like
<command>journalctl --output json-sse
</command>).
197 <term><constant>application/vnd.fdo.journal
</constant></term>
199 <listitem><para>Entries are serialized into a binary (but
200 mostly text-based) stream suitable for backups and network
202 (like
<command>journalctl --output export
</command>).
204 url=
"https://www.freedesktop.org/wiki/Software/systemd/export">Journal
205 Export Format
</ulink> for more information.
</para>
212 <title>Range header
</title>
215 <option>Range: entries=
<replaceable>cursor
</replaceable>[[:
<replaceable>num_skip
</replaceable>]:
<replaceable>num_entries
</replaceable>]
</option>
219 <replaceable>cursor
</replaceable> is a cursor string,
220 <replaceable>num_skip
</replaceable> is an integer,
221 <replaceable>num_entries
</replaceable> is an unsigned integer.
224 <para>Range defaults to all available events.
</para>
228 <title>URL GET parameters
</title>
230 <para>Following parameters can be used as part of the URL:
</para>
234 <term><uri>follow
</uri></term>
236 <listitem><para>wait for new events
237 (like
<command>journalctl --follow
</command>, except that
238 the number of events returned is not limited).
</para>
243 <term><uri>discrete
</uri></term>
245 <listitem><para>Test that the specified cursor refers to an
246 entry in the journal. Returns just this entry.
</para>
251 <term><uri>boot
</uri></term>
253 <listitem><para>Limit events to the current boot of the system
254 (like
<command>journalctl -b
</command>).
</para></listitem>
258 <term><uri><replaceable>KEY
</replaceable>=
<replaceable>match
</replaceable></uri></term>
260 <listitem><para>Match journal fields. See
261 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para>
268 <title>Examples
</title>
269 <para>Retrieve events from this boot from local journal
271 url=
"https://www.freedesktop.org/wiki/Software/systemd/export">Journal
272 Export Format
</ulink>:
273 <programlisting>curl --silent -H'Accept: application/vnd.fdo.journal' \
274 'http://localhost:
19531/entries?boot'
</programlisting>
277 <para>Listen for core dumps:
278 <programlisting>curl 'http://localhost:
19531/entries?follow
&MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1'
</programlisting></para>
282 <title>See Also
</title>
284 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
285 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
286 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
287 <citerefentry><refentrytitle>systemd-journald.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
288 <citerefentry><refentrytitle>systemd-journal-remote.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
289 <citerefentry><refentrytitle>systemd-journal-upload.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>