[pbs-devel] [PATCH proxmox-backup 0/3] add minimal documentation on schedules, remotes and sync jobs

[pbs-devel] [PATCH proxmox-backup 0/3] add minimal documentation on schedules, remotes and sync jobs

[Stoiko Ivanov]

The following patchset adds minimal docs on the capabilities of the
current calendar event parser and their use in sync jobs and datastore
settings.

additionally the creation and handling of remotes was documented.

wasn't too sure whether to split the patches - can gladly send it again
as single patch - else feel free to squash them when applying.

(sorry for the delay - I had to find my way around the build-env)

Stoiko Ivanov (2):
  docs: add remotes and sync-jobs and schedules
  docs: expand datastore documentation

 docs/administration-guide.rst | 91 ++++++++++++++++++++++++++++++++++-
 docs/glossary.rst             | 16 ++++++
 2 files changed, 106 insertions(+), 1 deletion(-)

-- 
2.20.1

[pbs-devel] [PATCH proxmox-backup 1/2] docs: add remotes and sync-jobs and schedules

[Stoiko Ivanov]

Signed-off-by: Stoiko Ivanov <s.ivanov@proxmox.com>
---
 docs/administration-guide.rst | 58 +++++++++++++++++++++++++++++++++++
 docs/glossary.rst             | 16 ++++++++++
 2 files changed, 74 insertions(+)

diff --git a/docs/administration-guide.rst b/docs/administration-guide.rst
index ae14ac4b..37a716c6 100644
--- a/docs/administration-guide.rst
+++ b/docs/administration-guide.rst
@@ -340,6 +340,64 @@ following roles exist:
   Is allowed to read data from a remote.
 
 
+:term:`Remote`
+~~~~~~~~~~~~~~
+
+A remote is a different Proxmox Backup Server installation and a user on that
+installation, from which you can `sync` datastores to a local datastore with a
+`Sync Job`.
+
+For adding a remote you need its hostname or ip, a userid and password on the
+remote and its certificate fingerprint to add it. To get the fingerprint use
+the ``proxmox-backup-manager cert info`` command on the remote.
+
+.. code-block:: console
+
+  # proxmox-backup-manager cert info |grep Fingerprint
+  Fingerprint (sha256): 64:d3:ff:3a:50:38:53:5a:9b:f7:50:...:ab:fe
+
+With the needed information add the remote with:
+
+.. code-block:: console
+
+  # proxmox-backup-manager remote create pbs2 --host pbs2.mydomain.example --userid sync@pam --password 'SECRET' --fingerprint 64:d3:ff:3a:50:38:53:5a:9b:f7:50:...:ab:fe
+
+Use the ``list``, ``show``, ``update``, ``remove`` subcommands of
+``proxmox-backup-manager remote`` to manage your remotes:
+
+.. code-block:: console
+
+  # proxmox-backup-manager remote update pbs2 --host pbs2.example
+  # proxmox-backup-manager remote list
+  ┌──────┬──────────────┬──────────┬───────────────────────────────────────────┬─────────┐
+  │ name │ host         │ userid   │ fingerprint                               │ comment │
+  ╞══════╪══════════════╪══════════╪═══════════════════════════════════════════╪═════════╡
+  │ pbs2 │ pbs2.example │ sync@pam │64:d3:ff:3a:50:38:53:5a:9b:f7:50:...:ab:fe │         │
+  └──────┴──────────────┴──────────┴───────────────────────────────────────────┴─────────┘
+  # proxmox-backup-manager remote remove pbs2
+
+
+Sync Jobs
+~~~~~~~~~
+
+Sync jobs are configured to pull the contents of a datastore on a `Remote` to a
+local datastore. You can either start the sync job manually on the GUI or
+provide it with a :term:`schedule` to run regularly. The
+``proxmox-backup-manager sync-job`` command is used to manage sync jobs:
+
+.. code-block:: console
+
+  # proxmox-backup-manager sync-job create pbs2-local --remote pbs2 --remote-store local --store local --schedule 'Wed 02:30'
+  # proxmox-backup-manager sync-job update pbs2-local --comment 'offsite'
+  # proxmox-backup-manager sync-job list
+  ┌────────────┬───────┬────────┬──────────────┬───────────┬─────────┐
+  │ id         │ store │ remote │ remote-store │ schedule  │ comment │
+  ╞════════════╪═══════╪════════╪══════════════╪═══════════╪═════════╡
+  │ pbs2-local │ local │ pbs2   │ local        │ Wed 02:30 │ offsite │
+  └────────────┴───────┴────────┴──────────────┴───────────┴─────────┘
+  # proxmox-backup-manager sync-job remove pbs2-local
+
+
 Backup Client usage
 -------------------
 
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 78a78d91..b831bea3 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -46,3 +46,19 @@ Glossary
       kernel driver handles filesystem requests and sends them to a
       userspace application.
 
