From f405fc6ae281eebf4d61abb39963a9830fe2fa2f Mon Sep 17 00:00:00 2001
From: David Steele <david@pgmasters.net>
Date: Fri, 6 May 2022 10:21:20 -0400
Subject: [PATCH] Backup file bundling documentation.

Make the feature user visible and add documentation to the user guide.
---
 doc/xml/release.xml          | 51 +++++++++++++++++++-----------------
 doc/xml/user-guide.xml       | 44 +++++++++++++++++++++++++++++++
 src/build/config/config.yaml |  2 --
 3 files changed, 71 insertions(+), 26 deletions(-)

diff --git a/doc/xml/release.xml b/doc/xml/release.xml
index 5fef85519..708381280 100644
--- a/doc/xml/release.xml
+++ b/doc/xml/release.xml
@@ -45,6 +45,33 @@
                 </release-bug-list>
 
                 <release-feature-list>
+                    <release-item>
+                        <commit subject="Remove redundant restoreFile() test and improve coverage."/>
+                        <commit subject="Add limit parameter to ioCopyP()."/>
+                        <commit subject="Optimize restore command for file bundling.">
+                            <github-issue id="1149"/>
+                            <github-pull-request id="1683"/>
+                        </commit>
+                        <commit subject="Add bundle logging to backup command."/>
+                        <commit subject="Rename bundle-* options to repo-bundle-*.">
+                            <github-pull-request id="1694"/>
+                        </commit>
+                        <commit subject="Disable repo-hardlink option when repo-bundle option is enabled."/>
+                        <commit subject="Allow files that become zero-length after the backup manifest is built."/>
+                        <commit subject="Backup file bundling documentation.">
+                            <github-pull-request id="1740"/>
+                        </commit>
+
+                        <release-item-contributor-list>
+                            <release-item-contributor id="david.steele"/>
+                            <release-item-reviewer id="reid.thompson"/>
+                            <release-item-reviewer id="stefan.fercot"/>
+                            <release-item-reviewer id="chris.bandy"/>
+                        </release-item-contributor-list>
+
+                        <p>Backup file bundling for improved small file support.</p>
+                    </release-item>
+
                     <release-item>
                         <commit subject="Remove dependency on pg_database.datlastsysoid.">
                             <github-pull-request id="1735"/>
@@ -224,30 +251,6 @@
                 </release-improvement-list>
 
                 <release-development-list>
-                    <release-item>
-                        <commit subject="Remove redundant restoreFile() test and improve coverage."/>
-                        <commit subject="Add limit parameter to ioCopyP()."/>
-                        <commit subject="Optimize restore command for file bundling.">
-                            <github-issue id="1149"/>
-                            <github-pull-request id="1683"/>
-                        </commit>
-                        <commit subject="Add bundle logging to backup command."/>
-                        <commit subject="Rename bundle-* options to repo-bundle-*.">
-                            <github-pull-request id="1694"/>
-                        </commit>
-                        <commit subject="Disable repo-hardlink option when repo-bundle option is enabled."/>
-                        <commit subject="Allow files that become zero-length after the backup manifest is built."/>
-
-                        <release-item-contributor-list>
-                            <release-item-contributor id="david.steele"/>
-                            <release-item-reviewer id="reid.thompson"/>
-                            <release-item-reviewer id="stefan.fercot"/>
-                            <release-item-reviewer id="chris.bandy"/>
-                        </release-item-contributor-list>
-
-                        <p>Improve small file support.</p>
-                    </release-item>
-
                     <release-item>
                         <commit subject="Add test for protocol greeting when a field is missing."/>
                         <commit subject="Return stats as a JSON string rather than a KeyValue object."/>
diff --git a/doc/xml/user-guide.xml b/doc/xml/user-guide.xml
index f97aab208..1b9928ed0 100644
--- a/doc/xml/user-guide.xml
+++ b/doc/xml/user-guide.xml
@@ -1526,6 +1526,50 @@
         </section>
     </section>
 
+    <!-- ======================================================================================================================= -->
+    <section id="backup" depend="quickstart/perform-backup">
+        <title>Backup</title>
+
+        <cmd-description key="backup"/>
+
+        <!-- =================================================================================================================== -->
+        <section id="bundle">
+            <title>File Bundling</title>
+
+            <p>Bundling files together in the repository saves time during the backup and some space in the repository. This is especially pronounced when the repository is stored on an object store such as <proper>S3</proper>. Per-file creation time on object stores is higher and very small files might cost as much to store as larger files.</p>
+
+            <p>The file bundling feature is enabled with the <br-option>repo-bundle</br-option> option.</p>
+
+            <backrest-config host="{[host-pg1]}" file="{[backrest-config-demo]}">
+                <title>Configure <br-option>repo1-bundle</br-option></title>
+
+                <backrest-config-option section="global" key="repo1-bundle">y</backrest-config-option>
+            </backrest-config>
+
+            <p>A full backup without file bundling will have 1000+ files in the backup path, but with bundling the total number of files is greatly reduced. An additional benefit is that zero-length files are not stored (except in the manifest), whereas in a normal backup each zero-length file is stored individually.</p>
+
+            <execute-list host="{[host-pg1]}">
+                <title>Perform a full backup</title>
+
+                <execute user="postgres">
+                    <exe-cmd>{[project-exe]} {[dash]}-stanza={[postgres-cluster-demo]} --type=full backup</exe-cmd>
+                </execute>
+            </execute-list>
+
+            <execute-list host="{[host-pg1]}">
+                <title>Check file total</title>
+
+                <execute user="postgres" output="y">
+                    <exe-cmd>find {[backrest-repo-path]}/backup/demo/latest/ -type f | wc -l</exe-cmd>
+                </execute>
+            </execute-list>
+
+            <p>The <br-option>repo-bundle-size</br-option> and <br-option>repo-bundle-limit</br-option> options can be used for tuning, though the defaults should be optimal in most cases.</p>
+
+            <p>While file bundling is generally more efficient, the downside is that it is more difficult to manually retrieve files from the repository. It may not be ideal for deduplicated storage since each full backup will arrange files in the bundles differently. Lastly, file bundles cannot be resumed, so be careful not to set <br-option>repo-bundle-size</br-option> too high.</p>
+        </section>
+    </section>
+
     <!-- SECTION => RETENTION -->
     <section id="retention" depend="quickstart/perform-backup">
         <title>Retention</title>
diff --git a/src/build/config/config.yaml b/src/build/config/config.yaml
index 58a844015..0448dd7eb 100644
--- a/src/build/config/config.yaml
+++ b/src/build/config/config.yaml
@@ -1742,7 +1742,6 @@ option:
     depend: repo-azure-account
 
   repo-bundle:
-    internal: true
     section: global
     group: repo
     type: boolean
@@ -1753,7 +1752,6 @@ option:
       main: {}
 
   repo-bundle-size:
-    internal: true
     section: global
     group: repo
     type: size