man/systemd-journal-gatewayd.service.xml

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