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=fa6e97edf06263eea3faf169b66e9bba447c24eb;hp=90f9290276ccb451c7aa62a7502e71268f006169;hb=a6e841b454e076ecbab6abc0bceb85ed06fd5c70;hpb=34511ca7b166b0e89d08ff9870b0cf2624a7815f

diff --git a/man/systemd-journald.service.xml b/man/systemd-journald.service.xml
index 90f929027..fa6e97edf 100644
--- a/man/systemd-journald.service.xml
+++ b/man/systemd-journald.service.xml
@@ -45,6 +45,7 @@
         <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>
@@ -52,6 +53,7 @@
         <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>
 
@@ -59,38 +61,55 @@
                 <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
+                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 meta data.
+                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
+                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
+                <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
+                <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
+                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
@@ -111,13 +130,13 @@
                                 is flushed to
                                 <filename>/var/</filename> in order to
                                 make it persistent (if this is
-                                enabled). This may be used after
+                                enabled). This must be used after
                                 <filename>/var/</filename> is mounted,
-                                but is generally not required since
-                                the first journal write when
-                                <filename>/var/</filename> becomes
-                                writable triggers the flushing
-                                anyway.</para></listitem>
+                                as otherwise log data from
+                                <filename>/run</filename> is never
+                                flushed to <filename>/var</filename>
+                                regardless of the
+                                configuration.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
@@ -134,19 +153,20 @@
                 <title>Kernel Command Line</title>
 
                 <para>A few configuration parameters from
-                <filename>journald.conf</filename> may be overriden on
+                <filename>journald.conf</filename> may be overridden on
                 the kernel command line:</para>
 
-                <variablelist>
+                <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 or
-                                the system console.
+                                to syslog, the kernel log buffer, the
+                                system console or wall.
                                 </para>
 
                                 <para>See
@@ -158,6 +178,84 @@
                 </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>
@@ -166,7 +264,11 @@
                         <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>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>