systemd/man/systemd-journal-gatewayd.service.xml
Zbigniew Jędrzejewski-Szmek 56ba3c78ae build-sys: create Makefile-man.am automatically
man rules were repeating the same information in too many places,
which was error prone. Those rules can be easily generated from .xml
files. For efficiency and because python is not a required dependency,
Makefile-man.am is only regenerated when requested with

  make update-man-list

If no metadata in man/*.xml changed, this file should not change. So
only when a new man page or a new alias is added, this file should
show up in 'git diff'. The change should then be committed.

If the support for building from git without python was dropped, we
could drop Makefile-man.am from version control. This would also
increase the partial build time (since more stuff would be rebuild
whenever sources in man/*.xml would be modified), so it would probably
wouldn't be worth it.
2013-02-06 23:16:16 -05:00

321 lines
10 KiB
XML

<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
Copyright 2012 Zbigniew Jędrzejewski-Szmek
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="systemd-journal-gatewayd.service" conditional='HAVE_MICROHTTPD'>
<refentryinfo>
<title>systemd-journal-gatewayd.service</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Zbigniew</firstname>
<surname>Jędrzejewski-Szmek</surname>
<email>zbyszek@in.waw.pl</email>
</author>
</authorgroup>
</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>--help</option></term>
<term><option>-h</option></term>
<listitem><para>Prints a short help
text and exits.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem><para>Prints a short version
string and exits.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--cert=</option></term>
<listitem><para>Specify the path to a file containing a server
certificate in PEM format. This option switches
<command>systemd-journal-gatewayd</command> into HTTPS mode
and must be used together with
<option>--key=</option>.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--key=</option></term>
<listitem><para>Specify the path to a file containing a server
key in PEM format corresponding to the certificate specified
with <option>--cert=</option>.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Supported URLs</title>
<para>The following URLs are recognized:</para>
<variablelist>
<varlistentry>
<term><uri>/browse</uri></term>
<listitem><para>Interactive browsing.</para></listitem>
</varlistentry>
<varlistentry>
<term><uri>/entries[?option1&amp;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>
</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>
</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>
</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>
</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="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
JSON Format</ulink> for more information.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>application/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>
</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="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
Export Format</ulink> for more information.</para>
</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>where
<option>cursor</option> is a cursor string,
<option>num_skip</option> is an integer,
<option>num_entries</option> 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>
</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>
</listitem>
</varlistentry>
<varlistentry>
<term><uri>boot</uri></term>
<listitem><para>Limit events to the current boot of the system
(like <command>journalctl --this--boot</command>).</para></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>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Examples</title>
<para>Retrieve events from this boot from local journal
in <ulink
url="http://www.freedesktop.org/wiki/Software/systemd/export">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&amp;MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1'
</programlisting></para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
</para>
</refsect1>
</refentry>