Fixes #427 - Reworked 'Backup and Restore' section

appendix/backup-and-restore/backup.rst

@@ -10,7 +10,10 @@ Before running your first backup, please have a look at the
 Backup
 ======
 
-In general, running a Zammad backup is as simple as running:
+It is recommended to stop Zammad before running the backup.
+
+To create a backup, execute the script ``zammad_backup.sh`` as ``root``
+or ``zammad`` user:
 
 .. code-block:: sh
 
@@ -33,22 +36,6 @@ The backup process should look like this one:
 
    # Zammad backuped successfully - Fri Jan 21 17:53:57 CET 2022!
 
-*Sample backup process with default*
-:doc:`settings </appendix/backup-and-restore/configuration>`.
-
-Additional Information
-======================
-
-* The backup script can be either run as ``zammad`` or ``root`` user.
-* Stopping Zammad is not required (but suggested) technically. It may be
-  required in your case!
-* Keep in mind that a running Zammad instance keeps changing data which may
-  be an issue during long backup runs
-
-.. hint::
-
-   **😖 Having trouble backing up?**
-
-   Have a look at the
-   :doc:`troubleshooting section </appendix/backup-and-restore/troubleshooting>`
-   to address your issues.
+If you are facing issues while backing up your data, you can have a look at
+the :doc:`troubleshooting section </appendix/backup-and-restore/troubleshooting>`
+to read about common issues.

appendix/backup-and-restore/configuration.rst

@@ -1,8 +1,8 @@
-Backup configuration
+Backup Configuration
 ********************
 
-Before you can run either a backup or restoration, the scripts requires you
-to provide a configuration file. We're shipping a ``config.dist`` within the
+Before you can run either a backup or restoration, the scripts require
+you to provide a configuration file. We're shipping a ``config.dist`` within the
 ``/opt/zammad/contrib/backup`` directory which you can simply rename.
 
 To do so run the following commands as either ``root`` or ``zammad`` user.
@@ -12,66 +12,56 @@ To do so run the following commands as either ``root`` or ``zammad`` user.
    $ cd /opt/zammad/contrib/backup/
    $ mv config.dist config
 
-If below default values are not working for you or your installation in general,
-this is the best moment to adjust the configuration file as needed.
+Adjust the values according to your needs. See the explanation of each
+parameter in the table below.
 
-After this you'll be ready to continue with either
-:doc:`creating your first backup </appendix/backup-and-restore/backup>` or
-:doc:`restoring an existing backup </appendix/backup-and-restore/backup>`.
-
-``BACKUP_DIR``
-   Default: ``/var/tmp/zammad_backup``
-
-   Tell the backup script where to write your backup files to.
-
-   Ensure that the user you're going to use for backing up Zammad
-   (either ``root`` or ``zammad`` by default) has enough permissions
-   to write into the target directory structure.
+.. list-table::
+  :widths: 15, 25, 60
+  :header-rows: 1
 
-   In case the directory is not available yet, the backup script will attempt
-   to create the directory.
+  * - Parameter
+    - Default
+    - Description
+  * - ``BACKUP_DIR``
+    - ``/var/tmp/zammad_backup``
+    - Location where the script writes the backup files to.
 
-   Make also sure to have enough space available on the backup location.
-   Zammad always creates full backups. While we do compress backups,
-   expect worst case ratios of 1 (no compression at all) depending
-   on your attachments!
+      The directory will be created if it does not exist. Make sure you have
+      enough space because the script writes full dumps.
+  * - ``HOLD_DAYS``
+    - ``10``
+    - Define how many days the backup script should keep old backups.
+      This value contains a 60 minutes grace period (e.g. 10 days plus 1 hour)
+      for safety reasons.
 
-``HOLD_DAYS``
-   Default: ``10``
+      Old backups are removed *before* creating the a new backup.
 
-   How many days should the backup script keep old backups?
-   This value contains 60 minutes grace period (so e.g. 10 days plus 1 hour)
-   for safety reasons.
+      **Examples:**
 
-   Old backups are removed *before* creating the actual (current) backup.
+      * ``1`` will keep backups of the last 25 hours
+      * ``-1`` will remove all available backups (except the new one)
+  * - ``FULL_FS_DUMP``
+    - ``yes``
+    - If set to ``yes``, the backup includes also application files.
 
-   **Example:**
+      If set to ``no``, the backup includes only user data.
 
-   * ``0`` will keep the last 25 hours worth of backup
-   * ``-1`` will always remove all available backups
-     (aka only keep current backup)
+      In any case, it includes the Zammad database and the attachments, if you
+      :admin-docs:`stored them in the file system </settings/system/storage.html>`.
 
-``FULL_FS_DUMP``
-   Default: ``yes`` (accepts: ``yes`` or ``no``)
+      If you are in doubt, set this to ``no``.
+  * - ``DEBUG``
+    - ``no``
+    - Setting this option to ``yes`` will output useful debug messages.
 
