mirror of
https://github.com/morgan9e/systemd
synced 2026-04-14 00:14:32 +09:00
a2015ad126
Since 435c372ce5 added in v256,
num_entries part of the Range header is mandatory and error is returned
when it's not filled in. This makes using the "follow" argument clumsy,
because for an indefinite following of the logs, arbitrary high number
must be specified. This change makes it possible to omit it again and
documents this behavior in the man page.
Moreover, as the cursor part of the header was never mandatory, enclose
it in square brackets in the documentation as well and elaborate how
indexing works.
Following are some concrete examples of the Range header which are now
accepted:
entries= (or entries=:)
- everything starting from the first event
entries=cursor
- everything starting from `cursor`
entries=:-9:10
- last 10 events and close the connection
If the follow flag is set:
entries=:-4:10
- last 5 events, wait for 5 new and close connection
entries=:-9:
- last 10 events and keep streaming
Note that only the very last one is changing current behavior, but
reintroduces pre-v256 compatibility.
Fixes #37172
381 lines
14 KiB
XML
381 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, defaults to the first entry,
|
|
<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>
|
|
|
|
<para>If <replaceable>num_skip</replaceable> is negative and no <replaceable>cursor</replaceable> is
|
|
given, the last entry will be the reference point.</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>, the number of
|
|
events returned is not limited, unless <replaceable>num_entries</replaceable> is specified in the
|
|
<replaceable>Range</replaceable> header).</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>
|