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