From 6bc4361997b15e9e5fe2efd9bb8640c24ce6c072 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Wed, 27 Nov 2019 21:38:07 +0100
Subject: [PATCH] man: document journald@NAMESPACE.conf

---
 man/journald.conf.xml | 50 +++++++++++++++++++++----------------------
 man/rules/meson.build |  2 +-
 2 files changed, 25 insertions(+), 27 deletions(-)

diff --git a/man/journald.conf.xml b/man/journald.conf.xml
index 824db668c5..afbbe64bb8 100644
--- a/man/journald.conf.xml
+++ b/man/journald.conf.xml
@@ -18,6 +18,7 @@
   <refnamediv>
     <refname>journald.conf</refname>
     <refname>journald.conf.d</refname>
+    <refname>journald@.conf</refname>
     <refpurpose>Journal service configuration files</refpurpose>
   </refnamediv>
 
@@ -26,6 +27,7 @@
     <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>
+    <para><filename>/etc/systemd/journald@<replaceable>NAMESPACE</replaceable>.conf</filename></para>
   </refsynopsisdiv>
 
   <refsect1>
@@ -37,6 +39,12 @@
     <citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>
     for a general description of the syntax.</para>
 
+    <para>The <command>systemd-journald</command> instance managing the default namespace is configured by
+    <filename>/etc/systemd/journald.conf</filename> and associated drop-ins. Instances managing other
+    namespaces read <filename>/etc/systemd/journald@<replaceable>NAMESPACE</replaceable>.conf</filename> with
+    the namespace identifier filled in. This allows each namespace to carry a distinct configuration. See
+    <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    for details about journal namespaces.</para>
   </refsect1>
 
   <xi:include href="standard-conf.xml" xpointer="main-conf" />
@@ -52,29 +60,19 @@
       <varlistentry>
         <term><varname>Storage=</varname></term>
 
-        <listitem><para>Controls where to store journal data. One of
-        <literal>volatile</literal>,
-        <literal>persistent</literal>,
-        <literal>auto</literal> and
-        <literal>none</literal>. If
-        <literal>volatile</literal>, journal
-        log data will be stored only in memory, i.e. below the
-        <filename>/run/log/journal</filename> hierarchy (which is
-        created if needed). If <literal>persistent</literal>, data
-        will be stored preferably on disk, i.e. below the
-        <filename>/var/log/journal</filename> hierarchy (which is
-        created if needed), with a fallback to
-        <filename>/run/log/journal</filename> (which is created if
-        needed), during early boot and if the disk is not writable.
-        <literal>auto</literal> is similar to
-        <literal>persistent</literal> but the directory
-        <filename>/var/log/journal</filename> is not created if
-        needed, so that its existence controls where log data goes.
-        <literal>none</literal> turns off all storage, all log data
-        received will be dropped. Forwarding to other targets, such as
-        the console, the kernel log buffer, or a syslog socket will
-        still work however. Defaults to
-        <literal>auto</literal>.</para></listitem>
+        <listitem><para>Controls where to store journal data. One of <literal>volatile</literal>,
+        <literal>persistent</literal>, <literal>auto</literal> and <literal>none</literal>. If
+        <literal>volatile</literal>, journal log data will be stored only in memory, i.e. below the
+        <filename>/run/log/journal</filename> hierarchy (which is created if needed). If
+        <literal>persistent</literal>, data will be stored preferably on disk, i.e. below the
+        <filename>/var/log/journal</filename> hierarchy (which is created if needed), with a fallback to
+        <filename>/run/log/journal</filename> (which is created if needed), during early boot and if the disk
+        is not writable.  <literal>auto</literal> is similar to <literal>persistent</literal> but the
+        directory <filename>/var/log/journal</filename> is not created if needed, so that its existence
+        controls where log data goes.  <literal>none</literal> turns off all storage, all log data received
+        will be dropped. Forwarding to other targets, such as the console, the kernel log buffer, or a syslog
+        socket will still work however. Defaults to <literal>auto</literal> in the default journal namespace,
+        and <literal>persistent</literal> in all others.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -399,9 +397,9 @@
       <varlistentry>
         <term><varname>ReadKMsg=</varname></term>
 
-        <listitem><para>Takes a boolean value. If enabled (the
-        default), journal reads <filename>/dev/kmsg</filename>
-        messages generated by the kernel.</para></listitem>
+        <listitem><para>Takes a boolean value. If enabled <command>systemd-journal</command> processes
+        <filename>/dev/kmsg</filename> messages generated by the kernel. In the default journal namespace
+        this option is enabled by default, it is disabled in all others.</para></listitem>
       </varlistentry>
 
       <varlistentry>
diff --git a/man/rules/meson.build b/man/rules/meson.build
index f4b161661a..5cff8ae320 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -24,7 +24,7 @@ manpages = [
  ['journal-remote.conf', '5', ['journal-remote.conf.d'], 'HAVE_MICROHTTPD'],
  ['journal-upload.conf', '5', ['journal-upload.conf.d'], 'HAVE_MICROHTTPD'],
  ['journalctl', '1', [], ''],
- ['journald.conf', '5', ['journald.conf.d'], ''],
+ ['journald.conf', '5', ['journald.conf.d', 'journald@.conf'], ''],
  ['kernel-command-line', '7', [], ''],
  ['kernel-install', '8', [], ''],
  ['libudev', '3', [], ''],