diff options
Diffstat (limited to '')
| -rw-r--r-- | man/systemd-journal-upload.service.xml | 329 |
1 files changed, 329 insertions, 0 deletions
diff --git a/man/systemd-journal-upload.service.xml b/man/systemd-journal-upload.service.xml new file mode 100644 index 0000000..fead24c --- /dev/null +++ b/man/systemd-journal-upload.service.xml @@ -0,0 +1,329 @@ +<?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" [ +<!ENTITY % entities SYSTEM "custom-entities.ent" > +%entities; +]> +<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> + +<refentry id="systemd-journal-upload" conditional='HAVE_MICROHTTPD' + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-journal-upload.service</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-journal-upload.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-journal-upload.service</refname> + <refname>systemd-journal-upload</refname> + <refpurpose>Send journal messages over the network</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-journal-upload.service</filename></para> + <cmdsynopsis> + <command>/usr/lib/systemd/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>. This program reads journal entries from one or more journal files, + similarly to + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + 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> + + <para><command>systemd-journal-upload</command> transfers the raw content of journal file and + uses HTTP as a transport protocol.</para> + + <para><filename>systemd-journal-upload.service</filename> is a system service that uses + <command>systemd-journal-upload</command> to upload journal entries to a server. It uses the + configuration in + <citerefentry><refentrytitle>journal-upload.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + At least the <varname>URL=</varname> option must be specified.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <variablelist> + <varlistentry> + <term><option>-u</option></term> + <term><option>--url=<optional>https://</optional><replaceable>URL</replaceable>[:<replaceable>PORT</replaceable>]</option></term> + <term><option>--url=<optional>http://</optional><replaceable>URL</replaceable>[:<replaceable>PORT</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. + The port number may be specified after a colon (<literal>:</literal>), + otherwise <constant>19532</constant> will be used by default. + </para> + + <xi:include href="version-info.xml" xpointer="v239"/></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> + + <xi:include href="version-info.xml" xpointer="v239"/></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> + + <xi:include href="version-info.xml" xpointer="v239"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--namespace=<replaceable>NAMESPACE</replaceable></option></term> + + <listitem><para>Takes a journal namespace identifier string as argument. Upload + entries from the specified journal namespace + <replaceable>NAMESPACE</replaceable> instead of the default namespace. This has the same meaning as + <option>--namespace=</option> option for + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para> + + <xi:include href="version-info.xml" xpointer="v254"/></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> + + <xi:include href="version-info.xml" xpointer="v239"/></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> + + <xi:include href="version-info.xml" xpointer="v239"/></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> + + <xi:include href="version-info.xml" xpointer="v239"/></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> + + <xi:include href="version-info.xml" xpointer="v239"/></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> + + <xi:include href="version-info.xml" xpointer="v239"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--follow</option><optional>=<replaceable>BOOL</replaceable></optional></term> + + <listitem><para> + If set to yes, then <command>systemd-journal-upload</command> waits for input. + </para> + + <xi:include href="version-info.xml" xpointer="v239"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--key=</option></term> + + <listitem><para> + Takes a path to a SSL key file in PEM format, or <option>-</option>. + If <option>-</option> is set, then client certificate authentication checking + will be disabled. + Defaults to <filename>&CERTIFICATE_ROOT;/private/journal-upload.pem</filename>. + </para> + + <xi:include href="version-info.xml" xpointer="v239"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--cert=</option></term> + + <listitem><para> + Takes a path to a SSL certificate file in PEM format, or <option>-</option>. + If <option>-</option> is set, then client certificate authentication checking + will be disabled. + Defaults to <filename>&CERTIFICATE_ROOT;/certs/journal-upload.pem</filename>. + </para> + + <xi:include href="version-info.xml" xpointer="v239"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--trust=</option></term> + + <listitem><para> + Takes a path to a SSL CA certificate file in PEM format, or <option>-</option>/<option>all</option>. + If <option>-</option>/<option>all</option> is set, then certificate checking will be disabled. + Defaults to <filename>&CERTIFICATE_ROOT;/ca/trusted.pem</filename>. + </para> + + <xi:include href="version-info.xml" xpointer="v239"/></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>. Note, 2048 bits of key length + is minimally recommended to use for security reasons:</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:2048 -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:2048 -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>, + and <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>journal-upload.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-journal-remote.service</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> |