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   SPDX-License-Identifier: LGPL-2.1+
   7
   8   This file is part of systemd.
   9
  10   Copyright 2012 Zbigniew Jędrzejewski-Szmek
  11
  12   systemd is free software; you can redistribute it and/or modify it
  13   under the terms of the GNU Lesser General Public License as published by
  14   the Free Software Foundation; either version 2.1 of the License, or
  15   (at your option) any later version.
  16
  17   systemd is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public License
  23   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  24 -->
  25
  26 <refentry id="systemd-journal-gatewayd.service" conditional='HAVE_MICROHTTPD'
  27           xmlns:xi="http://www.w3.org/2001/XInclude">
  28
  29   <refentryinfo>
  30     <title>systemd-journal-gatewayd.service</title>
  31     <productname>systemd</productname>
  32
  33     <authorgroup>
  34       <author>
  35         <contrib>Developer</contrib>
  36         <firstname>Zbigniew</firstname>
  37         <surname>Jędrzejewski-Szmek</surname>
  38         <email>zbyszek@in.waw.pl</email>
  39       </author>
  40     </authorgroup>
  41   </refentryinfo>
  42
  43   <refmeta>
  44     <refentrytitle>systemd-journal-gatewayd.service</refentrytitle>
  45     <manvolnum>8</manvolnum>
  46   </refmeta>
  47
  48   <refnamediv>
  49     <refname>systemd-journal-gatewayd.service</refname>
  50     <refname>systemd-journal-gatewayd.socket</refname>
  51     <refname>systemd-journal-gatewayd</refname>
  52     <refpurpose>HTTP server for journal events</refpurpose>
  53   </refnamediv>
  54
  55   <refsynopsisdiv>
  56     <para><filename>systemd-journal-gatewayd.service</filename></para>
  57     <para><filename>systemd-journal-gatewayd.socket</filename></para>
  58     <cmdsynopsis>
  59       <command>/usr/lib/systemd/systemd-journal-gatewayd</command>
  60       <arg choice="opt" rep="repeat">OPTIONS</arg>
  61     </cmdsynopsis>
  62   </refsynopsisdiv>
  63
  64   <refsect1>
  65     <title>Description</title>
  66
  67     <para><command>systemd-journal-gatewayd</command> serves journal
  68     events over the network. Clients must connect using
  69     HTTP. The server listens on port 19531 by default.
  70     If <option>--cert=</option> is specified, the server expects
  71     HTTPS connections.</para>
  72
  73     <para>The program is started by
  74     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  75     and expects to receive a single socket. Use
  76     <command>systemctl start systemd-journal-gatewayd.socket</command> to start
  77     the service, and <command>systemctl enable systemd-journal-gatewayd.socket</command>
  78     to have it started on boot.</para>
  79   </refsect1>
  80
  81   <refsect1>
  82     <title>Options</title>
  83
  84     <para>The following options are understood:</para>
  85
  86     <variablelist>
  87       <varlistentry>
  88         <term><option>--cert=</option></term>
  89
  90         <listitem><para>Specify the path to a file containing a server
  91         certificate in PEM format. This option switches
  92         <command>systemd-journal-gatewayd</command> into HTTPS mode
  93         and must be used together with
  94         <option>--key=</option>.</para></listitem>
  95       </varlistentry>
  96
  97       <varlistentry>
  98         <term><option>--key=</option></term>
  99
 100         <listitem><para>Specify the path to a file containing a server
 101         key in PEM format corresponding to the certificate specified
 102         with <option>--cert=</option>.</para></listitem>
 103       </varlistentry>
 104
 105       <varlistentry>
 106         <term><option>-D <replaceable>DIR</replaceable></option></term>
 107         <term><option>--directory=<replaceable>DIR</replaceable></option></term>
 108
 109         <listitem><para>Takes a directory path as argument. If
 110         specified, <command>systemd-journal-gatewayd</command> will serve the
 111         specified journal directory <replaceable>DIR</replaceable> instead of
 112         the default runtime and system journal paths.</para></listitem>
 113       </varlistentry>
 114
 115       <xi:include href="standard-options.xml" xpointer="help" />
 116       <xi:include href="standard-options.xml" xpointer="version" />
 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="https://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>text/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="https://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="https://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>