man/systemd-journal-gatewayd.service.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6 This file is part of systemd.
   7
   8 Copyright 2012 Zbigniew Jędrzejewski-Szmek
   9
  10 systemd is free software; you can redistribute it and/or modify it
  11 under the terms of the GNU Lesser General Public License as published by
  12 the Free Software Foundation; either version 2.1 of the License, or
  13 (at your option) any later version.
  14
  15 systemd is distributed in the hope that it will be useful, but
  16 WITHOUT ANY WARRANTY; without even the implied warranty of
  17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18 Lesser General Public License for more details.
  19
  20 You should have received a copy of the GNU Lesser General Public License
  21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="systemd-journal-gatewayd.service">
  25
  26   <refentryinfo>
  27     <title>systemd-journal-gatewayd.service</title>
  28     <productname>systemd</productname>
  29
  30     <authorgroup>
  31       <author>
  32         <contrib>Developer</contrib>
  33         <firstname>Zbigniew</firstname>
  34         <surname>Jędrzejewski-Szmek</surname>
  35         <email>zbyszek@in.waw.pl</email>
  36       </author>
  37     </authorgroup>
  38   </refentryinfo>
  39
  40   <refmeta>
  41     <refentrytitle>systemd-journal-gatewayd.service</refentrytitle>
  42     <manvolnum>8</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  46     <refname>systemd-journal-gatewayd.service</refname>
  47     <refname>systemd-journal-gatewayd.socket</refname>
  48     <refname>systemd-journal-gatewayd</refname>
  49     <refpurpose>HTTP server for journal events</refpurpose>
  50   </refnamediv>
  51
  52   <refsynopsisdiv>
  53     <para><filename>systemd-journal-gatewayd.service</filename></para>
  54     <para><filename>systemd-journal-gatewayd.socket</filename></para>
  55     <cmdsynopsis><command>/usr/lib/systemd/systemd-journal-gatewayd</command>
  56     </cmdsynopsis>
  57   </refsynopsisdiv>
  58
  59   <refsect1>
  60     <title>Description</title>
  61
  62     <para><command>systemd-journal-gatewayd</command> serves journal
  63     events over the network. Clients must connect using
  64     HTTP, to port 19531 by default.</para>
  65
  66     <para>The program is started by
  67     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  68     and expects to receive a single socket. Use
  69     <command>systemctl start systemd-journal-gatewayd.socket</command> to start
  70     the service, and <command>systemctl enable systemd-journal-gatewayd.socket</command>
  71     to have it started on boot.</para>
  72   </refsect1>
  73
  74   <refsect1>
  75     <title>Supported URLs</title>
  76
  77     <para>The following URLs are recognized:</para>
  78
  79     <variablelist>
  80       <varlistentry>
  81         <term><option>/browse</option></term>
  82
  83         <listitem><para>Interactive browsing.</para></listitem>
  84       </varlistentry>
  85
  86       <varlistentry>
  87         <term><option>/entries[?option1&amp;option2=value...]</option></term>
  88
  89         <listitem><para>Retrieval of events in various formats.</para>
  90
  91         <para>The <option>Accept:</option> part of the HTTP header
  92         determines the format. Supported values are described below.
  93         </para>
  94
  95         <para>The <option>Range:</option> part of the HTTP header
  96         determines the range of events returned. Supported values are
  97         described below.
  98         </para>
  99
 100         <para>GET parameters can be used to modify what events are
 101         returned. Supported parameters are described below.</para>
 102         </listitem>
 103       </varlistentry>
 104     </variablelist>
 105   </refsect1>
 106
 107   <refsect1>
 108     <title>Accept header</title>
 109
 110     <para>
 111       <option>Accept: &lt;format&gt;</option>
 112     </para>
 113
 114     <para>Recognized formats:</para>
 115
 116     <variablelist>
 117       <varlistentry>
 118         <term><option>text/plain</option></term>
 119
 120         <listitem><para>The default. Plaintext syslog-like output,
 121         one line per journal entry
 122         (like <command>journalctl --output short</command>).</para>
 123         </listitem>
 124       </varlistentry>
 125
 126       <varlistentry>
 127         <term><option>application/json</option></term>
 128
 129         <listitem><para>Entries are formatted as JSON data structures,
 130         one per line
 131         (like <command>journalctl --output json</command>).
 132         See <ulink
 133         url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
 134         JSON Format</ulink> for more information.</para>
 135         </listitem>
 136       </varlistentry>
 137
 138       <varlistentry>
 139         <term><option>application/event-stream</option></term>
 140
 141         <listitem><para>Entries are formatted as JSON data structures,
 142         wrapped in a format suitable for <ulink
 143         url="https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events">
 144         Server-Sent Events</ulink>
 145         (like <command>journalctl --output json-sse</command>).
 146         </para>
 147         </listitem>
 148       </varlistentry>
 149
 150       <varlistentry>
 151         <term><option>application/vnd.fdo.journal</option></term>
 152
 153         <listitem><para>Entries are serialized into a binary (but
 154         mostly text-based) stream suitable for backups and network
 155         transfer
 156         (like <command>journalctl --output export</command>).
 157         See <ulink
 158         url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
 159         Export Format</ulink> for more information.</para>
 160         </listitem>
 161       </varlistentry>
 162     </variablelist>
 163   </refsect1>
 164
 165   <refsect1>
 166     <title>Range header</title>
 167
 168     <para>
 169       <option>Range: entries=&lt;cursor&gt;[[:&lt;num_skip&gt;]:&lt;num_entries&gt;]</option>
 170     </para>
 171
 172     <para>where
 173       <option>cursor</option> is a cursor string,
 174       <option>num_skip</option> is an integer,
 175       <option>num_entries</option> is an unsigned integer.
 176     </para>
 177
 178     <para>Range defaults to all available events.</para>
 179   </refsect1>
 180
 181   <refsect1>
 182     <title>URL GET parameters</title>
 183
 184     <para>Following parameters can be used as part of the URL:</para>
 185
 186     <variablelist>
 187       <varlistentry>
 188         <term><option>follow</option></term>
 189
 190         <listitem><para>wait for new events
 191         (like <command>journalctl --follow</command>, except that
 192         the number of events returned is not limited).</para>
 193         </listitem>
 194       </varlistentry>
 195
 196       <varlistentry>
 197         <term><option>discrete</option></term>
 198
 199         <listitem><para>Test that the specified cursor refers to an
 200         entry in the journal. Returns just this entry.</para>
 201         </listitem>
 202       </varlistentry>
 203
 204       <varlistentry>
 205         <term><option>boot</option></term>
 206
 207         <listitem><para>Limit events to the current boot of the system
 208         (like <command>journalctl --this--boot</command>).</para></listitem>
 209       </varlistentry>
 210
 211       <varlistentry>
 212         <term><option>&lt;KEY&gt;=&lt;match&gt;</option></term>
 213
 214         <listitem><para>Match journal fields. See
 215         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 216         </listitem>
 217       </varlistentry>
 218     </variablelist>
 219   </refsect1>
 220
 221   <refsect1>
 222     <title>Examples</title>
 223     <para>Retrieve events from this boot from local journal
 224     in <ulink
 225     url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
 226     Export Format</ulink>:
 227     <programlisting>
 228 curl --silent -H'Accept: application/vnd.fdo.journal' \
 229        'http://localhost:19531/entries?boot'
 230     </programlisting>
 231     </para>
 232
 233     <para>Listen for core dumps:
 234     <programlisting>
 235 curl 'http://localhost:19531/entries?follow&amp;MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1'
 236     </programlisting></para>
 237   </refsect1>
 238
 239   <refsect1>
 240     <title>See Also</title>
 241     <para>
 242       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 243       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 244       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 245       <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 246     </para>
 247   </refsect1>
 248
 249 </refentry>