[pve-devel] [PATCH pve-manager 0/5] api: add return schemas and fix grammar in ifupdown2 error message

[pve-devel] [PATCH pve-manager 0/5] api: add return schemas and fix grammar in ifupdown2 error message

[n.frey]

From: Nicolas Frey <n.frey@proxmox.com>

Adds return schemas for various API endpoints (for documentation purposes) and fixes a minor grammar issue.

Nicolas Frey (5):
  Fix grammar in ifupdown2 version error message
  api: add ACME plugin return schema
  api: add APT versions return schema
  api: add service state return schema
  api: add replication config read return schema

 PVE/API2/ACMEPlugin.pm        | 49 ++++++++++++++++++++++++++++
 PVE/API2/APT.pm               | 61 ++++++++++++++++++++++++++++++++++-
 PVE/API2/Network.pm           |  2 +-
 PVE/API2/ReplicationConfig.pm |  2 +-
 PVE/API2/Services.pm          | 30 ++++++++++++++++-
 5 files changed, 140 insertions(+), 4 deletions(-)

-- 
2.47.3


_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [PATCH pve-manager 1/5] Fix grammar in ifupdown2 version error message

[n.frey]

From: Nicolas Frey <n.frey@proxmox.com>

Signed-off-by: Nicolas Frey <n.frey@proxmox.com>
---
 PVE/API2/Network.pm | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/PVE/API2/Network.pm b/PVE/API2/Network.pm
index 7fb7667e..fc053fec 100644
--- a/PVE/API2/Network.pm
+++ b/PVE/API2/Network.pm
@@ -873,7 +873,7 @@ sub assert_ifupdown2_installed {
     die "you need ifupdown2 to reload network configuration\n" if !-e '/usr/share/ifupdown2';
     my ($v, $pve, $v_str) = ifupdown2_version();
     die
-        "incompatible 'ifupdown2' package version '$v_str'! Did you installed from Proxmox repositories?\n"
+        "incompatible 'ifupdown2' package version '$v_str'! Did you install from Proxmox repositories?\n"
         if $v < (1 * 100000 + 2 * 1000 + 8 * 10) || !$pve;
 }
 
-- 
2.47.3


_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [PATCH pve-manager 2/5] api: add ACME plugin return schema

[n.frey]

From: Nicolas Frey <n.frey@proxmox.com>

Signed-off-by: Nicolas Frey <n.frey@proxmox.com>
---
 PVE/API2/ACMEPlugin.pm | 49 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/PVE/API2/ACMEPlugin.pm b/PVE/API2/ACMEPlugin.pm
