diff options
Diffstat (limited to 'src/grp-journal/grp-remote')
4 files changed, 1011 insertions, 0 deletions
diff --git a/src/grp-journal/grp-remote/systemd-journal-gatewayd/systemd-journal-gatewayd.service.xml b/src/grp-journal/grp-remote/systemd-journal-gatewayd/systemd-journal-gatewayd.service.xml new file mode 100644 index 0000000000..9ed85c3950 --- /dev/null +++ b/src/grp-journal/grp-remote/systemd-journal-gatewayd/systemd-journal-gatewayd.service.xml @@ -0,0 +1,302 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2012 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<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> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </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 containing a server + certificate 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 containing a server + key in PEM format corresponding to the certificate specified + with <option>--cert=</option>.</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="http://www.freedesktop.org/wiki/Software/systemd/json">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="http://www.freedesktop.org/wiki/Software/systemd/export">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 + <option>cursor</option> is a cursor string, + <option>num_skip</option> is an integer, + <option>num_entries</option> 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 --this-boot</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="http://www.freedesktop.org/wiki/Software/systemd/export">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-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + </para> + </refsect1> + +</refentry> diff --git a/src/grp-journal/grp-remote/systemd-journal-remote/journal-remote.conf.xml b/src/grp-journal/grp-remote/systemd-journal-remote/journal-remote.conf.xml new file mode 100644 index 0000000000..2d345963d9 --- /dev/null +++ b/src/grp-journal/grp-remote/systemd-journal-remote/journal-remote.conf.xml @@ -0,0 +1,121 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2015 Chris Morgan + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="journal-remote.conf" conditional='HAVE_MICROHTTPD' + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>journal-remote.conf</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Chris</firstname> + <surname>Morgan</surname> + <email>chmorgan@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>journal-remote.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>journal-remote.conf</refname> + <refname>journal-remote.conf.d</refname> + <refpurpose>Journal remote service configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/journal-remote.conf</filename></para> + <para><filename>/etc/systemd/journald.conf.d/*.conf</filename></para> + <para><filename>/run/systemd/journald.conf.d/*.conf</filename></para> + <para><filename>/usr/lib/systemd/journald.conf.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>These files configure various parameters of the systemd-remote-journal + application, + <citerefentry><refentrytitle>systemd-journal-remote</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="main-conf" /> + + <refsect1> + <title>Options</title> + + <para>All options are configured in the + <literal>[Remote]</literal> section:</para> + + <variablelist> + <varlistentry> + <term><varname>Seal=</varname></term> + + <listitem><para>Periodically sign the data in the journal using Forward Secure Sealing. + </para></listitem> + </varlistentry> + + + <varlistentry> + <term><varname>SplitMode=</varname></term> + + <listitem><para>One of <literal>host</literal> or <literal>none</literal>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ServerKeyFile=</varname></term> + + <listitem><para>SSL key in PEM format.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ServerCertificateFile=</varname></term> + + <listitem><para>SSL CA certificate in PEM format.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TrustedCertificateFile=</varname></term> + + <listitem><para>SSL CA certificate.</para></listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd-journal-remote</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/grp-journal/grp-remote/systemd-journal-remote/systemd-journal-remote.xml b/src/grp-journal/grp-remote/systemd-journal-remote/systemd-journal-remote.xml new file mode 100644 index 0000000000..3899f175d4 --- /dev/null +++ b/src/grp-journal/grp-remote/systemd-journal-remote/systemd-journal-remote.xml @@ -0,0 +1,325 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2012 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-journal-remote" conditional='HAVE_MICROHTTPD' + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-journal-remote</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-journal-remote</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-journal-remote</refname> + <refpurpose>Receive journal messages over the network</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-journal-remote</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="opt" rep="norepeat">-o/--output=<replaceable>DIR</replaceable>|<replaceable>FILE</replaceable></arg> + <arg choice="opt" rep="repeat">SOURCES</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <filename>systemd-journal-remote</filename> is a command to + receive serialized journal events and store them to the journal. + Input streams are in the + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/export"> + Journal Export Format + </ulink>, + i.e. like the output from + <command>journalctl --output=export</command>. For transport over + the network, this serialized stream is usually carried over an + HTTPS connection. + </para> + </refsect1> + + <refsect1> + <title>Sources</title> + + <para> + Sources can be either "active" + (<command>systemd-journal-remote</command> requests and pulls + the data), or "passive" + (<command>systemd-journal-remote</command> waits for a + connection and then receives events pushed by the other side). + </para> + + <para> + <command>systemd-journal-remote</command> can read more than one + event stream at a time. They will be interleaved in the output + file. In case of "active" connections, each "source" is one + stream, and in case of "passive" connections, each connection can + result in a separate stream. Sockets can be configured in + "accept" mode (i.e. only one connection), or "listen" mode (i.e. + multiple connections, each resulting in a stream). + </para> + + <para> + When there are no more connections, and no more can be created + (there are no listening sockets), then + <command>systemd-journal-remote</command> will exit. + </para> + + <para>Active sources can be specified in the following + ways:</para> + + <variablelist> + <varlistentry> + <listitem><para>When <option>-</option> is given as a + positional argument, events will be read from standard input. + Other positional arguments will be treated as filenames + to open and read from.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--url=<replaceable>ADDRESS</replaceable></option></term> + + <listitem><para>With the + <option>--url=<replaceable>ADDRESS</replaceable></option> option, + events will be retrieved using HTTP from + <replaceable>ADDRESS</replaceable>. This URL should refer to the + root of a remote + <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + instance (e.g. <ulink>http://some.host:19531/</ulink> or + <ulink>https://some.host:19531/</ulink>).</para></listitem> + </varlistentry> + </variablelist> + + <para>Passive sources can be specified in the following + ways:</para> + + <variablelist> + <varlistentry> + <term><option>--listen-raw=<replaceable>ADDRESS</replaceable></option></term> + + <listitem><para><replaceable>ADDRESS</replaceable> must be an + address suitable for <option>ListenStream=</option> (cf. + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + <command>systemd-journal-remote</command> will listen on this + socket for connections. Each connection is expected to be a + stream of journal events.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--listen-http=<replaceable>ADDRESS</replaceable></option></term> + <term><option>--listen-https=<replaceable>ADDRESS</replaceable></option></term> + + <listitem><para><replaceable>ADDRESS</replaceable> must be + either a negative integer, in which case it will be + interpreted as the (negated) file descriptor number, or an + address suitable for <option>ListenStream=</option> (c.f. + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + In the first case, matching file descriptor must be inherited + through + <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname>. + In the second case, an HTTP or HTTPS server will be spawned on + this port, respectively for <option>--listen-http</option> and + <option>--listen-https</option>. Currently, only POST requests + to <filename>/upload</filename> with <literal>Content-Type: + application/vnd.fdo.journal</literal> are supported.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>$LISTEN_FDS</varname></term> + + <listitem><para><command>systemd-journal-remote</command> + supports the + <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname> + protocol. Open sockets inherited through socket activation + behave like those opened with <option>--listen-raw=</option> + described above, unless they are specified as an argument in + <option>--listen-http=-<replaceable>n</replaceable></option> + or + <option>--listen-https=-<replaceable>n</replaceable></option> + above. In the latter case, an HTTP or HTTPS server will be + spawned using this descriptor and connections must be made + over the HTTP protocol.</para> + </listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Sinks</title> + + <para>The location of the output journal can be specified + with <option>-o</option> or <option>--output=</option>. For "active" + sources, this option is required. + </para> + + <variablelist> + <varlistentry> + <term><option>--output=<replaceable>FILE</replaceable></option></term> + + <listitem><para>Will write to this journal file. The filename + must end with <filename>.journal</filename>. The file will be + created if it does not exist. If necessary (journal file full, + or corrupted), the file will be renamed following normal + journald rules and a new journal file will be created in its + stead.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--output=<replaceable>DIR</replaceable></option></term> + + <listitem><para>Will create journal files underneath directory + <replaceable>DIR</replaceable>. The directory must exist. If + necessary (journal files over size, or corrupted), journal + files will be rotated following normal journald rules. Names + of files underneath <replaceable>DIR</replaceable> will be + generated using the rules described below.</para></listitem> + </varlistentry> + </variablelist> + + <para>If <option>--output=</option> is not used, the output + directory <filename>/var/log/journal/remote/</filename> will be + used. In case the output file is not specified, journal files + will be created underneath the selected directory. Files will be + called + <filename>remote-<replaceable>hostname</replaceable>.journal</filename>, + where the <replaceable>hostname</replaceable> part is the + escaped hostname of the source endpoint of the connection, or the + numerical address if the hostname cannot be determined.</para> + + <para>In case of "active" sources, the output file name must + always be given explicitly.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--split-mode</option></term> + + <listitem><para>One of <constant>none</constant> or + <constant>host</constant>. For the first, only one output + journal file is used. For the latter, a separate output file + is used, based on the hostname of the other endpoint of a + connection.</para> + + <para>In case of "active" sources, the output file name must + always be given explicitly and only <constant>none</constant> + is allowed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--compress</option></term> + <term><option>--no-compress</option></term> + + <listitem><para>Compress or not, respectively, the data in the + journal using XZ.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--seal</option></term> + <term><option>--no-seal</option></term> + + <listitem><para>Periodically sign or not, respectively, the + data in the journal using Forward Secure Sealing. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--getter=<replaceable>PROG --option1 --option2</replaceable></option></term> + + <listitem><para>Program to invoke to retrieve data. The journal + event stream must be generated on standard output.</para> + + <para>Examples:</para> + + <programlisting>--getter='curl "-HAccept: application/vnd.fdo.journal" https://some.host:19531/'</programlisting> + + <programlisting>--getter='wget --header="Accept: application/vnd.fdo.journal" -O- https://some.host:19531/'</programlisting> + </listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + <para>Copy local journal events to a different journal directory: + <programlisting> +journalctl -o export | systemd-journal-remote -o /tmp/dir - + </programlisting> + </para> + + <para>Retrieve all available events from a remote + <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + instance and store them in + <filename>/var/log/journal/remote/remote-some.host.journal</filename>: + <programlisting> +systemd-journal-remote --url http://some.host:19531/ + </programlisting> + </para> + + <para>Retrieve current boot events and wait for new events from a remote + <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + instance, and store them in + <filename>/var/log/journal/remote/remote-some.host.journal</filename>: + <programlisting> +systemd-journal-remote --url http://some.host:19531/entries?boot&follow + </programlisting> + </para> +</refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd-journal-upload</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-journal-gatewayd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + <citerefentry><refentrytitle>journal-remote.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> +</refentry> diff --git a/src/grp-journal/grp-remote/systemd-journal-upload/systemd-journal-upload.xml b/src/grp-journal/grp-remote/systemd-journal-upload/systemd-journal-upload.xml new file mode 100644 index 0000000000..f9723dea89 --- /dev/null +++ b/src/grp-journal/grp-remote/systemd-journal-upload/systemd-journal-upload.xml @@ -0,0 +1,263 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-journal-upload" conditional='HAVE_MICROHTTPD' + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-journal-upload</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-journal-upload</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-journal-upload</refname> + <refpurpose>Send journal messages over the network</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-journal-upload</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="opt" rep="norepeat">-u/--url=<replaceable>URL</replaceable></arg> + <arg choice="opt" rep="repeat">SOURCES</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>systemd-journal-upload</command> will upload journal + entries to the URL specified with <option>--url</option>. Unless + limited by one of the options specified below, all journal + entries accessible to the user the program is running as will be + uploaded, and then the program will wait and send new entries + as they become available. + </para> + </refsect1> + + <refsect1> + <title>Options</title> + + <variablelist> + <varlistentry> + <term><option>-u</option></term> + <term><option>--url=<optional>https://</optional><replaceable>URL</replaceable></option></term> + <term><option>--url=<optional>http://</optional><replaceable>URL</replaceable></option></term> + + <listitem><para>Upload to the specified + address. <replaceable>URL</replaceable> may specify either + just the hostname or both the protocol and + hostname. <constant>https</constant> is the default. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--system</option></term> + <term><option>--user</option></term> + + <listitem><para>Limit uploaded 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 uploaded. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-m</option></term> + <term><option>--merge</option></term> + + <listitem><para>Upload 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</option></term> + <term><option>--directory=<replaceable>DIR</replaceable></option></term> + + <listitem><para>Takes a directory path as argument. Upload + entries from the specified journal directory + <replaceable>DIR</replaceable> instead of the default runtime + and system journal paths. This has the same meaning as + <option>--directory</option> option for + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--file=<replaceable>GLOB</replaceable></option></term> + + <listitem><para>Takes a file glob as an argument. Upload + 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> + + <varlistentry> + <term><option>--cursor=</option></term> + + <listitem><para>Upload entries from the location in the + journal specified by the passed cursor. This has the same + meaning as <option>--cursor</option> option for + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--after-cursor=</option></term> + + <listitem><para>Upload entries from the location in the + journal <emphasis>after</emphasis> the location specified by + the this cursor. This has the same meaning as + <option>--after-cursor</option> option for + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + + + <varlistentry> + <term><option>--save-state</option><optional>=<replaceable>PATH</replaceable></optional></term> + + <listitem><para>Upload entries from the location in the + journal <emphasis>after</emphasis> the location specified by + the cursor saved in file at <replaceable>PATH</replaceable> + (<filename>/var/lib/systemd/journal-upload/state</filename> by default). + After an entry is successfully uploaded, update this file + with the cursor of that entry. + </para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned; otherwise, a non-zero + failure code is returned.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + <example> + <title>Setting up certificates for authentication</title> + + <para>Certificates signed by a trusted authority are used to + verify that the server to which messages are uploaded is + legitimate, and vice versa, that the client is trusted.</para> + + <para>A suitable set of certificates can be generated with + <command>openssl</command>:</para> + + <programlisting>openssl req -newkey rsa:2048 -days 3650 -x509 -nodes \ + -out ca.pem -keyout ca.key -subj '/CN=Certificate authority/' + +cat >ca.conf <<EOF +[ ca ] +default_ca = this + +[ this ] +new_certs_dir = . +certificate = ca.pem +database = ./index +private_key = ca.key +serial = ./serial +default_days = 3650 +default_md = default +policy = policy_anything + +[ policy_anything ] +countryName = optional +stateOrProvinceName = optional +localityName = optional +organizationName = optional +organizationalUnitName = optional +commonName = supplied +emailAddress = optional +EOF + +touch index +echo 0001 >serial + +SERVER=server +CLIENT=client + +openssl req -newkey rsa:1024 -nodes -out $SERVER.csr -keyout $SERVER.key -subj "/CN=$SERVER/" +openssl ca -batch -config ca.conf -notext -in $SERVER.csr -out $SERVER.pem + +openssl req -newkey rsa:1024 -nodes -out $CLIENT.csr -keyout $CLIENT.key -subj "/CN=$CLIENT/" +openssl ca -batch -config ca.conf -notext -in $CLIENT.csr -out $CLIENT.pem +</programlisting> + + <para>Generated files <filename>ca.pem</filename>, + <filename>server.pem</filename>, and + <filename>server.key</filename> should be installed on server, + and <filename>ca.pem</filename>, + <filename>client.pem</filename>, and + <filename>client.key</filename> on the client. The location of + those files can be specified using + <varname>TrustedCertificateFile=</varname>, + <varname>ServerCertificateFile=</varname>, + <varname>ServerKeyFile=</varname>, in + <filename>/etc/systemd/journal-remote.conf</filename> and + <filename>/etc/systemd/journal-upload.conf</filename>, + respectively. The default locations can be queried by using + <command>systemd-journal-remote --help</command> and + <command>systemd-journal-upload --help</command>.</para> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd-journal-remote</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-journal-gatewayd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> +</refentry> |