From af18706fcbca2f57967f4d4e2a7da4a021164c96 Mon Sep 17 00:00:00 2001 From: Maximiliano Sandoval Date: Mon, 27 Jan 2025 15:42:03 +0100 Subject: [PATCH] docs: add synopsis and basic docs for prune job configuration Have our docgen tool generate a synopsis for the prune.cfg schema, and use that output in a new prune.cfg manpage, and include it in the appropriate appendix of our html/pdf rendered admin guide. Signed-off-by: Maximiliano Sandoval [TL: expand commit message and keep alphabetical order for configs in the guide.] Signed-off-by: Thomas Lamprecht --- debian/proxmox-backup-server.install | 1 + docs/Makefile | 2 ++ docs/conf.py | 1 + docs/config/prune/format.rst | 14 ++++++++++++++ docs/config/prune/man5.rst | 23 +++++++++++++++++++++++ docs/configuration-files.rst | 15 +++++++++++++++ src/bin/docgen.rs | 1 + 7 files changed, 57 insertions(+) create mode 100644 docs/config/prune/format.rst create mode 100644 docs/config/prune/man5.rst diff --git a/debian/proxmox-backup-server.install b/debian/proxmox-backup-server.install index ff581e3d..a562d5e8 100644 --- a/debian/proxmox-backup-server.install +++ b/debian/proxmox-backup-server.install @@ -40,6 +40,7 @@ usr/share/man/man5/tape-job.cfg.5 usr/share/man/man5/tape.cfg.5 usr/share/man/man5/user.cfg.5 usr/share/man/man5/verification.cfg.5 +usr/share/man/man5/prune.cfg.5 usr/share/proxmox-backup/templates/default/acme-err-body.txt.hbs usr/share/proxmox-backup/templates/default/acme-err-subject.txt.hbs usr/share/proxmox-backup/templates/default/gc-err-body.txt.hbs diff --git a/docs/Makefile b/docs/Makefile index 66da6037..c57cbbc2 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -13,6 +13,7 @@ GENERATED_SYNOPSIS := \ config/tape/config.rst \ config/user/config.rst \ config/verification/config.rst \ + config/prune/config.rst \ pmt/synopsis.rst \ pmtx/synopsis.rst \ proxmox-backup-client/catalog-shell-synopsis.rst \ @@ -52,6 +53,7 @@ MAN5_PAGES := \ tape.cfg.5 \ user.cfg.5 \ verification.cfg.5 \ + prune.cfg.5 \ PRUNE_SIMULATOR_FILES := \ prune-simulator/index.html \ diff --git a/docs/conf.py b/docs/conf.py index 41d4ab97..a7fa1079 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -115,6 +115,7 @@ man_pages = [ ('config/tape/man5', 'tape.cfg', 'Tape Drive and Changer Configuration', [author], 5), ('config/user/man5', 'user.cfg', 'User Configuration', [author], 5), ('config/verification/man5', 'verification.cfg', 'Verification Job Configuration', [author], 5), + ('config/prune/man5', 'prune.cfg', 'Prune Job Configuration', [author], 5), ('config/notifications/man5', 'notifications.cfg', 'Notification target/matcher configuration', [author], 5), ('config/notifications-priv/man5', 'notifications-priv.cfg', 'Notification target secrets', [author], 5), ] diff --git a/docs/config/prune/format.rst b/docs/config/prune/format.rst new file mode 100644 index 00000000..104f183e --- /dev/null +++ b/docs/config/prune/format.rst @@ -0,0 +1,14 @@ +Each entry starts with the header ``prune: ``, followed by the job +configuration options. + +:: + + prune: prune-store2 + schedule mon..fri 10:30 + store my-datastore + + prune: ... + + +You can use the ``proxmox-backup-manager prune-job`` command to manipulate this +file. diff --git a/docs/config/prune/man5.rst b/docs/config/prune/man5.rst new file mode 100644 index 00000000..121ed184 --- /dev/null +++ b/docs/config/prune/man5.rst @@ -0,0 +1,23 @@ +:orphan: + +========= +prune.cfg +========= + +Description +=========== + +The file /etc/proxmox-backup/prune.cfg is a configuration file for Proxmox +Backup Server. It contains the prune job 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 5fabf48c..7389afa0 100644 --- a/docs/configuration-files.rst +++ b/docs/configuration-files.rst @@ -108,6 +108,21 @@ Options .. include:: config/notifications-priv/config.rst +``prune.cfg`` +~~~~~~~~~~~~~ + +File Format +^^^^^^^^^^^ + +.. include:: config/prune/format.rst + + +Options +^^^^^^^ + +.. include:: config/prune/config.rst + + ``tape.cfg`` ~~~~~~~~~~~~ diff --git a/src/bin/docgen.rs b/src/bin/docgen.rs index 66d71423..e012abe6 100644 --- a/src/bin/docgen.rs +++ b/src/bin/docgen.rs @@ -41,6 +41,7 @@ fn main() -> Result<(), Error> { "remote.cfg" => dump_section_config(&pbs_config::remote::CONFIG), "sync.cfg" => dump_section_config(&pbs_config::sync::CONFIG), "verification.cfg" => dump_section_config(&pbs_config::verify::CONFIG), + "prune.cfg" => dump_section_config(&pbs_config::prune::CONFIG), "media-pool.cfg" => dump_section_config(&pbs_config::media_pool::CONFIG), "config::acl::Role" => dump_enum_properties(&pbs_api_types::Role::API_SCHEMA)?, _ => bail!("docgen: got unknown type"),