-   Setting this option to ``no`` allows you to only backup usage data without
-   any environmental files from your old host. This allows you to backup your
-   Zammad database together with the attachments you've stored within the file
-   system.
+      .. warning::
 
-   Please refer :admin-docs:`Storage Settings </settings/system/storage.html>`
-   to learn how to change the storage location of your attachments.
+         This option potentially returns **sensitive** information to standard
+         output! *Do not* use this option in production environments or ensure
+         to turn it *off after testing*.
 
-   If you can't decide, our clear suggestion is setting this to ``no``.
 
-``DEBUG``
-   Default: ``no`` (accepts: ``yes`` or ``no``)
 
-   Having issues and want to fiddle around? Setting this option to ``yes`` may
-   help you with this. It contains useful debug messages at strategic points.
-
-   .. warning::
-
-      This option potentially returns **sensitive** information to standard
-      out! *Do not* use this option in productive environments or ensure
-      to turn it *off after testing*.
+After this you'll be ready to continue with either
+:doc:`creating your first backup </appendix/backup-and-restore/backup>` or
+:doc:`restoring an existing backup </appendix/backup-and-restore/restore>`.

appendix/backup-and-restore/index.rst

@@ -1,10 +1,10 @@
 Backup and Restore
 ******************
 
-Zammad comes with a collection of scripts for easy backup & restore for default
-installations. These scripts are located within ``/opt/zammad/contrib/backup``.
+Zammad ships scripts for backup & restore in package installations which you
+can use in your backup strategy.
 
-.. warning:: **⚖️ Important things to note beforehand**
+.. warning::
 
    These scripts do not come with any warranty and may not work in your
    specific use case. This depends on the configuration and installation type
@@ -18,6 +18,32 @@ installations. These scripts are located within ``/opt/zammad/contrib/backup``.
 Getting Started
 ===============
 
+These scripts are located in ``/opt/zammad/contrib/backup``. The following files
+might be important for you:
+
+- Backup configuration file: ``config.dist``
+- Script for backing up your data: ``zammad_backup.sh``
+- Script for restoring your data: ``zammad_restore.sh``
+
+Head over to the next section for a simple backup configuration. In
+:ref:`advanced_backup`, you can find links to sub pages with a more
+detailed explanation of the scripts.
+
+Basic Backup Setup
+------------------
+
+#. Rename/copy the ``config.dist`` file to ``config``.
+#. Change default parameters in  the ``config`` file if needed. Learn more
+   about the configuration options
+   :doc:`here </appendix/backup-and-restore/configuration>`.
+#. Execute ``/opt/zammad/contrib/backup/zammad_backup.sh``.
+
+
+.. _advanced_backup:
+
+Advanced Setup and Restore
+--------------------------
+
 .. toctree::
    :hidden:
 
@@ -28,52 +54,54 @@ Getting Started
    troubleshooting
    little-helpers
 
-Before you continue, please also note the listed limitations to save your
-precious time.
+Adjust script settings
+   Learn more about configuration options for backup and restore
+   :doc:`here </appendix/backup-and-restore/configuration>`.
 
-   :doc:`🔨 Adjust script settings </appendix/backup-and-restore/configuration>`
-      Learn more about configuration options for backup and restore to see
-      scopes better.
+Create Backups
+   Learn how to create full dumps of your Zammad installation
+   :doc:`here </appendix/backup-and-restore/backup>`.
 
-   :doc:`🗃️ Create Backups </appendix/backup-and-restore/backup>`
-      How to create full dumps of your Zammad installation.
+Restore Backups
+   Learn how to restore your instance on the same host
+   :doc:`here </appendix/backup-and-restore/restore>`.
 
-   :doc:`🗄️ Restore Backups </appendix/backup-and-restore/restore>`
-      Update went wrong and you need to go back? How to restore your instance on
-      a new or the same host.
+Additional Information
+----------------------
 
-   :doc:`🔀 Migrating to new hosts </appendix/backup-and-restore/migrate-hosts>`
-      This is a general summary on how to best migrate Zammad from host to host.
-      We'll reference to backup creation and restoration as needed.
+Migrating to a new host
+   :doc:`Here </appendix/backup-and-restore/migrate-hosts>` you can read how to
+   migrate Zammad from one host to another host.
 
-   :doc:`🔥 Troubleshooting </appendix/backup-and-restore/troubleshooting>`
-      Things hit the fan? This page might help you out of that pit.
+Troubleshooting
+   If something went wrong,
+   :doc:`this page </appendix/backup-and-restore/troubleshooting>` might help
+   you out.
 
