diff options
Diffstat (limited to 'man/systemd-journal-gatewayd.service.xml')
| -rw-r--r-- | man/systemd-journal-gatewayd.service.xml | 324 |
1 files changed, 324 insertions, 0 deletions
diff --git a/man/systemd-journal-gatewayd.service.xml b/man/systemd-journal-gatewayd.service.xml new file mode 100644 index 0000000..609d050 --- /dev/null +++ b/man/systemd-journal-gatewayd.service.xml @@ -0,0 +1,324 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> + +<refentry id="systemd-journal-gatewayd.service" conditional='HAVE_MICROHTTPD' + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-journal-gatewayd.service</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-journal-gatewayd.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-journal-gatewayd.service</refname> + <refname>systemd-journal-gatewayd.socket</refname> + <refname>systemd-journal-gatewayd</refname> + <refpurpose>HTTP server for journal events</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-journal-gatewayd.service</filename></para> + <para><filename>systemd-journal-gatewayd.socket</filename></para> + <cmdsynopsis> + <command>/usr/lib/systemd/systemd-journal-gatewayd</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-journal-gatewayd</command> serves journal + events over the network. Clients must connect using + HTTP. The server listens on port 19531 by default. + If <option>--cert=</option> is specified, the server expects + HTTPS connections.</para> + + <para>The program is started by + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and expects to receive a single socket. Use + <command>systemctl start systemd-journal-gatewayd.socket</command> to start + the service, and <command>systemctl enable systemd-journal-gatewayd.socket</command> + to have it started on boot.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--cert=</option></term> + + <listitem><para>Specify the path to a file or <constant>AF_UNIX</constant> stream socket to read the + server certificate from. The certificate must be in PEM format. This option switches + <command>systemd-journal-gatewayd</command> into HTTPS mode and must be used together with + <option>--key=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--key=</option></term> + + <listitem><para>Specify the path to a file or <constant>AF_UNIX</constant> stream socket to read the + secret server key corresponding to the certificate specified with <option>--cert=</option> from. The + key must be in PEM format.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--trust=</option></term> + + <listitem><para>Specify the path to a file or <constant>AF_UNIX</constant> stream socket to read a CA + certificate from. The certificate must be in PEM format.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--system</option></term> + <term><option>--user</option></term> + + <listitem><para>Limit served entries to entries from system + services and the kernel, or to entries from services of + current user. This has the same meaning as + <option>--system</option> and <option>--user</option> options + for + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If + neither is specified, all accessible entries are served. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-m</option></term> + <term><option>--merge</option></term> + + <listitem><para>Serve entries interleaved from all available + journals, including other machines. This has the same meaning + as <option>--merge</option> option for + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-D <replaceable>DIR</replaceable></option></term> + <term><option>--directory=<replaceable>DIR</replaceable></option></term> + + <listitem><para>Takes a directory path as argument. If + specified, <command>systemd-journal-gatewayd</command> will serve the + specified journal directory <replaceable>DIR</replaceable> instead of + the default runtime and system journal paths.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--file=<replaceable>GLOB</replaceable></option></term> + + <listitem><para>Takes a file glob as an argument. Serve + entries from the specified journal files matching + <replaceable>GLOB</replaceable> instead of the default runtime + and system journal paths. May be specified multiple times, in + which case files will be suitably interleaved. This has the same meaning as + <option>--file=</option> option for + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + </refsect1> + + <refsect1> + <title>Supported URLs</title> + + <para>The following URLs are recognized:</para> + + <variablelist> + <varlistentry> + <term><uri>/browse</uri></term> + + <listitem><para>Interactive browsing.</para></listitem> + </varlistentry> + + <varlistentry> + <term><uri>/entries[?option1&option2=value…]</uri></term> + + <listitem><para>Retrieval of events in various formats.</para> + + <para>The <option>Accept:</option> part of the HTTP header + determines the format. Supported values are described below. + </para> + + <para>The <option>Range:</option> part of the HTTP header + determines the range of events returned. Supported values are + described below. + </para> + + <para>GET parameters can be used to modify what events are + returned. Supported parameters are described below.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><uri>/machine</uri></term> + + <listitem><para>Return a JSON structure describing the machine.</para> + + <para>Example: + <programlisting>{ "machine_id" : "8cf7ed9d451ea194b77a9f118f3dc446", + "boot_id" : "3d3c9efaf556496a9b04259ee35df7f7", + "hostname" : "fedora", + "os_pretty_name" : "Fedora 19 (Rawhide)", + "virtualization" : "kvm", + …}</programlisting> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><uri>/fields/<replaceable>FIELD_NAME</replaceable></uri></term> + + <listitem><para>Return a list of values of this field present in the logs.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Accept header</title> + + <para> + <option>Accept: <replaceable>format</replaceable></option> + </para> + + <para>Recognized formats:</para> + + <variablelist> + <varlistentry> + <term><constant>text/plain</constant></term> + + <listitem><para>The default. Plaintext syslog-like output, + one line per journal entry + (like <command>journalctl --output short</command>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>application/json</constant></term> + + <listitem><para>Entries are formatted as JSON data structures, + one per line + (like <command>journalctl --output json</command>). + See <ulink url="https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-json-format">Journal JSON Format</ulink> + for more information.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>text/event-stream</constant></term> + + <listitem><para>Entries are formatted as JSON data structures, + wrapped in a format suitable for <ulink + url="https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events"> + Server-Sent Events</ulink> + (like <command>journalctl --output json-sse</command>). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>application/vnd.fdo.journal</constant></term> + + <listitem><para>Entries are serialized into a binary (but mostly text-based) stream suitable for + backups and network transfer (like <command>journalctl --output export</command>). See <ulink + url="https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format">Journal Export Format</ulink> + for more information.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Range header</title> + + <para> + <option>Range: entries=<replaceable>cursor</replaceable>[[:<replaceable>num_skip</replaceable>]:<replaceable>num_entries</replaceable>]</option> + </para> + + <para>where + <replaceable>cursor</replaceable> is a cursor string, + <replaceable>num_skip</replaceable> is an integer, + <replaceable>num_entries</replaceable> is an unsigned integer. + </para> + + <para>Range defaults to all available events.</para> + </refsect1> + + <refsect1> + <title>URL GET parameters</title> + + <para>Following parameters can be used as part of the URL:</para> + + <variablelist> + <varlistentry> + <term><uri>follow</uri></term> + + <listitem><para>wait for new events + (like <command>journalctl --follow</command>, except that + the number of events returned is not limited).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><uri>discrete</uri></term> + + <listitem><para>Test that the specified cursor refers to an + entry in the journal. Returns just this entry.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><uri>boot</uri></term> + + <listitem><para>Limit events to the current boot of the system + (like <command>journalctl -b</command>).</para></listitem> + </varlistentry> + + <varlistentry> + <term><uri><replaceable>KEY</replaceable>=<replaceable>match</replaceable></uri></term> + + <listitem><para>Match journal fields. See + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <para>Retrieve events from this boot from local journal in + <ulink url="https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format">Journal Export Format</ulink>: + <programlisting>curl --silent -H'Accept: application/vnd.fdo.journal' \ + 'http://localhost:19531/entries?boot'</programlisting> + </para> + + <para>Listen for core dumps: + <programlisting>curl 'http://localhost:19531/entries?follow&MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1'</programlisting></para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-journal-remote.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-journal-upload.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |