Jan Čermák
c9f931b737
Add endpoint for listing boots. Output format mimics `journalctl --list-boots -o json`, so it's a plain array containing index, boot ID and timestamps of the first and last entry. Initial implementation returns boots ordered starting with the current one and doesn't allow any filtering (i.e. equivalent of --lines argument). Fixes: #37573
378 lines
14 KiB
XML
378 lines
14 KiB
XML
<?xml version='1.0'?>
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
|
|
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
|
|
|
|
<refentry id="systemd-journal-gatewayd.service" conditional='ENABLE_REMOTE HAVE_MICROHTTPD'
|
|
xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
|
|
<refentryinfo>
|
|
<title>systemd-journal-gatewayd.service</title>
|
|
<productname>systemd</productname>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>systemd-journal-gatewayd.service</refentrytitle>
|
|
<manvolnum>8</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>systemd-journal-gatewayd.service</refname>
|
|
<refname>systemd-journal-gatewayd.socket</refname>
|
|
<refname>systemd-journal-gatewayd</refname>
|
|
<refpurpose>HTTP server for journal events</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<para><filename>systemd-journal-gatewayd.service</filename></para>
|
|
<para><filename>systemd-journal-gatewayd.socket</filename></para>
|
|
<cmdsynopsis>
|
|
<command>/usr/lib/systemd/systemd-journal-gatewayd</command>
|
|
<arg choice="opt" rep="repeat">OPTIONS</arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para><command>systemd-journal-gatewayd</command> serves journal
|
|
events over the network. Clients must connect using
|
|
HTTP. The server listens on port 19531 by default.
|
|
If <option>--cert=</option> is specified, the server expects
|
|
HTTPS connections.</para>
|
|
|
|
<para>The program is started by
|
|
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
and expects to receive a single socket. Use
|
|
<command>systemctl start systemd-journal-gatewayd.socket</command> to start
|
|
the service, and <command>systemctl enable systemd-journal-gatewayd.socket</command>
|
|
to have it started on boot.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Options</title>
|
|
|
|
<para>The following options are understood:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>--cert=</option></term>
|
|
|
|
<listitem><para>Specify the path to a file or <constant>AF_UNIX</constant> stream socket to read the
|
|
server certificate from. The certificate must be in PEM format. This option switches
|
|
<command>systemd-journal-gatewayd</command> into HTTPS mode and must be used together with
|
|
<option>--key=</option>.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v198"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--key=</option></term>
|
|
|
|
<listitem><para>Specify the path to a file or <constant>AF_UNIX</constant> stream socket to read the
|
|
secret server key corresponding to the certificate specified with <option>--cert=</option> from. The
|
|
key must be in PEM format.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v198"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--trust=</option></term>
|
|
|
|
<listitem><para>Specify the path to a file or <constant>AF_UNIX</constant> stream socket to read a CA
|
|
certificate from. The certificate must be in PEM format.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v236"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--system</option></term>
|
|
<term><option>--user</option></term>
|
|
|
|
<listitem><para>Limit served entries to entries from system
|
|
services and the kernel, or to entries from services of
|
|
current user. This has the same meaning as
|
|
<option>--system</option> and <option>--user</option> options
|
|
for
|
|
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If
|
|
neither is specified, all accessible entries are served.
|
|
</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v249"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-m</option></term>
|
|
<term><option>--merge</option></term>
|
|
|
|
<listitem><para>Serve entries interleaved from all available
|
|
journals, including other machines. This has the same meaning
|
|
as <option>--merge</option> option for
|
|
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v249"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-D <replaceable>DIR</replaceable></option></term>
|
|
<term><option>--directory=<replaceable>DIR</replaceable></option></term>
|
|
|
|
<listitem><para>Takes a directory path as argument. If
|
|
specified, <command>systemd-journal-gatewayd</command> will serve the
|
|
specified journal directory <replaceable>DIR</replaceable> instead of
|
|
the default runtime and system journal paths.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v232"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--file=<replaceable>GLOB</replaceable></option></term>
|
|
|
|
<listitem><para>Takes a file glob as an argument. Serve
|
|
entries from the specified journal files matching
|
|
<replaceable>GLOB</replaceable> instead of the default runtime
|
|
and system journal paths. May be specified multiple times, in
|
|
which case files will be suitably interleaved. This has the same meaning as
|
|
<option>--file=</option> option for
|
|
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
|
|
</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v249"/></listitem>
|
|
</varlistentry>
|
|
|
|
<xi:include href="standard-options.xml" xpointer="help" />
|
|
<xi:include href="standard-options.xml" xpointer="version" />
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Supported URLs</title>
|
|
|
|
<para>The following URLs are recognized:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><uri>/boots</uri></term>
|
|
|
|
<listitem><para>Returns json-seq (RFC 7464) response containing JSON objects, each one containing
|
|
boot number, its ID and the timestamps of the first and last message. Boots are returned starting
|
|
with the latest boot first and use the same schema as
|
|
<command>journalctl --list-boots --output json</command>.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><uri>/browse</uri></term>
|
|
|
|
<listitem><para>Interactive browsing.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v197"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><uri>/entries[?option1&option2=value…]</uri></term>
|
|
|
|
<listitem><para>Retrieval of events in various formats.</para>
|
|
|
|
<para>The <option>Accept:</option> part of the HTTP header
|
|
determines the format. Supported values are described below.
|
|
</para>
|
|
|
|
<para>The <option>Range:</option> part of the HTTP header
|
|
determines the range of events returned. Supported values are
|
|
described below.
|
|
</para>
|
|
|
|
<para>GET parameters can be used to modify what events are
|
|
returned. Supported parameters are described below.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v197"/>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><uri>/machine</uri></term>
|
|
|
|
<listitem><para>Return a JSON structure describing the machine.</para>
|
|
|
|
<para>Example:
|
|
<programlisting>{ "machine_id" : "8cf7ed9d451ea194b77a9f118f3dc446",
|
|
"boot_id" : "3d3c9efaf556496a9b04259ee35df7f7",
|
|
"hostname" : "fedora",
|
|
"os_pretty_name" : "Fedora 19 (Rawhide)",
|
|
"virtualization" : "kvm",
|
|
…}</programlisting>
|
|
</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v197"/>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><uri>/fields/<replaceable>FIELD_NAME</replaceable></uri></term>
|
|
|
|
<listitem><para>Return a list of values of this field present in the logs.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v197"/>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Accept header</title>
|
|
|
|
<para>
|
|
<option>Accept: <replaceable>format</replaceable></option>
|
|
</para>
|
|
|
|
<para>Recognized formats:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><constant>text/plain</constant></term>
|
|
|
|
<listitem><para>The default. Plaintext syslog-like output,
|
|
one line per journal entry
|
|
(like <command>journalctl --output short</command>).</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v197"/>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><constant>application/json</constant></term>
|
|
|
|
<listitem><para>Entries are formatted as JSON data structures,
|
|
one per line
|
|
(like <command>journalctl --output json</command>).
|
|
See <ulink url="https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-json-format">Journal JSON Format</ulink>
|
|
for more information.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v197"/>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><constant>text/event-stream</constant></term>
|
|
|
|
<listitem><para>Entries are formatted as JSON data structures,
|
|
wrapped in a format suitable for <ulink
|
|
url="https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events">
|
|
Server-Sent Events</ulink>
|
|
(like <command>journalctl --output json-sse</command>).
|
|
</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v229"/>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><constant>application/vnd.fdo.journal</constant></term>
|
|
|
|
<listitem><para>Entries are serialized into a binary (but mostly text-based) stream suitable for
|
|
backups and network transfer (like <command>journalctl --output export</command>). See <ulink
|
|
url="https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format">Journal Export Format</ulink>
|
|
for more information.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v197"/>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Range header</title>
|
|
|
|
<para>
|
|
<option>Range: entries=<replaceable>cursor</replaceable>[[:<replaceable>num_skip</replaceable>]:<replaceable>num_entries</replaceable>]</option>
|
|
</para>
|
|
<para>
|
|
<option>Range: realtime=[<replaceable>since</replaceable>]:[<replaceable>until</replaceable>][[:<replaceable>num_skip</replaceable>]:<replaceable>num_entries</replaceable>]</option>
|
|
</para>
|
|
|
|
<para>where
|
|
<replaceable>cursor</replaceable> is a cursor string,
|
|
<replaceable>since</replaceable> and <replaceable>until</replaceable> are timestamps (seconds since 1970-01-01 00:00:00 UTC),
|
|
<replaceable>num_skip</replaceable> is an integer,
|
|
<replaceable>num_entries</replaceable> is an unsigned integer.
|
|
</para>
|
|
|
|
<para>Range defaults to all available events.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>URL GET parameters</title>
|
|
|
|
<para>Following parameters can be used as part of the URL:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><uri>follow</uri></term>
|
|
|
|
<listitem><para>wait for new events
|
|
(like <command>journalctl --follow</command>, except that
|
|
the number of events returned is not limited).</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v197"/>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><uri>discrete</uri></term>
|
|
|
|
<listitem><para>Test that the specified cursor refers to an
|
|
entry in the journal. Returns just this entry.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v197"/>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><uri>boot</uri></term>
|
|
|
|
<listitem><para>Limit events to the current boot of the system
|
|
(like <command>journalctl -b</command>).</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v197"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><uri><replaceable>KEY</replaceable>=<replaceable>match</replaceable></uri></term>
|
|
|
|
<listitem><para>Match journal fields. See
|
|
<citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v197"/>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
<para>Retrieve events from this boot from local journal in
|
|
<ulink url="https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format">Journal Export Format</ulink>:
|
|
<programlisting>curl --silent -H'Accept: application/vnd.fdo.journal' \
|
|
'http://localhost:19531/entries?boot'</programlisting>
|
|
</para>
|
|
|
|
<para>Listen for core dumps:
|
|
<programlisting>curl 'http://localhost:19531/entries?follow&MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1'</programlisting></para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
<para><simplelist type="inline">
|
|
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>systemd-journal-remote.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>systemd-journal-upload.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
|
|
</simplelist></para>
|
|
</refsect1>
|
|
|
|
</refentry>
|