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-or-later -->
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>
66 <xi:include href=
"version-info.xml" xpointer=
"v198"/></listitem>
70 <term><option>--key=
</option></term>
72 <listitem><para>Specify the path to a file or
<constant>AF_UNIX
</constant> stream socket to read the
73 secret server key corresponding to the certificate specified with
<option>--cert=
</option> from. The
74 key must be in PEM format.
</para>
76 <xi:include href=
"version-info.xml" xpointer=
"v198"/></listitem>
80 <term><option>--trust=
</option></term>
82 <listitem><para>Specify the path to a file or
<constant>AF_UNIX
</constant> stream socket to read a CA
83 certificate from. The certificate must be in PEM format.
</para>
85 <xi:include href=
"version-info.xml" xpointer=
"v236"/></listitem>
89 <term><option>--system
</option></term>
90 <term><option>--user
</option></term>
92 <listitem><para>Limit served entries to entries from system
93 services and the kernel, or to entries from services of
94 current user. This has the same meaning as
95 <option>--system
</option> and
<option>--user
</option> options
97 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If
98 neither is specified, all accessible entries are served.
101 <xi:include href=
"version-info.xml" xpointer=
"v249"/></listitem>
105 <term><option>-m
</option></term>
106 <term><option>--merge
</option></term>
108 <listitem><para>Serve entries interleaved from all available
109 journals, including other machines. This has the same meaning
110 as
<option>--merge
</option> option for
111 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para>
113 <xi:include href=
"version-info.xml" xpointer=
"v249"/></listitem>
117 <term><option>-D
<replaceable>DIR
</replaceable></option></term>
118 <term><option>--directory=
<replaceable>DIR
</replaceable></option></term>
120 <listitem><para>Takes a directory path as argument. If
121 specified,
<command>systemd-journal-gatewayd
</command> will serve the
122 specified journal directory
<replaceable>DIR
</replaceable> instead of
123 the default runtime and system journal paths.
</para>
125 <xi:include href=
"version-info.xml" xpointer=
"v232"/></listitem>
129 <term><option>--file=
<replaceable>GLOB
</replaceable></option></term>
131 <listitem><para>Takes a file glob as an argument. Serve
132 entries from the specified journal files matching
133 <replaceable>GLOB
</replaceable> instead of the default runtime
134 and system journal paths. May be specified multiple times, in
135 which case files will be suitably interleaved. This has the same meaning as
136 <option>--file=
</option> option for
137 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
140 <xi:include href=
"version-info.xml" xpointer=
"v249"/></listitem>
143 <xi:include href=
"standard-options.xml" xpointer=
"help" />
144 <xi:include href=
"standard-options.xml" xpointer=
"version" />
149 <title>Supported URLs
</title>
151 <para>The following URLs are recognized:
</para>
155 <term><uri>/browse
</uri></term>
157 <listitem><para>Interactive browsing.
</para>
159 <xi:include href=
"version-info.xml" xpointer=
"v197"/></listitem>
163 <term><uri>/entries[?option1
&option2=value…]
</uri></term>
165 <listitem><para>Retrieval of events in various formats.
</para>
167 <para>The
<option>Accept:
</option> part of the HTTP header
168 determines the format. Supported values are described below.
171 <para>The
<option>Range:
</option> part of the HTTP header
172 determines the range of events returned. Supported values are
176 <para>GET parameters can be used to modify what events are
177 returned. Supported parameters are described below.
</para>
179 <xi:include href=
"version-info.xml" xpointer=
"v197"/>
184 <term><uri>/machine
</uri></term>
186 <listitem><para>Return a JSON structure describing the machine.
</para>
189 <programlisting>{
"machine_id" :
"8cf7ed9d451ea194b77a9f118f3dc446",
190 "boot_id" :
"3d3c9efaf556496a9b04259ee35df7f7",
191 "hostname" :
"fedora",
192 "os_pretty_name" :
"Fedora 19 (Rawhide)",
193 "virtualization" :
"kvm",
197 <xi:include href=
"version-info.xml" xpointer=
"v197"/>
202 <term><uri>/fields/
<replaceable>FIELD_NAME
</replaceable></uri></term>
204 <listitem><para>Return a list of values of this field present in the logs.
</para>
206 <xi:include href=
"version-info.xml" xpointer=
"v197"/>
213 <title>Accept header
</title>
216 <option>Accept:
<replaceable>format
</replaceable></option>
219 <para>Recognized formats:
</para>
223 <term><constant>text/plain
</constant></term>
225 <listitem><para>The default. Plaintext syslog-like output,
226 one line per journal entry
227 (like
<command>journalctl --output short
</command>).
</para>
229 <xi:include href=
"version-info.xml" xpointer=
"v197"/>
234 <term><constant>application/json
</constant></term>
236 <listitem><para>Entries are formatted as JSON data structures,
238 (like
<command>journalctl --output json
</command>).
239 See
<ulink url=
"https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-json-format">Journal JSON Format
</ulink>
240 for more information.
</para>
242 <xi:include href=
"version-info.xml" xpointer=
"v197"/>
247 <term><constant>text/event-stream
</constant></term>
249 <listitem><para>Entries are formatted as JSON data structures,
250 wrapped in a format suitable for
<ulink
251 url=
"https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events">
252 Server-Sent Events
</ulink>
253 (like
<command>journalctl --output json-sse
</command>).
256 <xi:include href=
"version-info.xml" xpointer=
"v229"/>
261 <term><constant>application/vnd.fdo.journal
</constant></term>
263 <listitem><para>Entries are serialized into a binary (but mostly text-based) stream suitable for
264 backups and network transfer (like
<command>journalctl --output export
</command>). See
<ulink
265 url=
"https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format">Journal Export Format
</ulink>
266 for more information.
</para>
268 <xi:include href=
"version-info.xml" xpointer=
"v197"/>
275 <title>Range header
</title>
278 <option>Range: entries=
<replaceable>cursor
</replaceable>[[:
<replaceable>num_skip
</replaceable>]:
<replaceable>num_entries
</replaceable>]
</option>
281 <option>Range: realtime=[
<replaceable>since
</replaceable>]:[
<replaceable>until
</replaceable>][[:
<replaceable>num_skip
</replaceable>]:
<replaceable>num_entries
</replaceable>]
</option>
285 <replaceable>cursor
</replaceable> is a cursor string,
286 <replaceable>since
</replaceable> and
<replaceable>until
</replaceable> are timestamps (seconds since
1970-
01-
01 00:
00:
00 UTC),
287 <replaceable>num_skip
</replaceable> is an integer,
288 <replaceable>num_entries
</replaceable> is an unsigned integer.
291 <para>Range defaults to all available events.
</para>
295 <title>URL GET parameters
</title>
297 <para>Following parameters can be used as part of the URL:
</para>
301 <term><uri>follow
</uri></term>
303 <listitem><para>wait for new events
304 (like
<command>journalctl --follow
</command>, except that
305 the number of events returned is not limited).
</para>
307 <xi:include href=
"version-info.xml" xpointer=
"v197"/>
312 <term><uri>discrete
</uri></term>
314 <listitem><para>Test that the specified cursor refers to an
315 entry in the journal. Returns just this entry.
</para>
317 <xi:include href=
"version-info.xml" xpointer=
"v197"/>
322 <term><uri>boot
</uri></term>
324 <listitem><para>Limit events to the current boot of the system
325 (like
<command>journalctl -b
</command>).
</para>
327 <xi:include href=
"version-info.xml" xpointer=
"v197"/></listitem>
331 <term><uri><replaceable>KEY
</replaceable>=
<replaceable>match
</replaceable></uri></term>
333 <listitem><para>Match journal fields. See
334 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para>
336 <xi:include href=
"version-info.xml" xpointer=
"v197"/>
343 <title>Examples
</title>
344 <para>Retrieve events from this boot from local journal in
345 <ulink url=
"https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format">Journal Export Format
</ulink>:
346 <programlisting>curl --silent -H'Accept: application/vnd.fdo.journal' \
347 'http://localhost:
19531/entries?boot'
</programlisting>
350 <para>Listen for core dumps:
351 <programlisting>curl 'http://localhost:
19531/entries?follow
&MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1'
</programlisting></para>
355 <title>See Also
</title>
357 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
358 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
359 <citerefentry><refentrytitle>systemd.journal-fields
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
360 <citerefentry><refentrytitle>systemd-journald.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
361 <citerefentry><refentrytitle>systemd-journal-remote.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
362 <citerefentry><refentrytitle>systemd-journal-upload.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>