man/systemd-journal-gatewayd.service.xml

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