[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 at proxmox.com:
> From: Nicolas Frey <n.frey at proxmox.com>
> 
> Signed-off-by: Nicolas Frey <n.frey at 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) = @_;