docs: add manual page for acl.cfg

debian/proxmox-backup-server.install

@@ -20,6 +20,7 @@ usr/share/man/man1/proxmox-backup-manager.1
 usr/share/man/man1/proxmox-backup-proxy.1
 usr/share/man/man1/pmtx.1
 usr/share/man/man1/pmt.1
+usr/share/man/man5/acl.cfg.5
 usr/share/man/man5/datastore.cfg.5
 usr/share/man/man5/user.cfg.5
 usr/share/man/man5/remote.cfg.5

docs/Makefile

@@ -12,6 +12,7 @@ GENERATED_SYNOPSIS := 						\
 	config/user/config.rst					\
 	config/remote/config.rst				\
 	config/sync/config.rst					\
+	config/acl/roles.rst					\
 	config/datastore/config.rst
 
 MAN1_PAGES := 				\
@@ -23,6 +24,7 @@ MAN1_PAGES := 				\
 	proxmox-backup-manager.1
 
 MAN5_PAGES :=				\
+	acl.cfg.5			\
 	user.cfg.5			\
 	remote.cfg.5			\
 	sync.cfg.5			\
@@ -119,6 +121,12 @@ config/sync/config.rst: ${COMPILEDIR}/docgen
 sync.cfg.5: config/sync/man5.rst config/sync/config.rst config/sync/format.rst
 	rst2man $< >$@
 
+config/acl/roles.rst: ${COMPILEDIR}/docgen
+	${COMPILEDIR}/docgen "config::acl::Role" >$@
+
+acl.cfg.5: config/acl/man5.rst config/acl/roles.rst config/acl/format.rst
+	rst2man $< >$@
+
 proxmox-backup-client/synopsis.rst: ${COMPILEDIR}/proxmox-backup-client
 	${COMPILEDIR}/proxmox-backup-client printdoc > proxmox-backup-client/synopsis.rst
 

docs/config/acl/format.rst

@@ -0,0 +1,22 @@
+This file contains the access control list for the Proxmox Backup
+Server API.
+
+Each line starts with ``acl:``, followed by 4 additional values
+separated by collon.
+
+:propagate: Propagate permissions down the hierachrchy
+
+:path: The object path
+
+:User/Token: List of users and token
+
+:Role: List of assigned roles
+
+Here is an example list::
+
+   acl:1:/:root@pam!test:Admin
+   acl:1:/datastore/store1:user1@pbs:DatastoreAdmin
+
+
+You can use the ``proxmox-backup-manager acl`` command to manipulate
+this file.

docs/config/acl/man5.rst

@@ -0,0 +1,35 @@
+==========================
+acl.cfg
+==========================
+
+.. include:: ../../epilog.rst
+
+-------------------------------------------------------------
+Access Control Configuration
+-------------------------------------------------------------
+
+:Author: |AUTHOR|
+:Version: Version |VERSION|
+:Manual section: 5
+
+Description
+===========
+
+The file /etc/proxmox-backup/user.cfg is a configuration file for Proxmox
+Backup Server. It contains the access control configuration for the API.
+
+File Format
+===========
+
+.. include:: format.rst
+
+
+Roles
+=====
+
+The following roles exist:
+
+.. include:: roles.rst
+
+
+.. include:: ../../pbs-copyright.rst

docs/configuration-files.rst

@@ -5,6 +5,23 @@ All Proxmox Backup Server configuration files resides inside directory
 ``/etc/proxmox-backup/``.
 
 
+``acl.cfg``
+~~~~~~~~~~~~~~~~~
+
+File Format
+^^^^^^^^^^^
+
+.. include:: config/acl/format.rst
+
+
+Roles
+^^^^^
+
+The following roles exist:
+
+.. include:: config/acl/roles.rst
+
+
 ``datastore.cfg``
 ~~~~~~~~~~~~~~~~~
 

src/bin/docgen.rs

@@ -1,6 +1,9 @@
 use anyhow::{bail, Error};
 
-use proxmox::api::format::dump_section_config;
+use proxmox::api::format::{
+    dump_enum_properties,
+    dump_section_config,
+};
 
 use proxmox_backup::{
     config,
@@ -25,15 +28,17 @@ fn main() -> Result<(), Error> {
     }
     
     for arg in args.iter() {
-        match arg.as_ref() {
+        let text = match arg.as_ref() {
-            "datastore.cfg" => println!("{}", dump_section_config(&config::datastore::CONFIG)),
+            "datastore.cfg" => dump_section_config(&config::datastore::CONFIG),
-            "tape.cfg" => println!("{}", dump_section_config(&config::drive::CONFIG)),
+            "tape.cfg" => dump_section_config(&config::drive::CONFIG),
-            "user.cfg" => println!("{}", dump_section_config(&config::user::CONFIG)),
+            "user.cfg" => dump_section_config(&config::user::CONFIG),
-            "remote.cfg" => println!("{}", dump_section_config(&config::remote::CONFIG)),
+            "remote.cfg" => dump_section_config(&config::remote::CONFIG),
-            "sync.cfg" => println!("{}", dump_section_config(&config::sync::CONFIG)),
+            "sync.cfg" => dump_section_config(&config::sync::CONFIG),
-            "media-pool.cfg" => println!("{}", dump_section_config(&config::media_pool::CONFIG)),
+            "media-pool.cfg" => dump_section_config(&config::media_pool::CONFIG),
+            "config::acl::Role" => dump_enum_properties(&config::acl::Role::API_SCHEMA)?,
             _ => bail!("docgen: got unknown type"),
-        }
+        };
+        println!("{}", text);
     }
    
     Ok(())