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
 105       <varlistentry>
 106         <term><option>/machine</option></term>
 107
 108         <listitem><para>Return a JSON structre describing the machine.</para>
 109
 110         <para>Example:
 111         <programlisting>
 112 { "machine_id" : "8cf7ed9d451ea194b77a9f118f3dc446",
 113   "boot_id" : "3d3c9efaf556496a9b04259ee35df7f7",
 114   "hostname" : "fedora",
 115   "os_pretty_name" : "Fedora 19 (Rawhide)",
 116   "virtualization" : "kvm",
 117   ...}
 118         </programlisting>
 119         </para>
 120         </listitem>
 121       </varlistentry>
 122
 123       <varlistentry>
 124         <term><option>/fields/</option><replaceable>FIELD_NAME</replaceable></term>
 125
 126         <listitem><para>Return a list of values of this field present in the logs.</para>
 127         </listitem>
 128       </varlistentry>
 129     </variablelist>
 130   </refsect1>
 131
 132   <refsect1>
 133     <title>Accept header</title>
 134
 135     <para>
 136       <option>Accept: </option><replaceable>format</replaceable>
 137     </para>
 138
 139     <para>Recognized formats:</para>
 140
 141     <variablelist>
 142       <varlistentry>
 143         <term><option>text/plain</option></term>
 144
 145         <listitem><para>The default. Plaintext syslog-like output,
 146         one line per journal entry
 147         (like <command>journalctl --output short</command>).</para>
 148         </listitem>
 149       </varlistentry>
 150
 151       <varlistentry>
 152         <term><option>application/json</option></term>
 153
 154         <listitem><para>Entries are formatted as JSON data structures,
 155         one per line
 156         (like <command>journalctl --output json</command>).
 157         See <ulink
 158         url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
 159         JSON Format</ulink> for more information.</para>
 160         </listitem>
 161       </varlistentry>
 162
 163       <varlistentry>
 164         <term><option>application/event-stream</option></term>
 165
 166         <listitem><para>Entries are formatted as JSON data structures,
 167         wrapped in a format suitable for <ulink
 168         url="https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events">
 169         Server-Sent Events</ulink>
 170         (like <command>journalctl --output json-sse</command>).
 171         </para>
 172         </listitem>
 173       </varlistentry>
 174
 175       <varlistentry>
 176         <term><option>application/vnd.fdo.journal</option></term>
 177
 178         <listitem><para>Entries are serialized into a binary (but
 179         mostly text-based) stream suitable for backups and network
 180         transfer
 181         (like <command>journalctl --output export</command>).
 182         See <ulink
 183         url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
 184         Export Format</ulink> for more information.</para>
 185         </listitem>
 186       </varlistentry>
 187     </variablelist>
 188   </refsect1>
 189
 190   <refsect1>
 191     <title>Range header</title>
 192
 193     <para>
 194       <option>Range: entries=&lt;cursor&gt;[[:&lt;num_skip&gt;]:&lt;num_entries&gt;]</option>
 195     </para>
 196
 197     <para>where
 198       <option>cursor</option> is a cursor string,
 199       <option>num_skip</option> is an integer,
 200       <option>num_entries</option> is an unsigned integer.
 201     </para>
 202
 203     <para>Range defaults to all available events.</para>
 204   </refsect1>
 205
 206   <refsect1>
 207     <title>URL GET parameters</title>
 208
 209     <para>Following parameters can be used as part of the URL:</para>
 210
 211     <variablelist>
 212       <varlistentry>
 213         <term><option>follow</option></term>
 214
 215         <listitem><para>wait for new events
 216         (like <command>journalctl --follow</command>, except that
 217         the number of events returned is not limited).</para>
 218         </listitem>
 219       </varlistentry>
 220
 221       <varlistentry>
 222         <term><option>discrete</option></term>
 223
 224         <listitem><para>Test that the specified cursor refers to an
 225         entry in the journal. Returns just this entry.</para>
 226         </listitem>
 227       </varlistentry>
 228
 229       <varlistentry>
 230         <term><option>boot</option></term>
 231
 232         <listitem><para>Limit events to the current boot of the system
 233         (like <command>journalctl --this--boot</command>).</para></listitem>
 234       </varlistentry>
 235
 236       <varlistentry>
 237         <term><option>&lt;KEY&gt;=&lt;match&gt;</option></term>
 238
 239         <listitem><para>Match journal fields. See
 240         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 241         </listitem>
 242       </varlistentry>
 243     </variablelist>
 244   </refsect1>
 245
 246   <refsect1>
 247     <title>Examples</title>
 248     <para>Retrieve events from this boot from local journal
 249     in <ulink
 250     url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
 251     Export Format</ulink>:
 252     <programlisting>
 253 curl --silent -H'Accept: application/vnd.fdo.journal' \
 254        'http://localhost:19531/entries?boot'
 255     </programlisting>
 256     </para>
 257
 258     <para>Listen for core dumps:
 259     <programlisting>
 260 curl 'http://localhost:19531/entries?follow&amp;MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1'
 261     </programlisting></para>
 262   </refsect1>
 263
 264   <refsect1>
 265     <title>See Also</title>
 266     <para>
 267       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 268       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 269       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 270       <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 271     </para>
 272   </refsect1>
 273
 274 </refentry>