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>
 158 { "machine_id" : "8cf7ed9d451ea194b77a9f118f3dc446",
 159   "boot_id" : "3d3c9efaf556496a9b04259ee35df7f7",
 160   "hostname" : "fedora",
 161   "os_pretty_name" : "Fedora 19 (Rawhide)",
 162   "virtualization" : "kvm",
 163   ...}
 164         </programlisting>
 165         </para>
 166         </listitem>
 167       </varlistentry>
 168
 169       <varlistentry>
 170         <term><uri>/fields/<replaceable>FIELD_NAME</replaceable></uri></term>
 171
 172         <listitem><para>Return a list of values of this field present in the logs.</para>
 173         </listitem>
 174       </varlistentry>
 175     </variablelist>
 176   </refsect1>
 177
 178   <refsect1>
 179     <title>Accept header</title>
 180
 181     <para>
 182       <option>Accept: <replaceable>format</replaceable></option>
 183     </para>
 184
 185     <para>Recognized formats:</para>
 186
 187     <variablelist>
 188       <varlistentry>
 189         <term><constant>text/plain</constant></term>
 190
 191         <listitem><para>The default. Plaintext syslog-like output,
 192         one line per journal entry
 193         (like <command>journalctl --output short</command>).</para>
 194         </listitem>
 195       </varlistentry>
 196
 197       <varlistentry>
 198         <term><constant>application/json</constant></term>
 199
 200         <listitem><para>Entries are formatted as JSON data structures,
 201         one per line
 202         (like <command>journalctl --output json</command>).
 203         See <ulink
 204         url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal
 205         JSON Format</ulink> for more information.</para>
 206         </listitem>
 207       </varlistentry>
 208
 209       <varlistentry>
 210         <term><constant>application/event-stream</constant></term>
 211
 212         <listitem><para>Entries are formatted as JSON data structures,
 213         wrapped in a format suitable for <ulink
 214         url="https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events">
 215         Server-Sent Events</ulink>
 216         (like <command>journalctl --output json-sse</command>).
 217         </para>
 218         </listitem>
 219       </varlistentry>
 220
 221       <varlistentry>
 222         <term><constant>application/vnd.fdo.journal</constant></term>
 223
 224         <listitem><para>Entries are serialized into a binary (but
 225         mostly text-based) stream suitable for backups and network
 226         transfer
 227         (like <command>journalctl --output export</command>).
 228         See <ulink
 229         url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
 230         Export Format</ulink> for more information.</para>
 231         </listitem>
 232       </varlistentry>
 233     </variablelist>
 234   </refsect1>
 235
 236   <refsect1>
 237     <title>Range header</title>
 238
 239     <para>
 240       <option>Range: entries=<replaceable>cursor</replaceable>[[:<replaceable>num_skip</replaceable>]:<replaceable>num_entries</replaceable>]</option>
 241     </para>
 242
 243     <para>where
 244       <option>cursor</option> is a cursor string,
 245       <option>num_skip</option> is an integer,
 246       <option>num_entries</option> is an unsigned integer.
 247     </para>
 248
 249     <para>Range defaults to all available events.</para>
 250   </refsect1>
 251
 252   <refsect1>
 253     <title>URL GET parameters</title>
 254
 255     <para>Following parameters can be used as part of the URL:</para>
 256
 257     <variablelist>
 258       <varlistentry>
 259         <term><uri>follow</uri></term>
 260
 261         <listitem><para>wait for new events
 262         (like <command>journalctl --follow</command>, except that
 263         the number of events returned is not limited).</para>
 264         </listitem>
 265       </varlistentry>
 266
 267       <varlistentry>
 268         <term><uri>discrete</uri></term>
 269
 270         <listitem><para>Test that the specified cursor refers to an
 271         entry in the journal. Returns just this entry.</para>
 272         </listitem>
 273       </varlistentry>
 274
 275       <varlistentry>
 276         <term><uri>boot</uri></term>
 277
 278         <listitem><para>Limit events to the current boot of the system
 279         (like <command>journalctl --this--boot</command>).</para></listitem>
 280       </varlistentry>
 281
 282       <varlistentry>
 283         <term><uri><replaceable>KEY</replaceable>=<replaceable>match</replaceable></uri></term>
 284
 285         <listitem><para>Match journal fields. See
 286         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 287         </listitem>
 288       </varlistentry>
 289     </variablelist>
 290   </refsect1>
 291
 292   <refsect1>
 293     <title>Examples</title>
 294     <para>Retrieve events from this boot from local journal
 295     in <ulink
 296     url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal
 297     Export Format</ulink>:
 298     <programlisting>
 299 curl --silent -H'Accept: application/vnd.fdo.journal' \
 300        'http://localhost:19531/entries?boot'
 301     </programlisting>
 302     </para>
 303
 304     <para>Listen for core dumps:
 305     <programlisting>
 306 curl 'http://localhost:19531/entries?follow&amp;MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1'
 307     </programlisting></para>
 308   </refsect1>
 309
 310   <refsect1>
 311     <title>See Also</title>
 312     <para>
 313       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 314       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 315       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 316       <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 317     </para>
 318   </refsect1>
 319
 320 </refentry>