man/systemd-journal-gatewayd.service.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd-journal-gatewayd.service" conditional='ENABLE_REMOTE HAVE_MICROHTTPD'
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>systemd-journal-gatewayd.service</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>systemd-journal-gatewayd.service</refentrytitle>
  16     <manvolnum>8</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>systemd-journal-gatewayd.service</refname>
  21     <refname>systemd-journal-gatewayd.socket</refname>
  22     <refname>systemd-journal-gatewayd</refname>
  23     <refpurpose>HTTP server for journal events</refpurpose>
  24   </refnamediv>
  25
  26   <refsynopsisdiv>
  27     <para><filename>systemd-journal-gatewayd.service</filename></para>
  28     <para><filename>systemd-journal-gatewayd.socket</filename></para>
  29     <cmdsynopsis>
  30       <command>/usr/lib/systemd/systemd-journal-gatewayd</command>
  31       <arg choice="opt" rep="repeat">OPTIONS</arg>
  32     </cmdsynopsis>
  33   </refsynopsisdiv>
  34
  35   <refsect1>
  36     <title>Description</title>
  37
  38     <para><command>systemd-journal-gatewayd</command> serves journal
  39     events over the network. Clients must connect using
  40     HTTP. The server listens on port 19531 by default.
  41     If <option>--cert=</option> is specified, the server expects
  42     HTTPS connections.</para>
  43
  44     <para>The program is started by
  45     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  46     and expects to receive a single socket. Use
  47     <command>systemctl start systemd-journal-gatewayd.socket</command> to start
  48     the service, and <command>systemctl enable systemd-journal-gatewayd.socket</command>
  49     to have it started on boot.</para>
  50   </refsect1>
  51
  52   <refsect1>
  53     <title>Options</title>
  54
  55     <para>The following options are understood:</para>
  56
  57     <variablelist>
  58       <varlistentry>
  59         <term><option>--cert=</option></term>
  60
  61         <listitem><para>Specify the path to a file or <constant>AF_UNIX</constant> stream socket to read the
  62         server certificate from. The certificate must be in PEM format. This option switches
  63         <command>systemd-journal-gatewayd</command> into HTTPS mode and must be used together with
  64         <option>--key=</option>.</para>
  65
  66         <xi:include href="version-info.xml" xpointer="v198"/></listitem>
  67       </varlistentry>
  68
  69       <varlistentry>
  70         <term><option>--key=</option></term>
  71
  72         <listitem><para>Specify the path to a file or <constant>AF_UNIX</constant> stream socket to read the
  73         secret server key corresponding to the certificate specified with <option>--cert=</option> from. The
  74         key must be in PEM format.</para>
  75
  76         <xi:include href="version-info.xml" xpointer="v198"/></listitem>
  77       </varlistentry>
  78
  79       <varlistentry>
  80         <term><option>--trust=</option></term>
  81
  82         <listitem><para>Specify the path to a file or <constant>AF_UNIX</constant> stream socket to read a CA
  83         certificate from. The certificate must be in PEM format.</para>
  84
  85         <xi:include href="version-info.xml" xpointer="v236"/></listitem>
  86       </varlistentry>
  87
  88       <varlistentry>
  89         <term><option>--system</option></term>
  90         <term><option>--user</option></term>
  91
  92         <listitem><para>Limit served entries to entries from system
  93         services and the kernel, or to entries from services of
  94         current user. This has the same meaning as
  95         <option>--system</option> and <option>--user</option> options
  96         for
  97         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If
  98         neither is specified, all accessible entries are served.
  99         </para>
 100
 101         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 102       </varlistentry>
 103
 104       <varlistentry>
 105         <term><option>-m</option></term>
 106         <term><option>--merge</option></term>
 107
 108         <listitem><para>Serve entries interleaved from all available
 109         journals, including other machines. This has the same meaning
 110         as <option>--merge</option> option for
 111         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
 112
 113         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 114       </varlistentry>
 115
 116       <varlistentry>
 117         <term><option>-D <replaceable>DIR</replaceable></option></term>
 118         <term><option>--directory=<replaceable>DIR</replaceable></option></term>
 119
 120         <listitem><para>Takes a directory path as argument. If
 121         specified, <command>systemd-journal-gatewayd</command> will serve the
 122         specified journal directory <replaceable>DIR</replaceable> instead of
 123         the default runtime and system journal paths.</para>
 124
 125         <xi:include href="version-info.xml" xpointer="v232"/></listitem>
 126       </varlistentry>
 127
 128       <varlistentry>
 129         <term><option>--file=<replaceable>GLOB</replaceable></option></term>
 130
 131         <listitem><para>Takes a file glob as an argument. Serve
 132         entries from the specified journal files matching
 133         <replaceable>GLOB</replaceable> instead of the default runtime
 134         and system journal paths. May be specified multiple times, in
 135         which case files will be suitably interleaved. This has the same meaning as
 136         <option>--file=</option> option for
 137         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 138         </para>
 139
 140         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 141       </varlistentry>
 142
 143       <xi:include href="standard-options.xml" xpointer="help" />
 144       <xi:include href="standard-options.xml" xpointer="version" />
 145     </variablelist>
 146   </refsect1>
 147
 148   <refsect1>
 149     <title>Supported URLs</title>
 150
 151     <para>The following URLs are recognized:</para>
 152
 153     <variablelist>
 154       <varlistentry>
 155         <term><uri>/browse</uri></term>
 156
 157         <listitem><para>Interactive browsing.</para>
 158
 159         <xi:include href="version-info.xml" xpointer="v197"/></listitem>
 160       </varlistentry>
 161
 162       <varlistentry>
 163         <term><uri>/entries[?option1&amp;option2=value…]</uri></term>
 164
 165         <listitem><para>Retrieval of events in various formats.</para>
 166
 167         <para>The <option>Accept:</option> part of the HTTP header
 168         determines the format. Supported values are described below.
 169         </para>
 170
 171         <para>The <option>Range:</option> part of the HTTP header
 172         determines the range of events returned. Supported values are
 173         described below.
 174         </para>
 175
 176         <para>GET parameters can be used to modify what events are
 177         returned. Supported parameters are described below.</para>
 178
 179         <xi:include href="version-info.xml" xpointer="v197"/>
 180         </listitem>
 181       </varlistentry>
 182
 183       <varlistentry>
 184         <term><uri>/machine</uri></term>
 185
 186         <listitem><para>Return a JSON structure describing the machine.</para>
 187
 188         <para>Example:
 189         <programlisting>{ "machine_id" : "8cf7ed9d451ea194b77a9f118f3dc446",
 190   "boot_id" : "3d3c9efaf556496a9b04259ee35df7f7",
 191   "hostname" : "fedora",
 192   "os_pretty_name" : "Fedora 19 (Rawhide)",
 193   "virtualization" : "kvm",
 194   …}</programlisting>
 195         </para>
 196
 197         <xi:include href="version-info.xml" xpointer="v197"/>
 198         </listitem>
 199       </varlistentry>
 200
 201       <varlistentry>
 202         <term><uri>/fields/<replaceable>FIELD_NAME</replaceable></uri></term>
 203
 204         <listitem><para>Return a list of values of this field present in the logs.</para>
 205
 206         <xi:include href="version-info.xml" xpointer="v197"/>
 207         </listitem>
 208       </varlistentry>
 209     </variablelist>
 210   </refsect1>
 211
 212   <refsect1>
 213     <title>Accept header</title>
 214
 215     <para>
 216       <option>Accept: <replaceable>format</replaceable></option>
 217     </para>
 218
 219     <para>Recognized formats:</para>
 220
 221     <variablelist>
 222       <varlistentry>
 223         <term><constant>text/plain</constant></term>
 224
 225         <listitem><para>The default. Plaintext syslog-like output,
 226         one line per journal entry
 227         (like <command>journalctl --output short</command>).</para>
 228
 229         <xi:include href="version-info.xml" xpointer="v197"/>
 230         </listitem>
 231       </varlistentry>
 232
 233       <varlistentry>
 234         <term><constant>application/json</constant></term>
 235
 236         <listitem><para>Entries are formatted as JSON data structures,
 237         one per line
 238         (like <command>journalctl --output json</command>).
 239         See <ulink url="https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-json-format">Journal JSON Format</ulink>
 240         for more information.</para>
 241
 242         <xi:include href="version-info.xml" xpointer="v197"/>
 243         </listitem>
 244       </varlistentry>
 245
 246       <varlistentry>
 247         <term><constant>text/event-stream</constant></term>
 248
 249         <listitem><para>Entries are formatted as JSON data structures,
 250         wrapped in a format suitable for <ulink
 251         url="https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events">
 252         Server-Sent Events</ulink>
 253         (like <command>journalctl --output json-sse</command>).
 254         </para>
 255
 256         <xi:include href="version-info.xml" xpointer="v229"/>
 257         </listitem>
 258       </varlistentry>
 259
 260       <varlistentry>
 261         <term><constant>application/vnd.fdo.journal</constant></term>
 262
 263         <listitem><para>Entries are serialized into a binary (but mostly text-based) stream suitable for
 264         backups and network transfer (like <command>journalctl --output export</command>).  See <ulink
 265         url="https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format">Journal Export Format</ulink>
 266         for more information.</para>
 267
 268         <xi:include href="version-info.xml" xpointer="v197"/>
 269         </listitem>
 270       </varlistentry>
 271     </variablelist>
 272   </refsect1>
 273
 274   <refsect1>
 275     <title>Range header</title>
 276
 277     <para>
 278       <option>Range: entries=<replaceable>cursor</replaceable>[[:<replaceable>num_skip</replaceable>]:<replaceable>num_entries</replaceable>]</option>
 279     </para>
 280     <para>
 281       <option>Range: realtime=[<replaceable>since</replaceable>]:[<replaceable>until</replaceable>][[:<replaceable>num_skip</replaceable>]:<replaceable>num_entries</replaceable>]</option>
 282     </para>
 283
 284     <para>where
 285       <replaceable>cursor</replaceable> is a cursor string,
 286       <replaceable>since</replaceable> and <replaceable>until</replaceable> are timestamps (seconds since 1970-01-01 00:00:00 UTC),
 287       <replaceable>num_skip</replaceable> is an integer,
 288       <replaceable>num_entries</replaceable> is an unsigned integer.
 289     </para>
 290
 291     <para>Range defaults to all available events.</para>
 292   </refsect1>
 293
 294   <refsect1>
 295     <title>URL GET parameters</title>
 296
 297     <para>Following parameters can be used as part of the URL:</para>
 298
 299     <variablelist>
 300       <varlistentry>
 301         <term><uri>follow</uri></term>
 302
 303         <listitem><para>wait for new events
 304         (like <command>journalctl --follow</command>, except that
 305         the number of events returned is not limited).</para>
 306
 307         <xi:include href="version-info.xml" xpointer="v197"/>
 308         </listitem>
 309       </varlistentry>
 310
 311       <varlistentry>
 312         <term><uri>discrete</uri></term>
 313
 314         <listitem><para>Test that the specified cursor refers to an
 315         entry in the journal. Returns just this entry.</para>
 316
 317         <xi:include href="version-info.xml" xpointer="v197"/>
 318         </listitem>
 319       </varlistentry>
 320
 321       <varlistentry>
 322         <term><uri>boot</uri></term>
 323
 324         <listitem><para>Limit events to the current boot of the system
 325         (like <command>journalctl -b</command>).</para>
 326
 327         <xi:include href="version-info.xml" xpointer="v197"/></listitem>
 328       </varlistentry>
 329
 330       <varlistentry>
 331         <term><uri><replaceable>KEY</replaceable>=<replaceable>match</replaceable></uri></term>
 332
 333         <listitem><para>Match journal fields. See
 334         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 335
 336         <xi:include href="version-info.xml" xpointer="v197"/>
 337         </listitem>
 338       </varlistentry>
 339     </variablelist>
 340   </refsect1>
 341
 342   <refsect1>
 343     <title>Examples</title>
 344     <para>Retrieve events from this boot from local journal in
 345     <ulink url="https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format">Journal Export Format</ulink>:
 346     <programlisting>curl --silent -H'Accept: application/vnd.fdo.journal' \
 347        'http://localhost:19531/entries?boot'</programlisting>
 348     </para>
 349
 350     <para>Listen for core dumps:
 351     <programlisting>curl 'http://localhost:19531/entries?follow&amp;MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1'</programlisting></para>
 352   </refsect1>
 353
 354   <refsect1>
 355     <title>See Also</title>
 356     <para><simplelist type="inline">
 357       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 358       <member><citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 359       <member><citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
 360       <member><citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 361       <member><citerefentry><refentrytitle>systemd-journal-remote.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 362       <member><citerefentry><refentrytitle>systemd-journal-upload.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 363     </simplelist></para>
 364   </refsect1>
 365
 366 </refentry>