-   :doc:`🤝 Helper scripts </appendix/backup-and-restore/little-helpers>`
-      These scripts may be helpful if Backup & Restore does not work as expected.
-      However note that these are potentially destructive.
+Helper scripts
+   Maybe this is helpful for you if backup & restore does not work as expected.
+   See :doc:`here </appendix/backup-and-restore/little-helpers>` for more
+   information.
 
 Limitations
 ===========
 
 Please note the following limitations which may affect script functionality
-or availability.
-
-   * Restoration via script on docker and source code based installations may
-     not work and is out of scope of this documentation as of now
-   * Backup & Restore is only available for PostgreSQL and MySQL / MariaDB like
-     installations
-   * Starting with Zammad 5.0 the scripts *require* user & password
-     authentication. This is supported by most of our installation types
-   * Backup & Restore is always a full dump of everything (no incrementals)
-   * Restoring or backing up specific information (e.g. Tickets, Users, ...)
-     is not supported
-   * | Switching / Converting database installations *is not* possible
-     | Refer this guide to manually switch databases:
-       :doc:`/appendix/migrate-to-postgresql`
-   * Environmental settings (like e.g. :doc:`/appendix/configure-env-vars`) are
-     not backed up and thus require you to manually set them on a new host
-   * Restoration into a *older* Zammad version is not possible nor supported
-   * *Do not* attempt to restore backup files from custom scripts with the
-     provided scripts by Zammad. This is most likely subject to fail or bring
-     issues you may discover too late.
+or availability:
+
+   * These scripts won't work in container and source code based installations.
+   * They only work for PostgreSQL installations.
+   * The backup is always a full dump (no incremental backup).
+   * Partial backup and restore (e.g. only specific data like tickets, users)
+     is not possible.
+   * Switching database system **is not** possible. See
+     :doc:`here </appendix/migrate-to-postgresql>` how to manually switch
+     databases.
+   * System settings (like
+     :doc:`environment variables </appendix/configure-env-vars>`) are
+     not backed up.
+   * Restore to an older Zammad version is not possible.
+   * **Do not** restore backup files from custom scripts with the
+     provided scripts by Zammad. This might cause problems.
+
+

appendix/backup-and-restore/little-helpers.rst

@@ -1,48 +1,45 @@
-Helper scripts
+Helper Scripts
 **************
 
-.. danger:: **☠️ The following scripts are potentially destructive ☠️**
+Warning
+=======
 
-   You should **never** run scrips which scopes you don't understand.
-   Below scripts potentially can make things worse which is why you should
-   evaluate them *before hand*.
+A script can potentially be destructive!
+You should **never** run scripts which scopes you don't understand.
 
-   You're running these scripts at your own risk.
-
-If we found a script is helping you more than 30 lines of new documentation,
-we may have added a helper script.
+Be aware that you are running these scripts at your own risk.
 
 .. _reset_db_password:
 
-Database Helper: (re)set password
----------------------------------
+Database Helper: (Re)set Password
+=================================
 
-   Limitations
-      * This script is working for PostgreSQL installations only.
-      * Only local database servers are supported (script changes user).
-      * This script requires to be run as ``root`` or similar privileged user!
+Limitations
+   * This script is working for PostgreSQL installations only.
+   * Only local database servers are supported (script changes user).
+   * This script requires to be run as ``root`` or similar privileged user.
+   * Be aware that the script will automatically stop and start Zammad!
 
-   Scopes
-      Mostly the following installation types will be affected / relevant:
+Scopes
+   Mostly the following installation types will be affected / relevant:
 
-         * package installations (especially CentOS & SUSE)
-         * possibly source code installations
+      * package installations (especially CentOS & SUSE)
+      * possibly source code installations
 
-   Functionality
-      The script will do the following actions depending on the situation
-      automatically for you. It will double tab by asking for your confirmation
-      up front.
+Functionality
+   The script will do the following actions automatically for you, depending
+   on the situation. It will ask for your confirmation before performing
+   actions.
 
-         * If ``database.yml`` contains an empty password line, a new password
-           will be generated, and set for the database user of Zammad, and
-           saved to the configuration file.
-         * If ``database.yml`` contains a password, it will be used to set
-           the password of the Zammad database user.
-         * Please note that the script will automatically stop and start Zammad!
+      * If ``database.yml`` contains an empty password line, a new password
+        will be generated and set for the database user of Zammad. It will also
+        be saved to the configuration file.
+      * If ``database.yml`` contains a password, it will be used to set
+        the password of the Zammad database user.
 
-   Usage
-      Run ``/opt/zammad/contrib/backup/zammad_db_user_helper.sh`` and follow
-      the instructions. No specific configurations are required.
+Usage
+   Run ``/opt/zammad/contrib/backup/zammad_db_user_helper.sh`` and follow
+   the instructions. No specific configurations are required.
 
-      If errors occur the script will try to bring Zammad back online before
-      exitting. Please ensure that your service is running.
+   If errors occur, the script will try to bring Zammad back online before
+   exiting.