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