[PATCH manager] api: backup: add return schema for backup jobs

[PATCH manager] api: backup: add return schema for backup jobs

[Lukas Wagner]

The GET /cluster/backup and /cluster/backup/<jobid> endpoints were
missing a proper return value schema. The schema properties themselves
were copied from the POST call, but needed to be slightly adapted.

 - id is a pve-backup-jobid, since this is what was used before
 - fleecing, performance and prune-backups are submitted as a property
   string, but returned as a proper JSON object, so these needed to be
   overridden from the base config that stems from pve-guest-common
 - 'next-run' was added

Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>
---
 PVE/API2/Backup.pm | 79 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 76 insertions(+), 3 deletions(-)

diff --git a/PVE/API2/Backup.pm b/PVE/API2/Backup.pm
index 27f5a14c..8317d0c3 100644
--- a/PVE/API2/Backup.pm
+++ b/PVE/API2/Backup.pm
@@ -120,6 +120,80 @@ my $schedule_param_check = sub {
     delete $param->{dow};
 };
 
+my $backup_job_return_schema = PVE::VZDump::Common::json_config_properties({
+    id => get_standard_option('pve-backup-jobid'),
+    schedule => {
+        description => "Backup schedule. The format is a subset of `systemd` calendar events.",
+        type => 'string',
+        format => 'pve-calendar-event',
+        maxLength => 128,
+        optional => 1,
+    },
+    starttime => {
+        type => 'string',
+        description => "Job Start time.",
+        pattern => '\d{1,2}:\d{1,2}',
+        typetext => 'HH:MM',
+        optional => 1,
+    },
+    dow => {
+        type => 'string',
+        format => 'pve-day-of-week-list',
+        optional => 1,
+        description => "Day of week selection.",
+        requires => 'starttime',
+        default => ALL_DAYS,
+    },
+    enabled => {
+        type => 'boolean',
+        optional => 1,
+        description => "Enable or disable the job.",
+        default => '1',
+    },
+    'repeat-missed' => {
+        optional => 1,
+        type => 'boolean',
+        description => "If true, the job will be run as soon as possible if it was missed"
+            . " while the scheduler was not running.",
+        default => 0,
+    },
+    comment => {
+        optional => 1,
+        type => 'string',
+        description => "Description for the Job.",
+        maxLength => 512,
+    },
+    'next-run' => {
+        description => "UNIX timestamp when this backup job will be executed next",
+        optional => 1,
+        type => 'integer',
+    },
+});
+
+# 'fleecing', 'prune-backups' and 'performance' are property strings in POST and PUT,  but proper
+# objects when they are returned from the API, which is why we need to override them here.
+$backup_job_return_schema->{'fleecing'} = {
+    description => "Options for backup fleecing (VM only).",
+    type => 'object',
+    optional => 1,
+    properties => PVE::JSONSchema::get_format('backup-fleecing'),
+};
+
+$backup_job_return_schema->{'prune-backups'} = {
+    description =>
+        "Use these retention options instead of those from the storage configuration.",
+    type => 'object',
+    optional => 1,
+    properties => PVE::JSONSchema::get_format('prune-backups'),
+};
+
+$backup_job_return_schema->{'performance'} = {
+    description => "Other performance-related settings.",
+    type => 'object',
+    optional => 1,
+    properties => PVE::JSONSchema::get_format('backup-performance'),
+};
+
 __PACKAGE__->register_method({
     name => 'index',
     path => '',
@@ -136,9 +210,7 @@ __PACKAGE__->register_method({
         type => 'array',
         items => {
             type => "object",
-            properties => {
-                id => get_standard_option('pve-backup-jobid'),
-            },
+            properties => $backup_job_return_schema,
         },
         links => [{ rel => 'child', href => "{id}" }],
     },
@@ -309,6 +381,7 @@ __PACKAGE__->register_method({
     },
     returns => {
         type => 'object',
+        properties => $backup_job_return_schema,
     },
     code => sub {
         my ($param) = @_;
-- 
2.47.3

Re: [PATCH manager] api: backup: add return schema for backup jobs

[Thomas Lamprecht]

Am 27.03.26 um 16:19 schrieb Lukas Wagner:
> The GET /cluster/backup and /cluster/backup/<jobid> endpoints were
> missing a proper return value schema. The schema properties themselves
> were copied from the POST call, but needed to be slightly adapted.
> 
>  - id is a pve-backup-jobid, since this is what was used before
>  - fleecing, performance and prune-backups are submitted as a property
>    string, but returned as a proper JSON object, so these needed to be
>    overridden from the base config that stems from pve-guest-common
>  - 'next-run' was added
> 
> Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>
> ---
>  PVE/API2/Backup.pm | 79 ++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 76 insertions(+), 3 deletions(-)
> 
> diff --git a/PVE/API2/Backup.pm b/PVE/API2/Backup.pm
> index 27f5a14c..8317d0c3 100644
> --- a/PVE/API2/Backup.pm
> +++ b/PVE/API2/Backup.pm
> @@ -120,6 +120,80 @@ my $schedule_param_check = sub {
>      delete $param->{dow};
>  };
>  
> +my $backup_job_return_schema = PVE::VZDump::Common::json_config_properties({
> +    id => get_standard_option('pve-backup-jobid'),
> +    schedule => {
> +        description => "Backup schedule. The format is a subset of `systemd` calendar events.",
> +        type => 'string',
> +        format => 'pve-calendar-event',
> +        maxLength => 128,
> +        optional => 1,
> +    },
> +    starttime => {
> +        type => 'string',
> +        description => "Job Start time.",
> +        pattern => '\d{1,2}:\d{1,2}',
> +        typetext => 'HH:MM',
> +        optional => 1,
> +    },
> +    dow => {
> +        type => 'string',
> +        format => 'pve-day-of-week-list',
> +        optional => 1,
> +        description => "Day of week selection.",
> +        requires => 'starttime',
> +        default => ALL_DAYS,
> +    },

I'd apply this with the following on-top or squashed-in, ack?

----8<----
diff --git a/PVE/API2/Backup.pm b/PVE/API2/Backup.pm
index 8317d0c38..1d6d42570 100644
--- a/PVE/API2/Backup.pm
+++ b/PVE/API2/Backup.pm
@@ -131,7 +131,7 @@ my $backup_job_return_schema = PVE::VZDump::Common::json_config_properties({
     },
     starttime => {
         type => 'string',
-        description => "Job Start time.",
+        description => "Job start-time (server timezone); deprecated and replaced by schedule.",
         pattern => '\d{1,2}:\d{1,2}',
         typetext => 'HH:MM',
         optional => 1,
@@ -140,7 +140,7 @@ my $backup_job_return_schema = PVE::VZDump::Common::json_config_properties({
         type => 'string',
         format => 'pve-day-of-week-list',
         optional => 1,
-        description => "Day of week selection.",
+        description => "Day of week selection; deprecated and replaced by schedule.",
         requires => 'starttime',
         default => ALL_DAYS,
     },

Re: [PATCH manager] api: backup: add return schema for backup jobs

[Lukas Wagner]

On Wed Apr 1, 2026 at 11:55 AM CEST, Thomas Lamprecht wrote:
> Am 27.03.26 um 16:19 schrieb Lukas Wagner:
>> The GET /cluster/backup and /cluster/backup/<jobid> endpoints were
>> missing a proper return value schema. The schema properties themselves
>> were copied from the POST call, but needed to be slightly adapted.
>> 
>>  - id is a pve-backup-jobid, since this is what was used before
>>  - fleecing, performance and prune-backups are submitted as a property
>>    string, but returned as a proper JSON object, so these needed to be
>>    overridden from the base config that stems from pve-guest-common
>>  - 'next-run' was added
>> 
>> Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>
>> ---
>>  PVE/API2/Backup.pm | 79 ++++++++++++++++++++++++++++++++++++++++++++--
>>  1 file changed, 76 insertions(+), 3 deletions(-)
>> 
>> diff --git a/PVE/API2/Backup.pm b/PVE/API2/Backup.pm
>> index 27f5a14c..8317d0c3 100644
>> --- a/PVE/API2/Backup.pm
>> +++ b/PVE/API2/Backup.pm
>> @@ -120,6 +120,80 @@ my $schedule_param_check = sub {
>>      delete $param->{dow};
>>  };
>>  
>> +my $backup_job_return_schema = PVE::VZDump::Common::json_config_properties({
>> +    id => get_standard_option('pve-backup-jobid'),
>> +    schedule => {
>> +        description => "Backup schedule. The format is a subset of `systemd` calendar events.",
>> +        type => 'string',
>> +        format => 'pve-calendar-event',
>> +        maxLength => 128,
>> +        optional => 1,
>> +    },
>> +    starttime => {
>> +        type => 'string',
>> +        description => "Job Start time.",
>> +        pattern => '\d{1,2}:\d{1,2}',
>> +        typetext => 'HH:MM',
>> +        optional => 1,
>> +    },
>> +    dow => {
>> +        type => 'string',
>> +        format => 'pve-day-of-week-list',
>> +        optional => 1,
>> +        description => "Day of week selection.",
>> +        requires => 'starttime',
>> +        default => ALL_DAYS,
>> +    },
>
> I'd apply this with the following on-top or squashed-in, ack?

ack; looks good to me!

>
> ----8<----
> diff --git a/PVE/API2/Backup.pm b/PVE/API2/Backup.pm
> index 8317d0c38..1d6d42570 100644
> --- a/PVE/API2/Backup.pm
> +++ b/PVE/API2/Backup.pm
> @@ -131,7 +131,7 @@ my $backup_job_return_schema = PVE::VZDump::Common::json_config_properties({
>      },
>      starttime => {
>          type => 'string',
> -        description => "Job Start time.",
> +        description => "Job start-time (server timezone); deprecated and replaced by schedule.",
>          pattern => '\d{1,2}:\d{1,2}',
>          typetext => 'HH:MM',
>          optional => 1,
> @@ -140,7 +140,7 @@ my $backup_job_return_schema = PVE::VZDump::Common::json_config_properties({
>          type => 'string',
>          format => 'pve-day-of-week-list',
>          optional => 1,
> -        description => "Day of week selection.",
> +        description => "Day of week selection; deprecated and replaced by schedule.",
>          requires => 'starttime',
>          default => ALL_DAYS,
>      },

Re: [PATCH manager] api: backup: add return schema for backup jobs

[Thomas Lamprecht]

Am 01.04.26 um 12:00 schrieb Lukas Wagner:
>>> +my $backup_job_return_schema = PVE::VZDump::Common::json_config_properties({
>>> +    id => get_standard_option('pve-backup-jobid'),
>>> +    schedule => {
>>> +        description => "Backup schedule. The format is a subset of `systemd` calendar events.",
>>> +        type => 'string',
>>> +        format => 'pve-calendar-event',
>>> +        maxLength => 128,
>>> +        optional => 1,
>>> +    },
>>> +    starttime => {
>>> +        type => 'string',
>>> +        description => "Job Start time.",
>>> +        pattern => '\d{1,2}:\d{1,2}',
>>> +        typetext => 'HH:MM',
>>> +        optional => 1,
>>> +    },
>>> +    dow => {
>>> +        type => 'string',
>>> +        format => 'pve-day-of-week-list',
>>> +        optional => 1,
>>> +        description => "Day of week selection.",
>>> +        requires => 'starttime',
>>> +        default => ALL_DAYS,
>>> +    },
>> I'd apply this with the following on-top or squashed-in, ack?

Hmm, we might actually just drop above two legacy fields here (soon).

As for the modern jobs.cfg (based on PVE::Job::Registry in pve-common) we do not
have them anymore at all, AFAICT, so those are only possible for the old CRON
based vzdump.cron, and those we map in the API endpoint via:

 my $data = cfs_read_file('vzdump.cron');
 
 my $res = $data->{jobs} || [];                      
 foreach my $job (@$res) {
     $job->{schedule} = $convert_to_schedule->($job);
 }

The convert_to_schedule method keeps the current starttime/dow params, but the
API contract now is basically, dow and starttime might be there, if a vzdum.cron
still exists and nobody updated/added/removed any backup job since a while, as
that would convert them to the modern jobs.cfg, having keept the old vzdump.cron
only around to ensure that PVE nodes with older pve-mananger in a cluster still
handle pre-existing backup old-style jobs correctly.
But that was introduced mostly in commit 305921b1a ("api/backup: handle new
vzdump jobs") [0] back in PVE 7.1 days, so we probably can just drop that, and
we probably also do not need to wait until a next major release, as vzdum.cron
cannot really be used anymore in practice (besides manual editing, which I do
not care that much for). And for the backup job API response it's rather a clear
cut, schedule is _always_ present, starttime/dow basically never, and all (API)
clients need to cope with schedule since PVE 7.1, so dropping it from the return
schema and (not a must, but nicer) deleting them from the response should be fine.

I know, it's a bit annoying to have those legacy ghosts in scope for such
patches, but it has some value to clean a few of them up when they resurface,
especially when doing this with the end goal of encoding such types in rust in
pve-api-types for use with PDM, as all legacy cruft we can safely shave off can
make our life simpler.

[0]: https://git.proxmox.com/?p=pve-manager.git;a=commitdiff;h=305921b1a

Re: [PATCH manager] api: backup: add return schema for backup jobs

[Lukas Wagner]

On Wed Apr 1, 2026 at 1:46 PM CEST, Thomas Lamprecht wrote:
> The convert_to_schedule method keeps the current starttime/dow params, but the
> API contract now is basically, dow and starttime might be there, if a vzdum.cron
> still exists and nobody updated/added/removed any backup job since a while, as
> that would convert them to the modern jobs.cfg, having keept the old vzdump.cron
> only around to ensure that PVE nodes with older pve-mananger in a cluster still
> handle pre-existing backup old-style jobs correctly.
> But that was introduced mostly in commit 305921b1a ("api/backup: handle new
> vzdump jobs") [0] back in PVE 7.1 days, so we probably can just drop that, and
> we probably also do not need to wait until a next major release, as vzdum.cron
> cannot really be used anymore in practice (besides manual editing, which I do
> not care that much for). And for the backup job API response it's rather a clear
> cut, schedule is _always_ present, starttime/dow basically never, and all (API)
> clients need to cope with schedule since PVE 7.1, so dropping it from the return
> schema and (not a must, but nicer) deleting them from the response should be fine.
>
> I know, it's a bit annoying to have those legacy ghosts in scope for such
> patches, but it has some value to clean a few of them up when they resurface,
> especially when doing this with the end goal of encoding such types in rust in
> pve-api-types for use with PDM, as all legacy cruft we can safely shave off can
> make our life simpler.
>
> [0]: https://git.proxmox.com/?p=pve-manager.git;a=commitdiff;h=305921b1a


Thanks for the detailed explanation, highly appreciated.

I've sent a follow-up, I hope this is what you've had in mind:

https://lore.proxmox.com/all/20260401140903.364176-1-l.wagner@proxmox.com/T/#u

Re: [PATCH manager] api: backup: add return schema for backup jobs

[Thomas Lamprecht]

On Fri, 27 Mar 2026 16:20:15 +0100, Lukas Wagner wrote:
> The GET /cluster/backup and /cluster/backup/<jobid> endpoints were
> missing a proper return value schema. The schema properties themselves
> were copied from the POST call, but needed to be slightly adapted.
> 
>  - id is a pve-backup-jobid, since this is what was used before
>  - fleecing, performance and prune-backups are submitted as a property
>    string, but returned as a proper JSON object, so these needed to be
>    overridden from the base config that stems from pve-guest-common
>  - 'next-run' was added
> 
> [...]

Applied this now, but please see my other reply for potentially dropping dow
and starttime completely here (which is IMO best done as follow-up), thanks!

[1/1] api: backup: add return schema for backup jobs
      commit: 0e85aecd829f838c5eb41f7655502a492ba651bd