index 510101aa..b67cb1ff 100644
--- a/PVE/API2/ACMEPlugin.pm
+++ b/PVE/API2/ACMEPlugin.pm
@@ -76,6 +76,29 @@ __PACKAGE__->register_method({
             type => "object",
             properties => {
                 plugin => get_standard_option('pve-acme-pluginid'),
+                'validation-delay' => {
+                    type => 'integer',
+                    description => 'Waiting period after a DNS record is created.',
+                    default => 30,
+                    optional => 1
+                },
+                data => {
+                    type => 'string',
+                    description => 'Additional data like keys, server, url etc.',
+                    optional => 1
+                },
+                api => {
+                    type => 'string',
+                    description => 'One of the DNS APIs listed in /json/cluster/challenge-schema.'
+                },
+                digest => {
+                    type => 'string',
+                    description => 'Digest to detect modification.'
+                },
+                type => {
+                    type => 'string',
+                    description => ''
+                },
             },
         },
         links => [{ rel => 'child', href => "{plugin}" }],
@@ -113,6 +136,32 @@ __PACKAGE__->register_method({
     },
     returns => {
         type => 'object',
+        properties => {
+            plugin => get_standard_option('pve-acme-pluginid'),
+            'validation-delay' => {
+                type => 'integer',
+                description => 'Waiting period after a DNS record is created.',
+                default => 30,
+                optional => 1
+            },
+            data => {
+                type => 'string',
+                description => 'Additional data like keys, server, url etc.',
+                optional => 1
+            },
+            api => {
+                type => 'string',
+                description => 'One of the DNS APIs listed in /json/cluster/challenge-schema.'
+            },
+            digest => {
+                type => 'string',
+                description => ''
+            },
+            type => {
+                type => 'string',
+                description => ''
+            },
+        },
     },
     code => sub {
         my ($param) = @_;
-- 
2.47.3


_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [PATCH pve-manager 3/5] api: add APT versions return schema

[n.frey]

From: Nicolas Frey <n.frey@proxmox.com>

Signed-off-by: Nicolas Frey <n.frey@proxmox.com>
---
 PVE/API2/APT.pm | 61 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 60 insertions(+), 1 deletion(-)

diff --git a/PVE/API2/APT.pm b/PVE/API2/APT.pm
index 0d07cf38..9a8406a8 100644
--- a/PVE/API2/APT.pm
+++ b/PVE/API2/APT.pm
@@ -788,7 +788,66 @@ __PACKAGE__->register_method({
         type => "array",
         items => {
             type => "object",
-            properties => {},
+            properties => {
+                'Arch' => {
+                    type => 'string',
+                    description => 'Package Architecture.',
+                },
+                'Description' => {
+                    type => 'string',
+                    description => 'Human-readable package description.',
+                },
+                'NotifyStatus' => {
+                    type => 'string',
+                    description =>
+                        'Version for which PVE has already sent an update notification for.',
+                    optional => 1,
+                },
+                'OldVersion' => {
+                    type => 'string',
+                    description => 'Old version currently installed.',
+                    optional => 1,
+                },
+                'Origin' => {
+                    type => 'string',
+                    description => 'Package origin.',
+                },
+                'Package' => {
+                    type => 'string',
+                    description => 'Package name.',
+                },
+                'Priority' => {
+                    type => 'string',
+                    description => 'Package priority in human-readable form.',
+                },
+                'Section' => {
+                    type => 'string',
+                    description => 'Package section.',
+                },
+                'Title' => {
+                    type => 'string',
+                    description => 'Package title.',
+                },
+                'Version' => {
+                    type => 'string',
+                    description => 'New version to be updated to.',
+                },
+                'CurrentState' => {
+                    type => 'string',
+                    description => 'Whether the Package is installed.',
+                    format => '',
+                },
+                'RunningKernel' => {
+                    type => 'string',
+                    description => 'Kernel Release, only for Package "Proxmox Virtual Environment".',
+                    optional => 1,
+                },
+                'ManagerVersion' => {
+                    type => 'string',
+                    description => 'Proxmox Virtual Environment Management Tools.',
+                    optional => 1,
+                }
+            },
         },
     },
     code => sub {
-- 
2.47.3


_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [PATCH pve-manager 4/5] api: add service state return schema

[n.frey]

From: Nicolas Frey <n.frey@proxmox.com>

Signed-off-by: Nicolas Frey <n.frey@proxmox.com>
---
 PVE/API2/Services.pm | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/PVE/API2/Services.pm b/PVE/API2/Services.pm
index 708b6613..c8e3e933 100644
--- a/PVE/API2/Services.pm
+++ b/PVE/API2/Services.pm
@@ -241,7 +241,35 @@ __PACKAGE__->register_method({
     },
     returns => {
         type => "object",
-        properties => {},
+        properties => {
+            'active-state' => {
+                type => 'string',
+                enum => ['active', 'inactive', 'unknown'],
+                description => 'Current active state of the service process.',
+            },
+            'state' => {
+                type => 'string',
+                enum => ['running', 'dead', 'unknown'],
+                description => 'Execution status of the service.',
+            },
+            'unit-state' => {
+                type => 'string',
+                enum => ['enabled', 'disabled', 'not-found'],
+                description => 'Whether the service is enabled to start at boot.',
+            },
+            'service' => {
+                type => 'string',
+                description => 'Systemd unit name (e.g., pveproxy).',
+            },
+            'name' => {
+                type => 'string',
+                description => 'Short identifier for the service (e.g., "pveproxy").',
+            },
+            'desc' => {
+                type => 'string',
+                description => 'Human-readable description of the service.',
+            },
+        },
     },
     code => sub {
         my ($param) = @_;
-- 
2.47.3


_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [PATCH pve-manager 5/5] api: add replication config read return schema

[n.frey]

From: Nicolas Frey <n.frey@proxmox.com>

Signed-off-by: Nicolas Frey <n.frey@proxmox.com>
---
 PVE/API2/ReplicationConfig.pm | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/PVE/API2/ReplicationConfig.pm b/PVE/API2/ReplicationConfig.pm
index 307ebe69..515afcec 100644
--- a/PVE/API2/ReplicationConfig.pm
+++ b/PVE/API2/ReplicationConfig.pm
@@ -75,7 +75,7 @@ __PACKAGE__->register_method({
             id => get_standard_option('pve-replication-id'),
         },
     },
-    returns => { type => 'object' },
+    returns => PVE::ReplicationConfig->createSchema(),
     code => sub {
         my ($param) = @_;
 
-- 
2.47.3


_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

Re: [pve-devel] [PATCH pve-manager 2/5] api: add ACME plugin return schema

[Thomas Lamprecht]

Am 19.09.25 um 11:40 schrieb n.frey@proxmox.com:
> From: Nicolas Frey <n.frey@proxmox.com>
> 

FYI: these methods are operating on modules that base off a so called
SectionConfig. This is quite widely used in our stack, not only in PVE
but also in rust based projects like PBS.

I'd recommend skimming the SectionConfig.pm in the pve-commong git repo
to get a basic overview. And as the underlying config types (meaning dns
and standalone) already define a schema for their respective config types,
and while we did not really reuse that for return schema until now IIRC,
it might actually work quite well to reuse the createSchema method (or
a slight derivation from that).

That said, doing that naturally adds a bit of scope to the task you're
doing here, might be still a nice learning experience in any case though.

The rest of the review commits are written such that they ignore the
potential for reusing the SectionConfig for the schema.

> Signed-off-by: Nicolas Frey <n.frey@proxmox.com>
> ---
>  PVE/API2/ACMEPlugin.pm | 49 ++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 49 insertions(+)
> 
> diff --git a/PVE/API2/ACMEPlugin.pm b/PVE/API2/ACMEPlugin.pm
> index 510101aa..b67cb1ff 100644
> --- a/PVE/API2/ACMEPlugin.pm
> +++ b/PVE/API2/ACMEPlugin.pm
> @@ -76,6 +76,29 @@ __PACKAGE__->register_method({
>              type => "object",
>              properties => {
>                  plugin => get_standard_option('pve-acme-pluginid'),
> +                'validation-delay' => {
> +                    type => 'integer',
> +                    description => 'Waiting period after a DNS record is created.',

Stating the unit is always great for such things, as else the user has
to guess if this is milliseconds, seconds, minutes, ...

The wording is also slightly ambiguous IMO, maybe go with something like:

The waiting period in seconds before validation starts after a DNS challenge
record has been created.

> +                    default => 30,
> +                    optional => 1
> +                },
> +                data => {
> +                    type => 'string',
> +                    description => 'Additional data like keys, server, url etc.',
> +                    optional => 1
> +                },
> +                api => {
> +                    type => 'string',
> +                    description => 'One of the DNS APIs listed in /json/cluster/challenge-schema.'

Referring to another API endpoint can be OK, but I'd not include the
formatter, as we have multiple ones (e.g. json, extjs, html).

And this should be marked as optional, as while it's always present for
the plugins of type "dns", it isn't for the ones of type "standalone" (HTTP
challenge).

> +                },
> +                digest => {
> +                    type => 'string',
> +                    description => 'Digest to detect modification.'
> +                },
> +                type => {
> +                    type => 'string',
> +                    description => ''

Should have a description and could be a enumeration of the possible variants,
i.e.:

    enum => ['dns', 'standalone']

> +                },
>              },
>          },
>          links => [{ rel => 'child', href => "{plugin}" }],
> @@ -113,6 +136,32 @@ __PACKAGE__->register_method({
>      },
>      returns => {
>          type => 'object',
> +        properties => {
> +            plugin => get_standard_option('pve-acme-pluginid'),
> +            'validation-delay' => {
> +                type => 'integer',
> +                description => 'Waiting period after a DNS record is created.',
> +                default => 30,
> +                optional => 1
> +            },
> +            data => {
> +                type => 'string',
> +                description => 'Additional data like keys, server, url etc.',
> +                optional => 1
> +            },
> +            api => {
> +                type => 'string',
> +                description => 'One of the DNS APIs listed in /json/cluster/challenge-schema.'
> +            },
> +            digest => {
> +                type => 'string',
> +                description => ''
> +            },
> +            type => {
> +                type => 'string',
> +                description => ''
> +            },

shares comments with above, and FWIW, even if we do not want to reuse the section
config schema, we still could use a hash variable to reuse the same schema between
both methods, once nested in an array and once as directed return schema.

> +        },
>      },
>      code => sub {
>          my ($param) = @_;



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] applied: [PATCH pve-manager 1/5] Fix grammar in ifupdown2 version error message

[Thomas Lamprecht]

Am 19.09.25 um 11:40 schrieb n.frey@proxmox.com:
> From: Nicolas Frey <n.frey@proxmox.com>
> 
> Signed-off-by: Nicolas Frey <n.frey@proxmox.com>
> ---
>  PVE/API2/Network.pm | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
>

applied this one already, thanks!


_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

Re: [pve-devel] [PATCH pve-manager 3/5] api: add APT versions return schema

[Thomas Lamprecht]

Am 19.09.25 um 11:40 schrieb n.frey@proxmox.com:
> From: Nicolas Frey <n.frey@proxmox.com>
> 
> Signed-off-by: Nicolas Frey <n.frey@proxmox.com>
> ---
>  PVE/API2/APT.pm | 61 ++++++++++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 60 insertions(+), 1 deletion(-)
> 
> diff --git a/PVE/API2/APT.pm b/PVE/API2/APT.pm
> index 0d07cf38..9a8406a8 100644
> --- a/PVE/API2/APT.pm
> +++ b/PVE/API2/APT.pm
> @@ -788,7 +788,66 @@ __PACKAGE__->register_method({
>          type => "array",
>          items => {
>              type => "object",
> -            properties => {},
> +            properties => {
> +                'Arch' => {
> +                    type => 'string',
> +                    description => 'Package Architecture.',

Could be an enum, and would not hurt to add other archs besides "all" and "amd64"
here too, as while that are currently the only relevant ones for us, there are
some community projects for arm64 and riscv64 (not sure if those are the exact
architectures as Debian APT/DPKG uses them though, you need to confirm yourself)

> +                },
> +                'Description' => {
> +                    type => 'string',
> +                    description => 'Human-readable package description.',
> +                },
> +                'NotifyStatus' => {
> +                    type => 'string',
> +                    description =>
> +                        'Version for which PVE has already sent an update notification for.',
> +                    optional => 1,
> +                },
> +                'OldVersion' => {
> +                    type => 'string',
> +                    description => 'Old version currently installed.',
> +                    optional => 1,

The ordering of the keys feels a bit off, IMO it would be best to order
them alphabetically, as that's probably the most useful order when
browsing the code here,

> +                },
> +                'Origin' => {
> +                    type => 'string',
> +                    description => 'Package origin.',

Including some examples what this might look like would IMO help a little
bit even if we might not be able to specify a complete enum here. E.g.:

"Package origin, e.g., 'Proxmox' or 'Debian'"

> +                },
> +                'Package' => {
> +                    type => 'string',
> +                    description => 'Package name.',
> +                },
> +                'Priority' => {
> +                    type => 'string',
> +                    description => 'Package priority in human-readable form.',

The priority as per APT/DPKG is always in human readable form though?

> +                },
> +                'Section' => {
> +                    type => 'string',
> +                    description => 'Package section.',
> +                },
> +                'Title' => {
> +                    type => 'string',
> +                    description => 'Package title.',
> +                },
> +                'Version' => {
> +                    type => 'string',
> +                    description => 'New version to be updated to.',
> +                },
> +                'CurrentState' => {
> +                    type => 'string',
> +                    description => 'Whether the Package is installed.',
> +                    format => '',

The empty string for the format has not much use, could be a enum, albeit
not 100% sure how future proof the variants from DPKG are (probably, but
would need checking).

> +                },
> +                'RunningKernel' => {
> +                    type => 'string',
> +                    description => 'Kernel Release, only for Package "Proxmox Virtual Environment".',

s/Release/release/ and if you refer to the value of another field, like
with Package here, I'd use the actual value, like "proxmox-ve" here.



> +                    optional => 1,
> +                },
> +                'ManagerVersion' => {
> +                    type => 'string',
> +                    description => 'Proxmox Virtual Environment Management Tools.',

Similar w.r.t. referring to the relevant package name, i.e. I'd use "pve-manager"
here. Like e.g.:

"Version of the currently running pve-manager API server."

> +                    optional => 1,
> +                }
> +            },
>          },
>      },
>      code => sub {



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

Re: [pve-devel] [PATCH pve-manager 4/5] api: add service state return schema

[Thomas Lamprecht]

Am 19.09.25 um 11:40 schrieb n.frey@proxmox.com:
> From: Nicolas Frey <n.frey@proxmox.com>
> 
> Signed-off-by: Nicolas Frey <n.frey@proxmox.com>
> ---
>  PVE/API2/Services.pm | 30 +++++++++++++++++++++++++++++-
>  1 file changed, 29 insertions(+), 1 deletion(-)
> 
> diff --git a/PVE/API2/Services.pm b/PVE/API2/Services.pm
> index 708b6613..c8e3e933 100644
> --- a/PVE/API2/Services.pm
> +++ b/PVE/API2/Services.pm
> @@ -241,7 +241,35 @@ __PACKAGE__->register_method({
>      },
>      returns => {
>          type => "object",
> -        properties => {},
> +        properties => {
> +            'active-state' => {
> +                type => 'string',
> +                enum => ['active', 'inactive', 'unknown'],

This is taken 1:1 from systemd's ActiveState of a unit.

You can check the systemd.directives manual page for all known configuration
and most state terms that systemd knows about. For "ActiveState" it links
to the manual page describing the D-Bus interface of systemd, which has
a table with all known values [1] that has a few more variants than what you
include above.

[0]: https://manpages.debian.org/trixie/systemd/systemd.directives.7.en.html
[1]: https://manpages.debian.org/trixie/systemd/org.freedesktop.systemd1.5.en.html#:~:text=Unit%20ACTIVE%20states

> +                description => 'Current active state of the service process.',
> +            },
> +            'state' => {
> +                type => 'string',
> +                enum => ['running', 'dead', 'unknown'],

Similar to above this can be a few other variants as well, you can check our
code and then [1] to see what values this can actually include.

> +                description => 'Execution status of the service.',
> +            },
> +            'unit-state' => {
> +                type => 'string',
> +                enum => ['enabled', 'disabled', 'not-found'],

There are a few additional variants here too, see [1] again, "UnitFileState" is
documented quite close to the "ActiveState"

> +                description => 'Whether the service is enabled to start at boot.',
> +            },
> +            'service' => {
> +                type => 'string',
> +                description => 'Systemd unit name (e.g., pveproxy).',

While not wrong, this is actually what we refer to the systemd unit
too, i.e. it might resolve to a different name if we use a (outdated)
alias or the like. But not really relevant and hard to encode into the
description, so fine by me as is.

> +            },
> +            'name' => {
> +                type => 'string',
> +                description => 'Short identifier for the service (e.g., "pveproxy").',

> +            },
> +            'desc' => {
> +                type => 'string',
> +                description => 'Human-readable description of the service.',
> +            },
> +        },
>      },
>      code => sub {
>          my ($param) = @_;



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

Re: [pve-devel] [PATCH pve-manager 5/5] api: add replication config read return schema

[Thomas Lamprecht]

Am 19.09.25 um 11:40 schrieb n.frey@proxmox.com:
> From: Nicolas Frey <n.frey@proxmox.com>
 
Ah, you actually figured about re-using the SectionConfig schema
here, but some commit message would be really warranted here to
explain why it's fine to use the *create* schema as *return*
schema. Don't get me wrong, that might be fine (I expect it too
from a gut feeling, but did not actually checked and reasoned),
but such things really need a basic rationale to describe why
it actually is. And if it is then you can naturally switch the
ACME return endpoint also to such a style.


> Signed-off-by: Nicolas Frey <n.frey@proxmox.com>
> ---
>  PVE/API2/ReplicationConfig.pm | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/PVE/API2/ReplicationConfig.pm b/PVE/API2/ReplicationConfig.pm
> index 307ebe69..515afcec 100644
> --- a/PVE/API2/ReplicationConfig.pm
> +++ b/PVE/API2/ReplicationConfig.pm
> @@ -75,7 +75,7 @@ __PACKAGE__->register_method({
>              id => get_standard_option('pve-replication-id'),
>          },
>      },
> -    returns => { type => 'object' },
> +    returns => PVE::ReplicationConfig->createSchema(),
>      code => sub {
>          my ($param) = @_;
>  



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel