1 package PVE
::API2
::Backup
;
9 use PVE
::Tools
qw(extract_param);
10 use PVE
::Cluster
qw(cfs_lock_file cfs_read_file cfs_write_file);
12 use PVE
::RPCEnvironment
;
15 use PVE
::Exception
qw(raise_param_exc);
17 use PVE
::VZDump
::Common
;
18 use PVE
::VZDump
::JobBase
;
19 use PVE
::Jobs
; # for VZDump Jobs
20 use Proxmox
::RS
::CalendarEvent
;
22 use base
qw(PVE::RESTHandler);
24 use constant ALL_DAYS
=> 'mon,tue,wed,thu,fri,sat,sun';
26 PVE
::JSONSchema
::register_format
('pve-day-of-week', \
&verify_day_of_week
);
27 sub verify_day_of_week
{
28 my ($value, $noerr) = @_;
30 return $value if $value =~ m/^(mon|tue|wed|thu|fri|sat|sun)$/;
32 return undef if $noerr;
34 die "invalid day '$value'\n";
37 my $vzdump_job_id_prop = {
39 description
=> "The job ID.",
43 # NOTE: also used by the vzdump API call.
44 sub assert_param_permission_common
{
45 my ($rpcenv, $user, $param) = @_;
46 return if $user eq 'root@pam'; # always OK
48 for my $key (qw(tmpdir dumpdir script)) {
49 raise_param_exc
({ $key => "Only root may set this option."}) if exists $param->{$key};
52 if (defined($param->{bwlimit
}) || defined($param->{ionice
}) || defined($param->{performance
})) {
53 $rpcenv->check($user, "/", [ 'Sys.Modify' ]);
57 my sub assert_param_permission_create
{
58 my ($rpcenv, $user, $param) = @_;
59 return if $user eq 'root@pam'; # always OK
61 assert_param_permission_common
($rpcenv, $user, $param);
63 if (my $storeid = PVE
::VZDump
::get_storage_param
($param)) {
64 $rpcenv->check($user, "/storage/$storeid", [ 'Datastore.Allocate' ]);
68 my sub assert_param_permission_update
{
69 my ($rpcenv, $user, $update, $delete, $current) = @_;
70 return if $user eq 'root@pam'; # always OK
72 assert_param_permission_common
($rpcenv, $user, $update);
73 assert_param_permission_common
($rpcenv, $user, $delete);
75 if ($update->{storage
}) {
76 $rpcenv->check($user, "/storage/$update->{storage}", [ 'Datastore.Allocate' ])
77 } elsif ($delete->{storage
}) {
78 $rpcenv->check($user, "/storage/local", [ 'Datastore.Allocate' ]);
81 return if !$current; # early check done
83 if ($current->{dumpdir
}) {
84 die "only root\@pam may edit jobs with a 'dumpdir' option.";
86 if (my $storeid = PVE
::VZDump
::get_storage_param
($current)) {
87 $rpcenv->check($user, "/storage/$storeid", [ 'Datastore.Allocate' ]);
92 my $convert_to_schedule = sub {
95 my $starttime = $job->{starttime
};
97 return "$starttime" if !$job->{dow
}; # dow is restrictive, so none means all days
99 # normalize as it could be a null-separated list previously
100 my $dow = join(',', PVE
::Tools
::split_list
($job->{dow
}));
102 return $dow eq ALL_DAYS ?
"$starttime" : "$dow $starttime";
105 my $schedule_param_check = sub {
106 my ($param, $required) = @_;
107 if (defined($param->{schedule
})) {
108 if (defined($param->{starttime
})) {
109 raise_param_exc
({ starttime
=> "'starttime' and 'schedule' cannot both be set" });
111 } elsif (!defined($param->{starttime
})) {
112 raise_param_exc
({ schedule
=> "neither 'starttime' nor 'schedule' were set" })
115 $param->{schedule
} = $convert_to_schedule->($param);
118 delete $param->{starttime
};
119 delete $param->{dow
};
122 __PACKAGE__-
>register_method({
126 description
=> "List vzdump backup schedule.",
128 check
=> ['perm', '/', ['Sys.Audit']],
131 additionalProperties
=> 0,
139 id
=> $vzdump_job_id_prop
142 links
=> [ { rel
=> 'child', href
=> "{id}" } ],
147 my $rpcenv = PVE
::RPCEnvironment
::get
();
148 my $user = $rpcenv->get_user();
150 my $data = cfs_read_file
('vzdump.cron');
151 my $jobs_data = cfs_read_file
('jobs.cfg');
152 my $order = $jobs_data->{order
};
153 my $jobs = $jobs_data->{ids
};
155 my $res = $data->{jobs
} || [];
156 foreach my $job (@$res) {
157 $job->{schedule
} = $convert_to_schedule->($job);
160 foreach my $jobid (sort { $order->{$a} <=> $order->{$b} } keys %$jobs) {
161 my $job = $jobs->{$jobid};
162 next if $job->{type
} ne 'vzdump';
164 if (my $schedule = $job->{schedule
}) {
165 # vzdump jobs are cluster wide, there maybe was no local run
166 # so simply calculate from now
167 my $last_run = time();
168 my $calspec = Proxmox
::RS
::CalendarEvent-
>new($schedule);
169 my $next_run = $calspec->compute_next_event($last_run);
170 $job->{'next-run'} = $next_run if defined($next_run);
173 # FIXME remove in PVE 8.0?
174 # backwards compat: before moving the job registry to pve-common, id was auto-injected
183 __PACKAGE__-
>register_method({
184 name
=> 'create_job',
188 description
=> "Create new vzdump backup job.",
190 check
=> ['perm', '/', ['Sys.Modify']],
191 description
=> "The 'tmpdir', 'dumpdir' and 'script' parameters are additionally restricted to the 'root\@pam' user.",
194 additionalProperties
=> 0,
195 properties
=> PVE
::VZDump
::Common
::json_config_properties
({
198 description
=> "Job ID (will be autogenerated).",
199 format
=> 'pve-configid',
200 optional
=> 1, # FIXME: make required on 8.0
203 description
=> "Backup schedule. The format is a subset of `systemd` calendar events.",
204 type
=> 'string', format
=> 'pve-calendar-event',
210 description
=> "Job Start time.",
211 pattern
=> '\d{1,2}:\d{1,2}',
216 type
=> 'string', format
=> 'pve-day-of-week-list',
218 description
=> "Day of week selection.",
219 requires
=> 'starttime',
225 description
=> "Enable or disable the job.",
231 description
=> "If true, the job will be run as soon as possible if it was missed".
232 " while the scheduler was not running.",
238 description
=> "Description for the Job.",
243 returns
=> { type
=> 'null' },
247 my $rpcenv = PVE
::RPCEnvironment
::get
();
248 my $user = $rpcenv->get_user();
250 assert_param_permission_create
($rpcenv, $user, $param);
252 if (my $pool = $param->{pool
}) {
253 $rpcenv->check_pool_exist($pool);
254 $rpcenv->check($user, "/pool/$pool", ['VM.Backup']);
257 $schedule_param_check->($param, 1);
259 $param->{enabled
} = 1 if !defined($param->{enabled
});
261 # autogenerate id for api compatibility FIXME remove with 8.0
262 my $id = extract_param
($param, 'id') // UUID
::uuid
();
264 cfs_lock_file
('jobs.cfg', undef, sub {
265 my $data = cfs_read_file
('jobs.cfg');
267 die "Job '$id' already exists\n"
268 if $data->{ids
}->{$id};
270 PVE
::VZDump
::verify_vzdump_parameters
($param, 1);
271 my $opts = PVE
::VZDump
::JobBase-
>check_config($id, $param, 1, 1);
273 $data->{ids
}->{$id} = $opts;
275 PVE
::Jobs
::create_job
($id, 'vzdump', $opts);
277 cfs_write_file
('jobs.cfg', $data);
284 __PACKAGE__-
>register_method({
288 description
=> "Read vzdump backup job definition.",
290 check
=> ['perm', '/', ['Sys.Audit']],
293 additionalProperties
=> 0,
295 id
=> $vzdump_job_id_prop
304 my $rpcenv = PVE
::RPCEnvironment
::get
();
305 my $user = $rpcenv->get_user();
307 my $data = cfs_read_file
('vzdump.cron');
309 my $jobs = $data->{jobs
} || [];
311 foreach my $job (@$jobs) {
312 if ($job->{id
} eq $param->{id
}) {
313 $job->{schedule
} = $convert_to_schedule->($job);
318 my $jobs_data = cfs_read_file
('jobs.cfg');
319 my $job = $jobs_data->{ids
}->{$param->{id
}};
320 if ($job && $job->{type
} eq 'vzdump') {
321 # FIXME remove in PVE 8.0?
322 # backwards compat: before moving the job registry to pve-common, id was auto-injected
323 $job->{id
} = $param->{id
};
327 raise_param_exc
({ id
=> "No such job '$param->{id}'" });
331 __PACKAGE__-
>register_method({
332 name
=> 'delete_job',
335 description
=> "Delete vzdump backup job definition.",
337 check
=> ['perm', '/', ['Sys.Modify']],
341 additionalProperties
=> 0,
343 id
=> $vzdump_job_id_prop
346 returns
=> { type
=> 'null' },
350 my $rpcenv = PVE
::RPCEnvironment
::get
();
351 my $user = $rpcenv->get_user();
353 my $id = $param->{id
};
355 my $delete_job = sub {
356 my $data = cfs_read_file
('vzdump.cron');
358 my $jobs = $data->{jobs
} || [];
362 foreach my $job (@$jobs) {
363 if ($job->{id
} eq $id) {
366 push @$newjobs, $job;
371 cfs_lock_file
('jobs.cfg', undef, sub {
372 my $jobs_data = cfs_read_file
('jobs.cfg');
374 if (!defined($jobs_data->{ids
}->{$id})) {
375 raise_param_exc
({ id
=> "No such job '$id'" });
377 delete $jobs_data->{ids
}->{$id};
379 PVE
::Jobs
::remove_job
($id, 'vzdump');
381 cfs_write_file
('jobs.cfg', $jobs_data);
385 $data->{jobs
} = $newjobs;
387 cfs_write_file
('vzdump.cron', $data);
390 cfs_lock_file
('vzdump.cron', undef, $delete_job);
396 __PACKAGE__-
>register_method({
397 name
=> 'update_job',
401 description
=> "Update vzdump backup job definition.",
403 check
=> ['perm', '/', ['Sys.Modify']],
404 description
=> "The 'tmpdir', 'dumpdir' and 'script' parameters are additionally restricted to the 'root\@pam' user.",
407 additionalProperties
=> 0,
408 properties
=> PVE
::VZDump
::Common
::json_config_properties
({
409 id
=> $vzdump_job_id_prop,
411 description
=> "Backup schedule. The format is a subset of `systemd` calendar events.",
412 type
=> 'string', format
=> 'pve-calendar-event',
418 description
=> "Job Start time.",
419 pattern
=> '\d{1,2}:\d{1,2}',
424 type
=> 'string', format
=> 'pve-day-of-week-list',
426 requires
=> 'starttime',
427 description
=> "Day of week selection.",
430 type
=> 'string', format
=> 'pve-configid-list',
431 description
=> "A list of settings you want to delete.",
437 description
=> "Enable or disable the job.",
443 description
=> "If true, the job will be run as soon as possible if it was missed".
444 " while the scheduler was not running.",
450 description
=> "Description for the Job.",
455 returns
=> { type
=> 'null' },
459 my $rpcenv = PVE
::RPCEnvironment
::get
();
460 my $user = $rpcenv->get_user();
462 if (my $pool = $param->{pool
}) {
463 $rpcenv->check_pool_exist($pool);
464 $rpcenv->check($user, "/pool/$pool", ['VM.Backup']);
467 $schedule_param_check->($param);
469 my $id = extract_param
($param, 'id');
470 my $delete = extract_param
($param, 'delete');
471 $delete = { map { $_ => 1 } PVE
::Tools
::split_list
($delete) } if $delete;
473 assert_param_permission_update
($rpcenv, $user, $param, $delete);
475 my $update_job = sub {
476 my $data = cfs_read_file
('vzdump.cron');
477 my $jobs_data = cfs_read_file
('jobs.cfg');
479 my $jobs = $data->{jobs
} || [];
481 die "no options specified\n" if !scalar(keys $param->%*) && !scalar(keys $delete->%*);
483 PVE
::VZDump
::verify_vzdump_parameters
($param);
484 my $opts = PVE
::VZDump
::JobBase-
>check_config($id, $param, 0, 1);
486 # try to find it in old vzdump.cron and convert it to a job
487 my ($idx) = grep { $jobs->[$_]->{id
} eq $id } (0 .. scalar(@$jobs) - 1);
491 $job = splice @$jobs, $idx, 1;
492 $job->{schedule
} = $convert_to_schedule->($job);
493 delete $job->{starttime
};
496 $job->{type
} = 'vzdump';
497 $jobs_data->{ids
}->{$id} = $job;
499 $job = $jobs_data->{ids
}->{$id};
500 die "no such vzdump job\n" if !$job || $job->{type
} ne 'vzdump';
503 assert_param_permission_update
($rpcenv, $user, $param, $delete, $job);
507 'repeat-missed' => 1,
510 for my $k (keys $delete->%*) {
511 if (!PVE
::VZDump
::option_exists
($k) && !$deletable->{$k}) {
512 raise_param_exc
({ delete => "unknown option '$k'" });
518 foreach my $k (keys %$param) {
519 $job->{$k} = $param->{$k};
522 $job->{all
} = 1 if (defined($job->{exclude
}) && !defined($job->{pool
}));
524 if (defined($param->{vmid
})) {
526 delete $job->{exclude
};
528 } elsif ($param->{all
}) {
531 } elsif ($job->{pool
}) {
534 delete $job->{exclude
};
537 PVE
::VZDump
::verify_vzdump_parameters
($job, 1);
540 cfs_write_file
('vzdump.cron', $data);
542 cfs_write_file
('jobs.cfg', $jobs_data);
544 PVE
::Jobs
::detect_changed_runtime_props
($id, 'vzdump', $job);
548 cfs_lock_file
('vzdump.cron', undef, sub {
549 cfs_lock_file
('jobs.cfg', undef, $update_job);
555 __PACKAGE__-
>register_method({
556 name
=> 'get_volume_backup_included',
557 path
=> '{id}/included_volumes',
560 description
=> "Returns included guests and the backup status of their disks. Optimized to be used in ExtJS tree views.",
562 check
=> ['perm', '/', ['Sys.Audit']],
565 additionalProperties
=> 0,
567 id
=> $vzdump_job_id_prop
572 description
=> 'Root node of the tree object. Children represent guests, grandchildren represent volumes of that guest.',
581 description
=> 'VMID of the guest.',
585 description
=> 'Name of the guest',
590 description
=> 'Type of the guest, VM, CT or unknown for removed but not purged guests.',
591 enum
=> ['qemu', 'lxc', 'unknown'],
596 description
=> 'The volumes of the guest with the information if they will be included in backups.',
602 description
=> 'Configuration key of the volume.',
606 description
=> 'Name of the volume.',
610 description
=> 'Whether the volume is included in the backup or not.',
614 description
=> 'The reason why the volume is included (or excluded).',
627 my $rpcenv = PVE
::RPCEnvironment
::get
();
629 my $user = $rpcenv->get_user();
631 my $vzconf = cfs_read_file
('vzdump.cron');
632 my $all_jobs = $vzconf->{jobs
} || [];
634 my $rrd = PVE
::Cluster
::rrd_dump
();
636 for my $j (@$all_jobs) {
637 if ($j->{id
} eq $param->{id
}) {
643 my $jobs_data = cfs_read_file
('jobs.cfg');
644 my $j = $jobs_data->{ids
}->{$param->{id
}};
645 if ($j && $j->{type
} eq 'vzdump') {
649 raise_param_exc
({ id
=> "No such job '$param->{id}'" }) if !$job;
651 my $vmlist = PVE
::Cluster
::get_vmlist
();
655 my $included_guests = PVE
::VZDump
::get_included_guests
($job);
657 for my $node (keys %{$included_guests}) {
658 my $node_vmids = $included_guests->{$node};
659 push(@job_vmids, @{$node_vmids});
662 # remove VMIDs to which the user has no permission to not leak infos
663 # like the guest name
664 my @allowed_vmids = grep {
665 $rpcenv->check($user, "/vms/$_", [ 'VM.Audit' ], 1);
672 for my $vmid (@allowed_vmids) {
676 # It's possible that a job has VMIDs configured that are not in
677 # vmlist. This could be because a guest was removed but not purged.
678 # Since there is no more data available we can only deliver the VMID
680 if (!defined $vmlist->{ids
}->{$vmid}) {
681 push(@{$result->{children
}}, {
689 my $type = $vmlist->{ids
}->{$vmid}->{type
};
690 my $node = $vmlist->{ids
}->{$vmid}->{node
};
696 if ($type eq 'qemu') {
697 $conf = PVE
::QemuConfig-
>load_config($vmid, $node);
698 $volumes = PVE
::QemuConfig-
>get_backup_volumes($conf);
699 $name = $conf->{name
};
700 } elsif ($type eq 'lxc') {
701 $conf = PVE
::LXC
::Config-
>load_config($vmid, $node);
702 $volumes = PVE
::LXC
::Config-
>get_backup_volumes($conf);
703 $name = $conf->{hostname
};
705 die "VMID $vmid is neither Qemu nor LXC guest\n";
708 foreach my $volume (@$volumes) {
710 # id field must be unique for ExtJS tree view
711 id
=> "$vmid:$volume->{key}",
712 name
=> $volume->{volume_config
}->{file
} // $volume->{volume_config
}->{volume
},
713 included
=> $volume->{included
},
714 reason
=> $volume->{reason
},
717 push(@{$children}, $disk);
721 # it's possible for a guest to have no volumes configured
722 $leaf = 1 if !@{$children};
724 push(@{$result->{children
}}, {
728 children
=> $children,