[PATCH manager 0/3] api: backup: drop/deprecate dow and starttime

[PATCH manager 0/3] api: backup: drop/deprecate dow and starttime

[Lukas Wagner]

Lukas Wagner (3):
  api: backup: drop starttime and dow from return schema
  api: backup: drop legacy starttime and dow from API response
  api: backup: deprecate starttime and dow in create/update parameter
    schema

 PVE/API2/Backup.pm | 36 +++++++++++++++++-------------------
 1 file changed, 17 insertions(+), 19 deletions(-)

-- 
2.47.3

[PATCH manager 1/3] api: backup: drop starttime and dow from return schema

[Lukas Wagner]

For backup jobs returned by the API, the `dow` and `starttime`
parameters are only ever set for legacy-jobs that are defined in the old
vzdump.cron configuration file. The newer backup jobs based on the
jobs.cfg file were introduced in [0]. Ever since then, any new or
updated backup job was stored in jobs.cfg, meaning that it is rather
unlikely to have any backup jobs in the old configuration file anyways,
from which subsequently follows that the 'dow' and 'starttime' params
will hardly ever be included in the response anyways. And even if a
legacy job is read from the old file, an appropriate 'schedule' key is
automatically synthesized from 'dow' and 'starttime'.

In summary:
  - 'dow' and 'starttime' will hardly ever be set
  - 'schedule' will ALWAYS be set
  - any client needed to understand the 'schedule' parameter since 7.1
    anyways

It should therefore be fine to just drop both old keys from the return
schema; this is a good chance to clean up some legacy cruft.

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

Suggested-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>
---
 PVE/API2/Backup.pm | 15 ---------------
 1 file changed, 15 deletions(-)

diff --git a/PVE/API2/Backup.pm b/PVE/API2/Backup.pm
index 1d6d4257..2ab78834 100644
--- a/PVE/API2/Backup.pm
+++ b/PVE/API2/Backup.pm
@@ -129,21 +129,6 @@ my $backup_job_return_schema = PVE::VZDump::Common::json_config_properties({
         maxLength => 128,
         optional => 1,
     },
-    starttime => {
-        type => 'string',
-        description => "Job start-time (server timezone); deprecated and replaced by schedule.",
-        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; deprecated and replaced by schedule.",
-        requires => 'starttime',
-        default => ALL_DAYS,
-    },
     enabled => {
         type => 'boolean',
         optional => 1,
-- 
2.47.3

[PATCH manager 2/3] api: backup: drop legacy starttime and dow from API response

[Lukas Wagner]

We dropped it from the schema, so it makes sense to drop it from the
actual response as well.

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

diff --git a/PVE/API2/Backup.pm b/PVE/API2/Backup.pm
index 2ab78834..0683748e 100644
--- a/PVE/API2/Backup.pm
+++ b/PVE/API2/Backup.pm
@@ -213,6 +213,8 @@ __PACKAGE__->register_method({
         my $res = $data->{jobs} || [];
         foreach my $job (@$res) {
             $job->{schedule} = $convert_to_schedule->($job);
+            delete $job->{starttime};
+            delete $job->{dow};
         }
 
         foreach my $jobid (sort { $order->{$a} <=> $order->{$b} } keys %$jobs) {
@@ -381,6 +383,9 @@ __PACKAGE__->register_method({
         foreach my $job (@$jobs) {
             if ($job->{id} eq $param->{id}) {
                 $job->{schedule} = $convert_to_schedule->($job);
+                delete $job->{starttime};
+                delete $job->{dow};
+
                 return $job;
             }
         }
-- 
2.47.3

[PATCH manager 3/3] api: backup: deprecate starttime and dow in create/update parameter schema

[Lukas Wagner]

When creating and updating backup jobs, the both parameters will be
supported until further notice -- we only really should remove them in a
major update -- but it definitely makes sense to mark them as deprecated
in the parameter schema and document that these will be automatically
translated into a matching 'schedule'.

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

diff --git a/PVE/API2/Backup.pm b/PVE/API2/Backup.pm
index 0683748e..3bd85593 100644
--- a/PVE/API2/Backup.pm
+++ b/PVE/API2/Backup.pm
@@ -269,18 +269,22 @@ __PACKAGE__->register_method({
                 maxLength => 128,
                 optional => 1,
             },
+            # FIXME: MAJOR VERSION: Drop this deprecated parameter.
             starttime => {
                 type => 'string',
-                description => "Job Start time.",
+                description => "Deprecated: Use 'schedule' instead. Job Start time."
+                    . " 'starttime' and 'dow' will be converted into 'schedule' if used.",
                 pattern => '\d{1,2}:\d{1,2}',
                 typetext => 'HH:MM',
                 optional => 1,
             },
+            # FIXME: MAJOR VERSION: Drop this deprecated parameter.
             dow => {
                 type => 'string',
                 format => 'pve-day-of-week-list',
                 optional => 1,
-                description => "Day of week selection.",
+                description => "Deprecated: Use 'schedule' instead. Day of week selection."
+                    . " 'starttime' and 'dow' will be converted into 'schedule' if used.",
                 requires => 'starttime',
                 default => ALL_DAYS,
             },
@@ -497,19 +501,23 @@ __PACKAGE__->register_method({
                 maxLength => 128,
                 optional => 1,
             },
+            # FIXME: MAJOR VERSION: Drop this deprecated parameter.
             starttime => {
                 type => 'string',
-                description => "Job Start time.",
+                description => "Deprecated: Use 'schedule' instead. Job Start time."
+                    . " 'starttime' and 'dow' will be converted into 'schedule' if used.",
                 pattern => '\d{1,2}:\d{1,2}',
                 typetext => 'HH:MM',
                 optional => 1,
             },
+            # FIXME: MAJOR VERSION: Drop this deprecated parameter.
             dow => {
                 type => 'string',
                 format => 'pve-day-of-week-list',
                 optional => 1,
                 requires => 'starttime',
-                description => "Day of week selection.",
+                description => "Deprecated: Use 'schedule' instead. Day of week selection."
+                    . " 'starttime' and 'dow' will be converted into 'schedule' if used.",
             },
             delete => {
                 type => 'string',
-- 
2.47.3

applied: [PATCH manager 0/3] api: backup: drop/deprecate dow and starttime

[Thomas Lamprecht]

On Wed, 01 Apr 2026 16:08:59 +0200, Lukas Wagner wrote:
> Lukas Wagner (3):
>   api: backup: drop starttime and dow from return schema
>   api: backup: drop legacy starttime and dow from API response
>   api: backup: deprecate starttime and dow in create/update parameter
>     schema
> 
> PVE/API2/Backup.pm | 36 +++++++++++++++++-------------------
>  1 file changed, 17 insertions(+), 19 deletions(-)
> 
> [...]

Applied, thanks!

[1/3] api: backup: drop starttime and dow from return schema
      commit: 75424de1df9b26ba7003ed86614bf01b157e9b0f
[2/3] api: backup: drop legacy starttime and dow from API response
      commit: cc978dd616199e06acee01ea129b482208d97a79
[3/3] api: backup: deprecate starttime and dow in create/update parameter schema
      commit: 336c9a6e453b0fc3d011676052dd3450adf8f938