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" conditional='HAVE_MICROHTTPD'>
  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>
  56       <command>/usr/lib/systemd/systemd-journal-gatewayd</command>
  57       <arg choice="opt" rep="repeat">OPTIONS</arg>
  58     </cmdsynopsis>
  59   </refsynopsisdiv>
  60
  61   <refsect1>
  62     <title>Description</title>
  63
  64     <para><command>systemd-journal-gatewayd</command> serves journal
  65     events over the network. Clients must connect using
  66     HTTP. The server listens on port 19531 by default.
  67     If <option>--cert=</option> is specified, the server expects
  68     HTTPS connections.</para>
  69
  70     <para>The program is started by
  71     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  72     and expects to receive a single socket. Use
  73     <command>systemctl start systemd-journal-gatewayd.socket</command> to start
  74     the service, and <command>systemctl enable systemd-journal-gatewayd.socket</command>
  75     to have it started on boot.</para>
  76   </refsect1>
  77
  78   <refsect1>
  79     <title>Options</title>
  80
  81     <para>The following options are understood:</para>
  82
  83     <variablelist>
  84       <varlistentry>
  85         <term><option>--help</option></term>
  86         <term><option>-h</option></term>
  87
  88         <listitem><para>Prints a short help
  89         text and exits.</para></listitem>
  90       </varlistentry>
  91
  92       <varlistentry>
  93         <term><option>--version</option></term>
  94
  95         <listitem><para>Prints a short version
  96         string and exits.</para></listitem>
  97       </varlistentry>
  98
  99       <varlistentry>
 100         <term><option>--cert=</option></term>
 101
 102         <listitem><para>Specify the path to a file containing a server
 103         certificate in PEM format. This option switches
 104         <command>systemd-journal-gatewayd</command> into HTTPS mode
 105         and must be used together with
 106         <option>--key=</option>.</para></listitem>
 107       </varlistentry>
 108
 109       <varlistentry>
 110         <term><option>--key=</option></term>
 111
 112         <listitem><para>Specify the path to a file containing a server
 113         key in PEM format corresponding to the certificate specified
 114         with <option>--cert=</option>.</para></listitem>
 115       </varlistentry>
 116
 117     </variablelist>
 118   </refsect1>
 119
 120   <refsect1>
 121     <title>Supported URLs</title>
 122
 123     <para>The following URLs are recognized:</para>
 124
 125     <variablelist>
 126       <varlistentry>
 127         <term><uri>/browse</uri></term>
 128
 129         <listitem><para>Interactive browsing.</para></listitem>
 130       </varlistentry>
 131
 132       <varlistentry>
 133         <term><uri>/entries[?option1&amp;option2=value...]</uri></term>
 134
 135         <listitem><para>Retrieval of events in various formats.</para>
 136
 137         <para>The <option>Accept:</option> part of the HTTP header
 138         determines the format. Supported values are described below.
 139         </para>
 140
 141         <para>The <option>Range:</option> part of the HTTP header
 142         determines the range of events returned. Supported values are
 143         described below.
 144         </para>
 145
 146         <para>GET parameters can be used to modify what events are
 147         returned. Supported parameters are described below.</para>
 148         </listitem>
 149       </varlistentry>
 150
 151       <varlistentry>
 152         <term><uri>/machine</uri></term>
 153
 154         <listitem><para>Return a JSON structure describing the machine.</para>
 155
 156         <para>Example:
 157         <programlisting>{ "machine_id" : "8cf7ed9d451ea194b77a9f118f3dc446",
 158   "boot_id" : "3d3c9efaf556496a9b04259ee35df7f7",
 159   "hostname" : "fedora",
 160   "os_pretty_name" : "Fedora 19 (Rawhide)",
 161   "virtualization" : "kvm",
 162   ...}</programlisting>
 163         </para>
 164         </listitem>
 165       </varlistentry>
 166
 167       <varlistentry>
 168         <term><uri>/fields/<replaceable>FIELD_NAME</replaceable></uri></term>
 169
 170         <listitem><para>Return a list of values of this field present in the logs.</para>
 171         </listitem>
 172       </varlistentry>
 173     </variablelist>
 174   </refsect1>
 175
 176   <refsect1>
 177     <title>Accept header</title>
 178
 179     <para>
 180       <option>Accept: <replaceable>format</replaceable></option>
 181     </para>
 182
 183     <para>Recognized formats:</para>
 184
 185     <variablelist>
 186       <varlistentry>
 187         <term><constant>text/plain</constant></term>
 188
 189         <listitem><para>The default. Plaintext syslog-like output,
 190         one line per journal entry
 191         (like <command>journalctl --output short</command>).</para>
 192         </listitem>
 193       </varlistentry>
 194
 195       <varlistentry>
 196         <term><constant>application/json</constant></term>
 197
 198         <listitem><para>Entries are formatted as JSON data structures,
 199         one per line
 200         (like <command>journalctl --output json</command>).
 201         See <ulink
 202         url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
 203         JSON Format</ulink> for more information.</para>
 204         </listitem>
 205       </varlistentry>
 206
 207       <varlistentry>
 208         <term><constant>application/event-stream</constant></term>
 209
 210         <listitem><para>Entries are formatted as JSON data structures,
 211         wrapped in a format suitable for <ulink
 212         url="https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events">
 213         Server-Sent Events</ulink>
 214         (like <command>journalctl --output json-sse</command>).
 215         </para>
 216         </listitem>
 217       </varlistentry>
 218
 219       <varlistentry>
 220         <term><constant>application/vnd.fdo.journal</constant></term>
 221
 222         <listitem><para>Entries are serialized into a binary (but
 223         mostly text-based) stream suitable for backups and network
 224         transfer
 225         (like <command>journalctl --output export</command>).
 226         See <ulink
 227         url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
 228         Export Format</ulink> for more information.</para>
 229         </listitem>
 230       </varlistentry>
 231     </variablelist>
 232   </refsect1>
 233
 234   <refsect1>
 235     <title>Range header</title>
 236
 237     <para>
 238       <option>Range: entries=<replaceable>cursor</replaceable>[[:<replaceable>num_skip</replaceable>]:<replaceable>num_entries</replaceable>]</option>
 239     </para>
 240
 241     <para>where
 242       <option>cursor</option> is a cursor string,
 243       <option>num_skip</option> is an integer,
 244       <option>num_entries</option> is an unsigned integer.
 245     </para>
 246
 247     <para>Range defaults to all available events.</para>
 248   </refsect1>
 249
 250   <refsect1>
 251     <title>URL GET parameters</title>
 252
 253     <para>Following parameters can be used as part of the URL:</para>
 254
 255     <variablelist>
 256       <varlistentry>
 257         <term><uri>follow</uri></term>
 258
 259         <listitem><para>wait for new events
 260         (like <command>journalctl --follow</command>, except that
 261         the number of events returned is not limited).</para>
 262         </listitem>
 263       </varlistentry>
 264
 265       <varlistentry>
 266         <term><uri>discrete</uri></term>
 267
 268         <listitem><para>Test that the specified cursor refers to an
 269         entry in the journal. Returns just this entry.</para>
 270         </listitem>
 271       </varlistentry>
 272
 273       <varlistentry>
 274         <term><uri>boot</uri></term>
 275
 276         <listitem><para>Limit events to the current boot of the system
 277         (like <command>journalctl --this--boot</command>).</para></listitem>
 278       </varlistentry>
 279
 280       <varlistentry>
 281         <term><uri><replaceable>KEY</replaceable>=<replaceable>match</replaceable></uri></term>
 282
 283         <listitem><para>Match journal fields. See
 284         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 285         </listitem>
 286       </varlistentry>
 287     </variablelist>
 288   </refsect1>
 289
 290   <refsect1>
 291     <title>Examples</title>
 292     <para>Retrieve events from this boot from local journal
 293     in <ulink
 294     url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
 295     Export Format</ulink>:
 296     <programlisting>curl --silent -H'Accept: application/vnd.fdo.journal' \
 297        'http://localhost:19531/entries?boot'</programlisting>
 298     </para>
 299
 300     <para>Listen for core dumps:
 301     <programlisting>curl 'http://localhost:19531/entries?follow&amp;MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1'</programlisting></para>
 302   </refsect1>
 303
 304   <refsect1>
 305     <title>See Also</title>
 306     <para>
 307       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 308       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 309       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 310       <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 311     </para>
 312   </refsect1>
 313
 314 </refentry>