[pbs-devel] [PATCH v3 proxmox-backup 11/18] docs: add configuration file reference for domains.cfg

[Lukas Wagner]

Signed-off-by: Lukas Wagner <l.wagner at proxmox.com>
---
 docs/Makefile                  |  6 ++++--
 docs/conf.py                   |  1 +
 docs/config/domains/format.rst | 27 +++++++++++++++++++++++++++
 docs/config/domains/man5.rst   | 21 +++++++++++++++++++++
 docs/configuration-files.rst   | 14 ++++++++++++++
 src/bin/docgen.rs              |  1 +
 6 files changed, 68 insertions(+), 2 deletions(-)
 create mode 100644 docs/config/domains/format.rst
 create mode 100644 docs/config/domains/man5.rst

diff --git a/docs/Makefile b/docs/Makefile
index b1ce4f7a..b06badff 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -18,7 +18,8 @@ GENERATED_SYNOPSIS := 						\
 	config/sync/config.rst					\
 	config/verification/config.rst				\
 	config/acl/roles.rst					\
-	config/datastore/config.rst
+	config/datastore/config.rst				\
+	config/domains/config.rst
 
 MAN1_PAGES := 				\
 	pxar.1				\
@@ -40,7 +41,8 @@ MAN5_PAGES :=				\
 	remote.cfg.5			\
 	sync.cfg.5			\
 	verification.cfg.5		\
-	datastore.cfg.5
+	datastore.cfg.5			\
+	domains.cfg.5
 
 PRUNE_SIMULATOR_FILES := 					\
 	prune-simulator/index.html				\
diff --git a/docs/conf.py b/docs/conf.py
index 59f27c42..8944926e 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -105,6 +105,7 @@ man_pages = [
     # configs
     ('config/acl/man5', 'acl.cfg', 'Access Control Configuration', [author], 5),
     ('config/datastore/man5', 'datastore.cfg', 'Datastore Configuration', [author], 5),
+    ('config/domains/man5', 'domains.cfg', 'Realm Configuration', [author], 5),
     ('config/media-pool/man5', 'media-pool.cfg', 'Media Pool Configuration', [author], 5),
     ('config/remote/man5', 'remote.cfg', 'Remote Server Configuration', [author], 5),
     ('config/sync/man5', 'sync.cfg', 'Synchronization Job Configuration', [author], 5),
diff --git a/docs/config/domains/format.rst b/docs/config/domains/format.rst
new file mode 100644
index 00000000..d92cd473
--- /dev/null
+++ b/docs/config/domains/format.rst
@@ -0,0 +1,27 @@
+This file contains the list authentication realms.
+
+Each user configuration section starts with the header ``<realm-type>: <name>``,
+followed by the realm's configuration options.
+
+For LDAP realms, the LDAP bind password is stored in ``ldap_passwords.json``.
+
+::
+
+  openid: master
+	client-id pbs
+	comment
+	issuer-url http://192.168.0.10:8080/realms/master
+	username-claim username
+
+  ldap: ldap-server
+	base-dn OU=People,DC=ldap-server,DC=example,DC=com
+	mode ldaps
+	server1 192.168.0.10
+	sync-attributes email=mail
+	sync-defaults-options enable-new=0,remove-vanished=acl;entry
+	user-attr uid
+	user-classes inetorgperson,posixaccount,person,user
+
+
+You can use the ``proxmox-backup-manager openid`` and ``proxmox-backup-manager ldap`` commands to manipulate
+this file.
diff --git a/docs/config/domains/man5.rst b/docs/config/domains/man5.rst
new file mode 100644
index 00000000..83341ec1
--- /dev/null
+++ b/docs/config/domains/man5.rst
@@ -0,0 +1,21 @@
+===========
+domains.cfg
+===========
+
+Description
+===========
+
+The file /etc/proxmox-backup/domains.cfg is a configuration file for Proxmox
+Backup Server. It contains the realm configuration.
+
+File Format
+===========
+
+.. include:: format.rst
+
+Options
+=======
+
+.. include:: config.rst
+
+.. include:: ../../pbs-copyright.rst
diff --git a/docs/configuration-files.rst b/docs/configuration-files.rst
index 047636a2..12a4a54e 100644
--- a/docs/configuration-files.rst
+++ b/docs/configuration-files.rst
@@ -36,6 +36,20 @@ Options
 
 .. include:: config/datastore/config.rst
 
+``domains.cfg``
+~~~~~~~~~~~~~~~~~
+
+File Format
+^^^^^^^^^^^
+
+.. include:: config/domains/format.rst
+
+
+Options
+^^^^^^^
+
+.. include:: config/domains/config.rst
+
 
 ``media-pool.cfg``
 ~~~~~~~~~~~~~~~~~~
diff --git a/src/bin/docgen.rs b/src/bin/docgen.rs
index beea4cf1..0b8cc065 100644
--- a/src/bin/docgen.rs
+++ b/src/bin/docgen.rs
@@ -30,6 +30,7 @@ fn main() -> Result<(), Error> {
         let text = match arg.as_ref() {
             "apidata.js" => generate_api_tree(),
             "datastore.cfg" => dump_section_config(&pbs_config::datastore::CONFIG),
+            "domains.cfg" => dump_section_config(&pbs_config::domains::CONFIG),
             "tape.cfg" => dump_section_config(&pbs_config::drive::CONFIG),
             "tape-job.cfg" => dump_section_config(&pbs_config::tape_job::CONFIG),
             "user.cfg" => dump_section_config(&pbs_config::user::CONFIG),
-- 
2.30.2