* [PATCH manager] api: backup: add return schema for backup jobs
@ 2026-03-27 15:20 Lukas Wagner
2026-04-01 9:55 ` Thomas Lamprecht
2026-04-01 11:47 ` Thomas Lamprecht
0 siblings, 2 replies; 6+ messages in thread
From: Lukas Wagner @ 2026-03-27 15:20 UTC (permalink / raw)
To: pve-devel
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH manager] api: backup: add return schema for backup jobs
2026-03-27 15:20 [PATCH manager] api: backup: add return schema for backup jobs Lukas Wagner
@ 2026-04-01 9:55 ` Thomas Lamprecht
2026-04-01 10:01 ` Lukas Wagner
2026-04-01 11:47 ` Thomas Lamprecht
1 sibling, 1 reply; 6+ messages in thread
From: Thomas Lamprecht @ 2026-04-01 9:55 UTC (permalink / raw)
To: Lukas Wagner, pve-devel
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,
},
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH manager] api: backup: add return schema for backup jobs
2026-04-01 9:55 ` Thomas Lamprecht
@ 2026-04-01 10:01 ` Lukas Wagner
2026-04-01 11:46 ` Thomas Lamprecht
0 siblings, 1 reply; 6+ messages in thread
From: Lukas Wagner @ 2026-04-01 10:01 UTC (permalink / raw)
To: Thomas Lamprecht, Lukas Wagner, pve-devel
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,
> },
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH manager] api: backup: add return schema for backup jobs
2026-04-01 10:01 ` Lukas Wagner
@ 2026-04-01 11:46 ` Thomas Lamprecht
2026-04-01 14:11 ` Lukas Wagner
0 siblings, 1 reply; 6+ messages in thread
From: Thomas Lamprecht @ 2026-04-01 11:46 UTC (permalink / raw)
To: Lukas Wagner, pve-devel
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH manager] api: backup: add return schema for backup jobs
2026-03-27 15:20 [PATCH manager] api: backup: add return schema for backup jobs Lukas Wagner
2026-04-01 9:55 ` Thomas Lamprecht
@ 2026-04-01 11:47 ` Thomas Lamprecht
1 sibling, 0 replies; 6+ messages in thread
From: Thomas Lamprecht @ 2026-04-01 11:47 UTC (permalink / raw)
To: pve-devel, Lukas Wagner
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH manager] api: backup: add return schema for backup jobs
2026-04-01 11:46 ` Thomas Lamprecht
@ 2026-04-01 14:11 ` Lukas Wagner
0 siblings, 0 replies; 6+ messages in thread
From: Lukas Wagner @ 2026-04-01 14:11 UTC (permalink / raw)
To: Thomas Lamprecht, Lukas Wagner, pve-devel
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
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2026-04-01 14:11 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2026-03-27 15:20 [PATCH manager] api: backup: add return schema for backup jobs Lukas Wagner
2026-04-01 9:55 ` Thomas Lamprecht
2026-04-01 10:01 ` Lukas Wagner
2026-04-01 11:46 ` Thomas Lamprecht
2026-04-01 14:11 ` Lukas Wagner
2026-04-01 11:47 ` Thomas Lamprecht
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox