[systemd-devel] [PATCH 4/4] Document the new parameter CowJournal

[Goffredo Baroncelli]

From: Goffredo Baroncelli <kreijack at inwind.it>

Document:
- the new parameter CowJournal in journald.conf
- the new options --cow-journal and --no-cow-journal for
  systemd-journal-remote.

Signed-off-by: Goffredo Baroncelli <kreijack at inwind.it>
---
 man/journald.conf.xml          | 56 ++++++++++++++++++++++++++++++++++++++++++
 man/systemd-journal-remote.xml | 34 +++++++++++++++++++++++++
 2 files changed, 90 insertions(+)

diff --git a/man/journald.conf.xml b/man/journald.conf.xml
index 364b58f..9be19b8 100644
--- a/man/journald.conf.xml
+++ b/man/journald.conf.xml
@@ -362,6 +362,62 @@
         <filename>/dev/console</filename>.</para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><varname>CowJournal=</varname></term>
+
+	<listitem><para>Controls the "no copy on write" attribute for the
+	 journal file. 
+	If <varname>CowJournal=no</varname> this attribute is set.
+	If <varname>CowJournal=yes</varname> this attribute is reset.
+	</para>
+
+	<para>For the BTRFS filesystem the "no copy on write" attribute disables
+	the COW behavior and the checksum feature ; this leads to a faster
+	journal operations. Instead if this attribute is not set, the COW
+	behavior and the checksum feature are enabled but the performances are
+	slower.</para>
+
+	<para>BTRFS uses the checksums to detect a corrupted file; the checksums
+	are also used to automatically correct the file if a good copy is
+	available (as in a RAID1 BTRFS filesystems). Without  checksums, BTRFS
+	is not able to detect and to repair a corrupted file.</para>
+
+	<para>In case of a BTRFS filesystem without redundancy (i.e. single
+	disk), it is safe t<varname>CowJournal=no</varname> because in any case
+	there is no a good copy available to correct the file.</para>
+
+	<para>Refer to man pages such as 
+	<citerefentry><refentrytitle>btrfs</refentrytitle>
+		<manvolnum>5</manvolnum></citerefentry> and 
+	<citerefentry><refentrytitle>chattr</refentrytitle>
+		<manvolnum>1</manvolnum></citerefentry>  
+	for more details.</para>
+	</listitem>
+      </varlistentry>
+
+
+
+      <varlistentry>
+        <term><varname>CowJournal=</varname></term>
+
+        <listitem><para>Controls the COW/NOCOW attribute for the journal file.
+        If <varname>CowJournal=no</varname> the journal file has the NOCOW
+        flags set.
+        For the BTRFS filesystem this means that the COW behaviour (Copy
+        On Write) is disable but also the checksum protection is also disabled.
+        In this case journal operations are faster, but the journal file is not
+        protected by the filesystem checksums.
+        If <varname>CowJournal=yes</varname> the journal file has the NOCOW
+        flag unset, and it is protected by the BTRFS checksum but the
+        perfomance are slower.
+        If the the journal file is corrupted on the disk and a good copy
+        (raid mirror) is available, the checksum are used by BTRFS to rebuild
+        the file content during a SCRUB process. If the checksum is not
+        available, the SCRUB process is unable the repair of the journal file.
+        In case of a single volume filesystem (no RAID), it is safe to have
+        NoCowJournal=yes.</para></listitem>
+      </varlistentry>
+
     </variablelist>
 
   </refsect1>
diff --git a/man/systemd-journal-remote.xml b/man/systemd-journal-remote.xml
index 2687662..b14f4e3 100644
--- a/man/systemd-journal-remote.xml
+++ b/man/systemd-journal-remote.xml
@@ -258,6 +258,40 @@
       </varlistentry>
 
       <varlistentry>
+        <term><option>--cow-journal</option></term>
+        <term><option>--no-cow-journal</option></term>
+
+	<listitem><para>Controls the "no copy on write" attribute for the
+	 journal file. 
+	If <option>--no-cow-journal</option> is passed, this attribute is set.
+	If <option>--cow-journal</option> is passed, this attribute is reset.
+	</para>
+
+	<para>For the BTRFS filesystem the "no copy on write" attribute disables
+	the COW behavior and the checksum feature ; this leads to a faster
+	journal operations. Instead if this attribute is not set, the COW
+	behavior and the checksum feature are enabled but the performances are
+	slower.</para>
+
+	<para>BTRFS uses the checksums to detect a corrupted file; the checksums
+	are also used to automatically correct the file if a good copy is
+	available (as in a RAID1 BTRFS filesystems). Without  checksums, BTRFS
+	is not able to detect and to repair a corrupted file.</para>
+
+	<para>In case of a BTRFS filesystem without redundancy (i.e. single
+	disk), it is safe to pass --no-cow-journal because in any case
+	there is no a good copy available to correct the file.</para>
+
+	<para>Refer to man pages such as 
+	<citerefentry><refentrytitle>btrfs</refentrytitle>
+		<manvolnum>5</manvolnum></citerefentry> and 
+	<citerefentry><refentrytitle>chattr</refentrytitle>
+		<manvolnum>1</manvolnum></citerefentry>  
+	for more details.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
         <term><option>--seal</option></term>
         <term><option>--no-seal</option></term>
 
-- 
2.1.0