X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd-journald.service.xml;h=6b250b65e62540208abbc0837dabe33a30636bf3;hp=5d39c50f62d7523efafacfc35beb357de4b3ecea;hb=dc2c282b6aac820a3c27d8a7a68c0386300db663;hpb=3ab1e259d918228c68c1829bd67625e1dc660862

diff --git a/man/systemd-journald.service.xml b/man/systemd-journald.service.xml
index 5d39c50f6..6b250b65e 100644
--- a/man/systemd-journald.service.xml
+++ b/man/systemd-journald.service.xml
@@ -1,6 +1,6 @@
 <?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">
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
 <!--
   This file is part of systemd.
@@ -23,88 +23,228 @@
 
 <refentry id="systemd-journald.service">
 
-        <refentryinfo>
-                <title>systemd-journald</title>
-                <productname>systemd</productname>
-
-                <authorgroup>
-                        <author>
-                                <contrib>Developer</contrib>
-                                <firstname>Lennart</firstname>
-                                <surname>Poettering</surname>
-                                <email>lennart@poettering.net</email>
-                        </author>
-                </authorgroup>
-        </refentryinfo>
-
-        <refmeta>
-                <refentrytitle>systemd-journald</refentrytitle>
-                <manvolnum>8</manvolnum>
-        </refmeta>
-
-        <refnamediv>
-                <refname>systemd-journald.service</refname>
-                <refname>systemd-journald</refname>
-                <refpurpose>systemd Journal Service</refpurpose>
-        </refnamediv>
-
-        <refsynopsisdiv>
-                <para><filename>systemd-journald.service</filename></para>
-                <para><filename>/usr/lib/systemd/systemd-journald</filename></para>
-        </refsynopsisdiv>
-
-        <refsect1>
-                <title>Description</title>
-
-                <para><filename>systemd-journald</filename> is a
-                system service that collects and stores logging
-                data. It creates and maintains structured, indexed
-                journals based on logging information that is received
-                from the kernel, from user processes via the libc
-                <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-                call, from STDOUT/STDERR of system services or via its
-                native API. It will implicitly collect numerous meta
-                data fields for each log messages in a secure and
-                unfakeable way. See
-                <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
-                for more information about the collected meta data.
-                </para>
-
-                <para>Log data collected by the journal is primarily
-                text based but can also include binary data where
-                necessary. All objects stored in the journal can be up
-                to 2^64-1 bytes in size.</para>
-
-                <para>By default the journal stores log data in
-                <filename>/run/log/journal/</filename>. Since
-                <filename>/run/</filename> is volatile log data is
-                lost at reboot. To make the data persistent it
-                is sufficient to create
-                <filename>/var/log/journal/</filename> where
-                <filename>systemd-journald</filename> will then store
-                the data.</para>
-
-                <para><filename>systemd-journald</filename> will
-                forward all received log messages to the AF_UNIX
-                SOCK_DGRAM socket
-                <filename>/run/systemd/journal/syslog</filename> (if it exists) which
-                may be used by UNIX syslog daemons to process the data
-                further.</para>
-
-                <para>See
-                <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-                for information about the configuration of this
-                service.</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>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
-                </para>
-        </refsect1>
+  <refentryinfo>
+    <title>systemd-journald.service</title>
+    <productname>systemd</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Lennart</firstname>
+        <surname>Poettering</surname>
+        <email>lennart@poettering.net</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>systemd-journald.service</refentrytitle>
+    <manvolnum>8</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>systemd-journald.service</refname>
+    <refname>systemd-journald.socket</refname>
+    <refname>systemd-journald-dev-log.socket</refname>
+    <refname>systemd-journald</refname>
+    <refpurpose>Journal service</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <para><filename>systemd-journald.service</filename></para>
+    <para><filename>systemd-journald.socket</filename></para>
+    <para><filename>systemd-journald-dev-log.socket</filename></para>
+    <para><filename>/usr/lib/systemd/systemd-journald</filename></para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><filename>systemd-journald</filename> is a system service
+    that collects and stores logging data. It creates and maintains
+    structured, indexed journals based on logging information that is
+    received from a variety of sources:</para>
+
+    <itemizedlist>
+      <listitem><para>Kernel log messages, via kmsg</para></listitem>
+
+      <listitem><para>Simple system log messages, via the libc
+      <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+      call</para></listitem>
+
+      <listitem><para>Structured system log messages via the native
+      Journal API, see
+      <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>4</manvolnum></citerefentry></para></listitem>
+
+      <listitem><para>Standard output and standard error of system
+      services</para></listitem>
+
+      <listitem><para>Audit records, via the audit
+      subsystem</para></listitem>
+    </itemizedlist>
+
+    <para>The daemon will implicitly collect numerous metadata fields
+    for each log messages in a secure and unfakeable way. See
+    <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+    for more information about the collected metadata.
+    </para>
+
+    <para>Log data collected by the journal is primarily text-based
+    but can also include binary data where necessary. All objects
+    stored in the journal can be up to 2^64-1 bytes in size.</para>
+
+    <para>By default, the journal stores log data in
+    <filename>/run/log/journal/</filename>. Since
+    <filename>/run/</filename> is volatile, log data is lost at
+    reboot. To make the data persistent, it is sufficient to create
+    <filename>/var/log/journal/</filename> where
+    <filename>systemd-journald</filename> will then store the
+    data.</para>
+
+    <para><filename>systemd-journald</filename> will forward all
+    received log messages to the
+    <constant>AF_UNIX</constant>/<constant>SOCK_DGRAM</constant>
+    socket <filename>/run/systemd/journal/syslog</filename>, if it
+    exists, which may be used by Unix syslog daemons to process the
+    data further.</para>
+
+    <para>See
+    <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    for information about the configuration of this service.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Signals</title>
+
+    <variablelist>
+      <varlistentry>
+        <term>SIGUSR1</term>
+
+        <listitem><para>Request that journal data from
+        <filename>/run/</filename> is flushed to
+        <filename>/var/</filename> in order to make it persistent (if
+        this is enabled). This must be used after
+        <filename>/var/</filename> is mounted, as otherwise log data
+        from <filename>/run</filename> is never flushed to
+        <filename>/var</filename> regardless of the
+        configuration.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>SIGUSR2</term>
+
+        <listitem><para>Request immediate rotation of the journal
+        files.</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Kernel Command Line</title>
+
+    <para>A few configuration parameters from
+    <filename>journald.conf</filename> may be overridden on the kernel
+    command line:</para>
+
+    <variablelist class='kernel-commandline-options'>
+      <varlistentry>
+        <term><varname>systemd.journald.forward_to_syslog=</varname></term>
+        <term><varname>systemd.journald.forward_to_kmsg=</varname></term>
+        <term><varname>systemd.journald.forward_to_console=</varname></term>
+        <term><varname>systemd.journald.forward_to_wall=</varname></term>
+
+        <listitem><para>Enables/disables forwarding of collected log
+        messages to syslog, the kernel log buffer, the system console
+        or wall.
+        </para>
+
+        <para>See
+        <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+        for information about these settings.</para>
+        </listitem>
+
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Access Control</title>
+
+    <para>Journal files are, by default, owned and readable by the
+    <literal>systemd-journal</literal> system group but are not
+    writable. Adding a user to this group thus enables her/him to read
+    the journal files.</para>
+
+    <para>By default, each logged in user will get her/his own set of
+    journal files in <filename>/var/log/journal/</filename>. These
+    files will not be owned by the user, however, in order to avoid
+    that the user can write to them directly. Instead, file system
+    ACLs are used to ensure the user gets read access only.</para>
+
+    <para>Additional users and groups may be granted access to journal
+    files via file system access control lists (ACL). Distributions
+    and administrators may choose to grant read access to all members
+    of the <literal>wheel</literal> and <literal>adm</literal> system
+    groups with a command such as the following:</para>
+
+    <programlisting># setfacl -Rnm g:wheel:rx,d:g:wheel:rx,g:adm:rx,d:g:adm:rx /var/log/journal/</programlisting>
+
+    <para>Note that this command will update the ACLs both for
+    existing journal files and for future journal files created in the
+    <filename>/var/log/journal/</filename> directory.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Files</title>
+
+    <variablelist>
+      <varlistentry>
+        <term><filename>/etc/systemd/journald.conf</filename></term>
+
+        <listitem><para>Configure
+        <command>systemd-journald</command>
+        behaviour. See
+        <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+        </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><filename>/run/log/journal/<replaceable>machine-id</replaceable>/*.journal</filename></term>
+        <term><filename>/run/log/journal/<replaceable>machine-id</replaceable>/*.journal~</filename></term>
+        <term><filename>/var/log/journal/<replaceable>machine-id</replaceable>/*.journal</filename></term>
+        <term><filename>/var/log/journal/<replaceable>machine-id</replaceable>/*.journal~</filename></term>
+
+        <listitem><para><command>systemd-journald</command> writes
+        entries to files in
+        <filename>/run/log/journal/<replaceable>machine-id</replaceable>/</filename>
+        or
+        <filename>/var/log/journal/<replaceable>machine-id</replaceable>/</filename>
+        with the <literal>.journal</literal> suffix. If the daemon is
+        stopped uncleanly, or if the files are found to be corrupted,
+        they are renamed using the <literal>.journal~</literal>
+        suffix, and <command>systemd-journald</command> starts writing
+        to a new file. <filename>/run</filename> is used when
+        <filename>/var/log/journal</filename> is not available, or
+        when <option>Storage=volatile</option> is set in the
+        <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+        configuration file. </para></listitem>
+      </varlistentry>
+    </variablelist>
+  </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>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>setfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>4</manvolnum></citerefentry>,
+      <command>pydoc systemd.journal</command>.
+    </para>
+  </refsect1>
 
 </refentry>