1
0
mirror of https://github.com/systemd/systemd.git synced 2024-12-23 21:35:11 +03:00
systemd/man/systemd-journal-gatewayd.service.xml
Tom Gundersen 12b42c7667 man: revert dynamic paths for split-usr setups
This did not really work out as we had hoped. Trying to do this upstream
introduced several problems that probably makes it better suited as a
downstream patch after all. At any rate, it is not releaseable in the
current state, so we at least need to revert this before the release.

 * by adjusting the path to binaries, but not do the same thing to the
   search path we end up with inconsistent man-pages. Adjusting the search
   path too would be quite messy, and it is not at all obvious that this is
   worth the effort, but at any rate it would have to be done before we
   could ship this.

 * this means that distributed man-pages does not make sense as they depend
   on config options, and for better or worse we are still distributing
   man pages, so that is something that definitely needs sorting out before
   we could ship with this patch.

 * we have long held that split-usr is only minimally supported in order
   to boot, and something we hope will eventually go away. So before we start
   adding even more magic/effort in order to make this work nicely, we should
   probably question if it makes sense at all.
2015-06-18 19:47:44 +02:00

303 lines
10 KiB
XML

<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!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'
xmlns:xi="http://www.w3.org/2001/XInclude">
<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>--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>
<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>/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>