1<?xml version='1.0'?>
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 -->
5
6<refentry id="systemd-journal-gatewayd.service" conditional='HAVE_MICROHTTPD'
7          xmlns:xi="http://www.w3.org/2001/XInclude">
8
9  <refentryinfo>
10    <title>systemd-journal-gatewayd.service</title>
11    <productname>systemd</productname>
12  </refentryinfo>
13
14  <refmeta>
15    <refentrytitle>systemd-journal-gatewayd.service</refentrytitle>
16    <manvolnum>8</manvolnum>
17  </refmeta>
18
19  <refnamediv>
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>
24  </refnamediv>
25
26  <refsynopsisdiv>
27    <para><filename>systemd-journal-gatewayd.service</filename></para>
28    <para><filename>systemd-journal-gatewayd.socket</filename></para>
29    <cmdsynopsis>
30      <command>/usr/lib/systemd/systemd-journal-gatewayd</command>
31      <arg choice="opt" rep="repeat">OPTIONS</arg>
32    </cmdsynopsis>
33  </refsynopsisdiv>
34
35  <refsect1>
36    <title>Description</title>
37
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>
43
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>
50  </refsect1>
51
52  <refsect1>
53    <title>Options</title>
54
55    <para>The following options are understood:</para>
56
57    <variablelist>
58      <varlistentry>
59        <term><option>--cert=</option></term>
60
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>
65      </varlistentry>
66
67      <varlistentry>
68        <term><option>--key=</option></term>
69
70        <listitem><para>Specify the path to a file or <constant>AF_UNIX</constant> stream socket to read the
71        secret server key corresponding to the certificate specified with <option>--cert=</option> from. The
72        key must be in PEM format.</para></listitem>
73      </varlistentry>
74
75      <varlistentry>
76        <term><option>--trust=</option></term>
77
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>
80      </varlistentry>
81
82      <varlistentry>
83        <term><option>--system</option></term>
84        <term><option>--user</option></term>
85
86        <listitem><para>Limit served entries to entries from system
87        services and the kernel, or to entries from services of
88        current user. This has the same meaning as
89        <option>--system</option> and <option>--user</option> options
90        for
91        <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If
92        neither is specified, all accessible entries are served.
93        </para></listitem>
94      </varlistentry>
95
96      <varlistentry>
97        <term><option>-m</option></term>
98        <term><option>--merge</option></term>
99
100        <listitem><para>Serve entries interleaved from all available
101        journals, including other machines. This has the same meaning
102        as <option>--merge</option> option for
103        <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
104      </varlistentry>
105
106      <varlistentry>
107        <term><option>-D <replaceable>DIR</replaceable></option></term>
108        <term><option>--directory=<replaceable>DIR</replaceable></option></term>
109
110        <listitem><para>Takes a directory path as argument. If
111        specified, <command>systemd-journal-gatewayd</command> will serve the
112        specified journal directory <replaceable>DIR</replaceable> instead of
113        the default runtime and system journal paths.</para></listitem>
114      </varlistentry>
115
116      <varlistentry>
117        <term><option>--file=<replaceable>GLOB</replaceable></option></term>
118
119        <listitem><para>Takes a file glob as an argument. Serve
120        entries from the specified journal files matching
121        <replaceable>GLOB</replaceable> instead of the default runtime
122        and system journal paths. May be specified multiple times, in
123        which case files will be suitably interleaved. This has the same meaning as
124        <option>--file=</option> option for
125        <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
126        </para></listitem>
127      </varlistentry>
128
129      <xi:include href="standard-options.xml" xpointer="help" />
130      <xi:include href="standard-options.xml" xpointer="version" />
131    </variablelist>
132  </refsect1>
133
134  <refsect1>
135    <title>Supported URLs</title>
136
137    <para>The following URLs are recognized:</para>
138
139    <variablelist>
140      <varlistentry>
141        <term><uri>/browse</uri></term>
142
143        <listitem><para>Interactive browsing.</para></listitem>
144      </varlistentry>
145
146      <varlistentry>
147        <term><uri>/entries[?option1&amp;option2=value…]</uri></term>
148
149        <listitem><para>Retrieval of events in various formats.</para>
150
151        <para>The <option>Accept:</option> part of the HTTP header
152        determines the format. Supported values are described below.
153        </para>
154
155        <para>The <option>Range:</option> part of the HTTP header
156        determines the range of events returned. Supported values are
157        described below.
158        </para>
159
160        <para>GET parameters can be used to modify what events are
161        returned. Supported parameters are described below.</para>
162        </listitem>
163      </varlistentry>
164
165      <varlistentry>
166        <term><uri>/machine</uri></term>
167
168        <listitem><para>Return a JSON structure describing the machine.</para>
169
170        <para>Example:
171        <programlisting>{ "machine_id" : "8cf7ed9d451ea194b77a9f118f3dc446",
172  "boot_id" : "3d3c9efaf556496a9b04259ee35df7f7",
173  "hostname" : "fedora",
174  "os_pretty_name" : "Fedora 19 (Rawhide)",
175  "virtualization" : "kvm",
176  …}</programlisting>
177        </para>
178        </listitem>
179      </varlistentry>
180
181      <varlistentry>
182        <term><uri>/fields/<replaceable>FIELD_NAME</replaceable></uri></term>
183
184        <listitem><para>Return a list of values of this field present in the logs.</para>
185        </listitem>
186      </varlistentry>
187    </variablelist>
188  </refsect1>
189
190  <refsect1>
191    <title>Accept header</title>
192
193    <para>
194      <option>Accept: <replaceable>format</replaceable></option>
195    </para>
196
197    <para>Recognized formats:</para>
198
199    <variablelist>
200      <varlistentry>
201        <term><constant>text/plain</constant></term>
202
203        <listitem><para>The default. Plaintext syslog-like output,
204        one line per journal entry
205        (like <command>journalctl --output short</command>).</para>
206        </listitem>
207      </varlistentry>
208
209      <varlistentry>
210        <term><constant>application/json</constant></term>
211
212        <listitem><para>Entries are formatted as JSON data structures,
213        one per line
214        (like <command>journalctl --output json</command>).
215        See <ulink url="https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-json-format">Journal JSON Format</ulink>
216        for more information.</para>
217        </listitem>
218      </varlistentry>
219
220      <varlistentry>
221        <term><constant>text/event-stream</constant></term>
222
223        <listitem><para>Entries are formatted as JSON data structures,
224        wrapped in a format suitable for <ulink
225        url="https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events">
226        Server-Sent Events</ulink>
227        (like <command>journalctl --output json-sse</command>).
228        </para>
229        </listitem>
230      </varlistentry>
231
232      <varlistentry>
233        <term><constant>application/vnd.fdo.journal</constant></term>
234
235        <listitem><para>Entries are serialized into a binary (but mostly text-based) stream suitable for
236        backups and network transfer (like <command>journalctl --output export</command>).  See <ulink
237        url="https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format">Journal Export Format</ulink>
238        for more information.</para>
239        </listitem>
240      </varlistentry>
241    </variablelist>
242  </refsect1>
243
244  <refsect1>
245    <title>Range header</title>
246
247    <para>
248      <option>Range: entries=<replaceable>cursor</replaceable>[[:<replaceable>num_skip</replaceable>]:<replaceable>num_entries</replaceable>]</option>
249    </para>
250
251    <para>where
252      <replaceable>cursor</replaceable> is a cursor string,
253      <replaceable>num_skip</replaceable> is an integer,
254      <replaceable>num_entries</replaceable> is an unsigned integer.
255    </para>
256
257    <para>Range defaults to all available events.</para>
258  </refsect1>
259
260  <refsect1>
261    <title>URL GET parameters</title>
262
263    <para>Following parameters can be used as part of the URL:</para>
264
265    <variablelist>
266      <varlistentry>
267        <term><uri>follow</uri></term>
268
269        <listitem><para>wait for new events
270        (like <command>journalctl --follow</command>, except that
271        the number of events returned is not limited).</para>
272        </listitem>
273      </varlistentry>
274
275      <varlistentry>
276        <term><uri>discrete</uri></term>
277
278        <listitem><para>Test that the specified cursor refers to an
279        entry in the journal. Returns just this entry.</para>
280        </listitem>
281      </varlistentry>
282
283      <varlistentry>
284        <term><uri>boot</uri></term>
285
286        <listitem><para>Limit events to the current boot of the system
287        (like <command>journalctl -b</command>).</para></listitem>
288      </varlistentry>
289
290      <varlistentry>
291        <term><uri><replaceable>KEY</replaceable>=<replaceable>match</replaceable></uri></term>
292
293        <listitem><para>Match journal fields. See
294        <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
295        </listitem>
296      </varlistentry>
297    </variablelist>
298  </refsect1>
299
300  <refsect1>
301    <title>Examples</title>
302    <para>Retrieve events from this boot from local journal in
303    <ulink url="https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format">Journal Export Format</ulink>:
304    <programlisting>curl --silent -H'Accept: application/vnd.fdo.journal' \
305       'http://localhost:19531/entries?boot'</programlisting>
306    </para>
307
308    <para>Listen for core dumps:
309    <programlisting>curl 'http://localhost:19531/entries?follow&amp;MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1'</programlisting></para>
310  </refsect1>
311
312  <refsect1>
313    <title>See Also</title>
314    <para>
315      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
316      <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
317      <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
318      <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
319      <citerefentry><refentrytitle>systemd-journal-remote.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
320      <citerefentry><refentrytitle>systemd-journal-upload.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
321    </para>
322  </refsect1>
323
324</refentry>
325