[pbs-devel] [PATCH proxmox] proxmox-product-config: fix code documentation on permissions

[Laurențiu Leahu-Vlăducu]

This patch fixes the documentation of some functions being
inconsistent with the actual code. While such inconsistencies are
never good, when it comes to permissions, they might have even worse
consequences.

To be precise, this patch fixes the following:
- replace_config() actually uses permissions 0640 (docs stated 0660)
- although the possibility of setting a privileged user (usually root,
but possibly different) has been added in the past, the docs still
stated "root" or "superuser". However, some functions also explicitly
use "root", which made it even more confusing. It is now clear which
functions use the API user, which use the privileged user, and which
explicitly use root.
- fixed some small style inconsistencies (e.g. priv-user instead
of priv_user)

Signed-off-by: Laurențiu Leahu-Vlăducu <l.leahu-vladucu at proxmox.com>
---
 .../src/filesystem_helpers.rs                 | 26 +++++++++----------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/proxmox-product-config/src/filesystem_helpers.rs b/proxmox-product-config/src/filesystem_helpers.rs
index 9aa8b1a4..d9f0e827 100644
--- a/proxmox-product-config/src/filesystem_helpers.rs
+++ b/proxmox-product-config/src/filesystem_helpers.rs
@@ -17,9 +17,9 @@ pub fn default_create_options() -> CreateOptions {
         .group(api_user.gid)
 }
 
-/// Return [CreateOptions] for files owned by `priv_user.uid:api-user.gid` with permission `0640`.
+/// Return [CreateOptions] for files owned by `priv_user.uid:api_user.gid` with permission `0640`.
 ///
-/// Only the superuser can write those files, but group `api-user.gid` can read them.
+/// Only `priv_user` can write those files, but group `api_user.gid` can read them.
 pub fn privileged_create_options() -> CreateOptions {
     let api_user = get_api_user();
     let priv_user = get_priv_user();
@@ -30,9 +30,9 @@ pub fn privileged_create_options() -> CreateOptions {
         .group(api_user.gid)
 }
 
-/// Return [CreateOptions] for files owned by `priv_user.uid: priv_user.gid` with permission `0600`.
+/// Return [CreateOptions] for files owned by `priv_user.uid:priv_user.gid` with permission `0600`.
 ///
-/// Only the superuser can read and write those files.
+/// Only `priv_user` can read and write those files.
 pub fn secret_create_options() -> CreateOptions {
     let priv_user = get_priv_user();
     let mode = Mode::from_bits_truncate(0o0600);
@@ -63,16 +63,16 @@ pub fn lockfile_create_options() -> CreateOptions {
         .group(api_user.gid)
 }
 
-/// Atomically write data to file owned by `priv_user.uid:api-user.gid` with permission `0640`
+/// Atomically write data to file owned by `priv_user.uid:api_user.gid` with permission `0640`
 ///
-/// Only the superuser can write those files, but group 'api-user' can read them.
+/// Only `priv_user` can write those files, but group 'api_user' can read them.
 pub fn replace_privileged_config<P: AsRef<Path>>(path: P, data: &[u8]) -> Result<(), Error> {
     let options = privileged_create_options();
     proxmox_sys::fs::replace_file(path, data, options, true)?;
     Ok(())
 }
 
-/// Atomically write data to file owned by `api-user.uid:api-user.gid` with permission `0660`.
+/// Atomically write data to file owned by `api_user.uid:api_user.gid` with permission `0640`.
 pub fn replace_config<P: AsRef<Path>>(path: P, data: &[u8]) -> Result<(), Error> {
     let options = default_create_options();
     proxmox_sys::fs::replace_file(path, data, options, true)?;
@@ -81,7 +81,7 @@ pub fn replace_config<P: AsRef<Path>>(path: P, data: &[u8]) -> Result<(), Error>
 
 /// Atomically write data to file owned by `priv_user.uid:priv_user.gid` with permission `0600`.
 ///
-/// Only the superuser can read and write those files.
+/// Only `priv_user` can read and write those files.
 pub fn replace_secret_config<P: AsRef<Path>>(path: P, data: &[u8]) -> Result<(), Error> {
     let options = secret_create_options();
     proxmox_sys::fs::replace_file(path, data, options, true)?;
@@ -119,15 +119,15 @@ pub unsafe fn create_mocked_lock() -> ApiLockGuard {
     ApiLockGuard(None)
 }
 
-/// Open or create a lock file owned by user `api-user` and lock it.
+/// Open or create a lock file owned by user `api_user` and lock it.
 ///
-/// Owner/Group of the file is set to `api-user.uid/api-user.gid`.
+/// Owner/Group of the file is set to `api_user.uid/api_user.gid`.
 /// File mode is `0660`.
 /// Default timeout is 10 seconds.
 ///
 /// The lock is released as soon as you drop the returned lock guard.
 ///
-/// Note: This method needs to be called by user `root` or `api-user`.
+/// Note: This method needs to be called by `priv_user` or `api_user`.
 pub fn open_api_lockfile<P: AsRef<Path>>(
     path: P,
     timeout: Option<std::time::Duration>,
@@ -139,14 +139,14 @@ pub fn open_api_lockfile<P: AsRef<Path>>(
     Ok(ApiLockGuard(Some(file)))
 }
 ///
-/// Open or create a lock file owned by root and lock it.
+/// Open or create a lock file owned by `priv_user` and lock it.
 ///
 /// File mode is `0600`.
 /// Default timeout is 10 seconds.
 ///
 /// The lock is released as soon as you drop the returned lock guard.
 ///
-/// Note: This method needs to be called by user `root`.
+/// Note: This method needs to be called by user `priv_user`.
 pub fn open_secret_lockfile<P: AsRef<Path>>(
     path: P,
     timeout: Option<std::time::Duration>,
-- 
2.39.5