+   Remote
+
+      A remote Proxmox Backup Server installation and credentials for a user on it.
+      You can pull datastores from a remote to a local datastore in order to
+      have redundant backups.
+
+   Schedule
+
+      Certain tasks, for example pruning and garbage collection, need to be
+      performed on a regular basis. Proxmox Backup Server uses a subset of the
+      `systemd Time and Date Specification
+      <https://www.freedesktop.org/software/systemd/man/systemd.time.html#>`_.
+      The subset currently supports time of day specifications and weekdays, in
+      addition to the shorthand expressions 'minutely', 'hourly', 'daily'.
+      There is no support for specifying timezones, the tasks are run in the
+      timezone configured on the server.
-- 
2.20.1

[pbs-devel] [PATCH proxmox-backup 2/2] docs: expand datastore documentation

[Stoiko Ivanov]

document retention settings and schedules per datastore with
some minimal examples.

Signed-off-by: Stoiko Ivanov <s.ivanov@proxmox.com>
---
 docs/administration-guide.rst | 33 ++++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/docs/administration-guide.rst b/docs/administration-guide.rst
index 37a716c6..165633a7 100644
--- a/docs/administration-guide.rst
+++ b/docs/administration-guide.rst
@@ -146,7 +146,12 @@ Datastore Configuration
 
 You can configure multiple datastores. Minimum one datastore needs to be
 configured. The datastore is identified by a simple `name` and points to a
-directory on the filesystem.
+directory on the filesystem. Each datastore also has associated retention
+settings of how many backup snapshots for each interval of ``hourly``,
+``daily``, ``weekly``, ``monthly``, ``yearly`` as well as an time independent
+number of backups to keep in that store. :ref:`Pruning <pruning>` and
+:ref:`garbage collection <garbage-collection>` can also be configured to run
+periodically based on a configured :term:`schedule` per datastore.
 
 The following command creates a new datastore called ``store1`` on :file:`/backup/disk1/store1`
 
@@ -165,6 +170,30 @@ To list existing datastores run:
   │ store1 │ /backup/disk1/store1 │ This is my default storage. │
   └────────┴──────────────────────┴─────────────────────────────┘
 
+You can change settings of a datastore, for example to set a prune and garbage
+collection schedule or retention settings using ``update`` subcommand and view
+a datastore with the ``show`` subcommand:
+
+.. code-block:: console
+
+  # proxmox-backup-manager datastore update store1 --keep-last 7 --prune-schedule daily --gc-schedule 'Tue 04:27'
+  # proxmox-backup-manager datastore show store1
+  ┌────────────────┬─────────────────────────────┐
+  │ Name           │ Value                       │
+  ╞════════════════╪═════════════════════════════╡
+  │ name           │ store1                      │
+  ├────────────────┼─────────────────────────────┤
+  │ path           │ /backup/disk1/store1        │
+  ├────────────────┼─────────────────────────────┤
+  │ comment        │ This is my default storage. │
+  ├────────────────┼─────────────────────────────┤
+  │ gc-schedule    │ Tue 04:27                   │
+  ├────────────────┼─────────────────────────────┤
+  │ keep-last      │ 7                           │
+  ├────────────────┼─────────────────────────────┤
+  │ prune-schedule │ daily                       │
+  └────────────────┴─────────────────────────────┘
+
 Finally, it is possible to remove the datastore configuration:
 
 .. code-block:: console
@@ -822,6 +851,8 @@ To remove the ticket, issue a logout:
   # proxmox-backup-client logout
 
 
+.. _pruning:
+
 Pruning and Removing Backups
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.20.1

[pbs-devel] applied-series: Re: [PATCH proxmox-backup 0/3] add minimal documentation on schedules, remotes and sync jobs

[Thomas Lamprecht]

On 09.07.20 14:59, Stoiko Ivanov wrote:
> The following patchset adds minimal docs on the capabilities of the
> current calendar event parser and their use in sync jobs and datastore
> settings.
> 
> additionally the creation and handling of remotes was documented.
> 
> wasn't too sure whether to split the patches - can gladly send it again
> as single patch - else feel free to squash them when applying.
> 
> (sorry for the delay - I had to find my way around the build-env)
> 
> Stoiko Ivanov (2):
>   docs: add remotes and sync-jobs and schedules
>   docs: expand datastore documentation
> 
>  docs/administration-guide.rst | 91 ++++++++++++++++++++++++++++++++++-
>  docs/glossary.rst             | 16 ++++++
>  2 files changed, 106 insertions(+), 1 deletion(-)
> 



applied-series, thanks!