PVE/API2/Backup.pm

   1 package PVE::API2::Backup;
   2
   3 use strict;
   4 use warnings;
   5 use Digest::SHA;
   6 use UUID qw(uuid);
   7
   8 use PVE::SafeSyslog;
   9 use PVE::Tools qw(extract_param);
  10 use PVE::Cluster qw(cfs_lock_file cfs_read_file cfs_write_file);
  11 use PVE::RESTHandler;
  12 use PVE::RPCEnvironment;
  13 use PVE::JSONSchema;
  14 use PVE::Storage;
  15 use PVE::Exception qw(raise_param_exc);
  16 use PVE::VZDump;
  17 use PVE::VZDump::Common;
  18 use PVE::VZDump::JobBase;
  19 use PVE::Jobs; # for VZDump Jobs
  20 use Proxmox::RS::CalendarEvent;
  21
  22 use base qw(PVE::RESTHandler);
  23
  24 use constant ALL_DAYS => 'mon,tue,wed,thu,fri,sat,sun';
  25
  26 PVE::JSONSchema::register_format('pve-day-of-week', \&verify_day_of_week);
  27 sub verify_day_of_week {
  28     my ($value, $noerr) = @_;
  29
  30     return $value if $value =~ m/^(mon|tue|wed|thu|fri|sat|sun)$/;
  31
  32     return undef if $noerr;
  33
  34     die "invalid day '$value'\n";
  35 }
  36
  37 my $vzdump_job_id_prop = {
  38     type => 'string',
  39     description => "The job ID.",
  40     maxLength => 50
  41 };
  42
  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
  47
  48     for my $key (qw(tmpdir dumpdir script)) {
  49         raise_param_exc({ $key => "Only root may set this option."}) if exists $param->{$key};
  50     }
  51
  52     if (defined($param->{bwlimit}) || defined($param->{ionice}) || defined($param->{performance})) {
  53         $rpcenv->check($user, "/", [ 'Sys.Modify' ]);
  54     }
  55 }
  56
  57 my $convert_to_schedule = sub {
  58     my ($job) = @_;
  59
  60     my $starttime = $job->{starttime};
  61
  62     return "$starttime" if !$job->{dow}; # dow is restrictive, so none means all days
  63
  64     # normalize as it could be a null-separated list previously
  65     my $dow = join(',', PVE::Tools::split_list($job->{dow}));
  66
  67     return $dow eq ALL_DAYS ? "$starttime" : "$dow $starttime";
  68 };
  69
  70 my $schedule_param_check = sub {
  71     my ($param, $required) = @_;
  72     if (defined($param->{schedule})) {
  73         if (defined($param->{starttime})) {
  74             raise_param_exc({ starttime => "'starttime' and 'schedule' cannot both be set" });
  75         }
  76     } elsif (!defined($param->{starttime})) {
  77         raise_param_exc({ schedule => "neither 'starttime' nor 'schedule' were set" })
  78             if $required;
  79     } else {
  80         $param->{schedule} = $convert_to_schedule->($param);
  81     }
  82
  83     delete $param->{starttime};
  84     delete $param->{dow};
  85 };
  86
  87 __PACKAGE__->register_method({
  88     name => 'index',
  89     path => '',
  90     method => 'GET',
  91     description => "List vzdump backup schedule.",
  92     permissions => {
  93         check => ['perm', '/', ['Sys.Audit']],
  94     },
  95     parameters => {
  96         additionalProperties => 0,
  97         properties => {},
  98     },
  99     returns => {
 100         type => 'array',
 101         items => {
 102             type => "object",
 103             properties => {
 104                 id => $vzdump_job_id_prop
 105             },
 106         },
 107         links => [ { rel => 'child', href => "{id}" } ],
 108     },
 109     code => sub {
 110         my ($param) = @_;
 111
 112         my $rpcenv = PVE::RPCEnvironment::get();
 113         my $user = $rpcenv->get_user();
 114
 115         my $data = cfs_read_file('vzdump.cron');
 116         my $jobs_data = cfs_read_file('jobs.cfg');
 117         my $order = $jobs_data->{order};
 118         my $jobs = $jobs_data->{ids};
 119
 120         my $res = $data->{jobs} || [];
 121         foreach my $job (@$res) {
 122             $job->{schedule} = $convert_to_schedule->($job);
 123         }
 124
 125         foreach my $jobid (sort { $order->{$a} <=> $order->{$b} } keys %$jobs) {
 126             my $job = $jobs->{$jobid};
 127             next if $job->{type} ne 'vzdump';
 128
 129             if (my $schedule = $job->{schedule}) {
 130                 # vzdump jobs are cluster wide, there maybe was no local run
 131                 # so simply calculate from now
 132                 my $last_run = time();
 133                 my $calspec = Proxmox::RS::CalendarEvent->new($schedule);
 134                 my $next_run = $calspec->compute_next_event($last_run);
 135                 $job->{'next-run'} = $next_run if defined($next_run);
 136             }
 137
 138             # FIXME remove in PVE 8.0?
 139             # backwards compat: before moving the job registry to pve-common, id was auto-injected
 140             $job->{id} = $jobid;
 141
 142             push @$res, $job;
 143         }
 144
 145         return $res;
 146     }});
 147
 148 __PACKAGE__->register_method({
 149     name => 'create_job',
 150     path => '',
 151     method => 'POST',
 152     protected => 1,
 153     description => "Create new vzdump backup job.",
 154     permissions => {
 155         check => ['perm', '/', ['Sys.Modify']],
 156         description => "The 'tmpdir', 'dumpdir' and 'script' parameters are additionally restricted to the 'root\@pam' user.",
 157     },
 158     parameters => {
 159         additionalProperties => 0,
 160         properties => PVE::VZDump::Common::json_config_properties({
 161             id => {
 162                 type => 'string',
 163                 description => "Job ID (will be autogenerated).",
 164                 format => 'pve-configid',
 165                 optional => 1, # FIXME: make required on 8.0
 166             },
 167             schedule => {
 168                 description => "Backup schedule. The format is a subset of `systemd` calendar events.",
 169                 type => 'string', format => 'pve-calendar-event',
 170                 maxLength => 128,
 171                 optional => 1,
 172             },
 173             starttime => {
 174                 type => 'string',
 175                 description => "Job Start time.",
 176                 pattern => '\d{1,2}:\d{1,2}',
 177                 typetext => 'HH:MM',
 178                 optional => 1,
 179             },
 180             dow => {
 181                 type => 'string', format => 'pve-day-of-week-list',
 182                 optional => 1,
 183                 description => "Day of week selection.",
 184                 requires => 'starttime',
 185                 default => ALL_DAYS,
 186             },
 187             enabled => {
 188                 type => 'boolean',
 189                 optional => 1,
 190                 description => "Enable or disable the job.",
 191                 default => '1',
 192             },
 193             'repeat-missed' => {
 194                 optional => 1,
 195                 type => 'boolean',
 196                 description => "If true, the job will be run as soon as possible if it was missed".
 197                     " while the scheduler was not running.",
 198                 default => 0,
 199             },
 200             comment => {
 201                 optional => 1,
 202                 type => 'string',
 203                 description => "Description for the Job.",
 204                 maxLength => 512,
 205             },
 206        }),
 207     },
 208     returns => { type => 'null' },
 209     code => sub {
 210         my ($param) = @_;
 211
 212         my $rpcenv = PVE::RPCEnvironment::get();
 213         my $user = $rpcenv->get_user();
 214
 215         assert_param_permission_common($rpcenv, $user, $param);
 216
 217         if (my $pool = $param->{pool}) {
 218             $rpcenv->check_pool_exist($pool);
 219             $rpcenv->check($user, "/pool/$pool", ['VM.Backup']);
 220         }
 221
 222         $schedule_param_check->($param, 1);
 223
 224         $param->{enabled} = 1 if !defined($param->{enabled});
 225
 226         # autogenerate id for api compatibility FIXME remove with 8.0
 227         my $id = extract_param($param, 'id') // UUID::uuid();
 228
 229         cfs_lock_file('jobs.cfg', undef, sub {
 230             my $data = cfs_read_file('jobs.cfg');
 231
 232             die "Job '$id' already exists\n"
 233                 if $data->{ids}->{$id};
 234
 235             PVE::VZDump::verify_vzdump_parameters($param, 1);
 236             my $opts = PVE::VZDump::JobBase->check_config($id, $param, 1, 1);
 237
 238             $data->{ids}->{$id} = $opts;
 239
 240             PVE::Jobs::create_job($id, 'vzdump', $opts);
 241
 242             cfs_write_file('jobs.cfg', $data);
 243         });
 244         die "$@" if ($@);
 245
 246         return undef;
 247     }});
 248
 249 __PACKAGE__->register_method({
 250     name => 'read_job',
 251     path => '{id}',
 252     method => 'GET',
 253     description => "Read vzdump backup job definition.",
 254     permissions => {
 255         check => ['perm', '/', ['Sys.Audit']],
 256     },
 257     parameters => {
 258         additionalProperties => 0,
 259         properties => {
 260             id => $vzdump_job_id_prop
 261         },
 262     },
 263     returns => {
 264         type => 'object',
 265     },
 266     code => sub {
 267         my ($param) = @_;
 268
 269         my $rpcenv = PVE::RPCEnvironment::get();
 270         my $user = $rpcenv->get_user();
 271
 272         my $data = cfs_read_file('vzdump.cron');
 273
 274         my $jobs = $data->{jobs} || [];
 275
 276         foreach my $job (@$jobs) {
 277             if ($job->{id} eq $param->{id}) {
 278                 $job->{schedule} = $convert_to_schedule->($job);
 279                 return $job;
 280             }
 281         }
 282
 283         my $jobs_data = cfs_read_file('jobs.cfg');
 284         my $job = $jobs_data->{ids}->{$param->{id}};
 285         if ($job && $job->{type} eq 'vzdump') {
 286             # FIXME remove in PVE 8.0?
 287             # backwards compat: before moving the job registry to pve-common, id was auto-injected
 288             $job->{id} = $param->{id};
 289             return $job;
 290         }
 291
 292         raise_param_exc({ id => "No such job '$param->{id}'" });
 293
 294     }});
 295
 296 __PACKAGE__->register_method({
 297     name => 'delete_job',
 298     path => '{id}',
 299     method => 'DELETE',
 300     description => "Delete vzdump backup job definition.",
 301     permissions => {
 302         check => ['perm', '/', ['Sys.Modify']],
 303     },
 304     protected => 1,
 305     parameters => {
 306         additionalProperties => 0,
 307         properties => {
 308             id => $vzdump_job_id_prop
 309         },
 310     },
 311     returns => { type => 'null' },
 312     code => sub {
 313         my ($param) = @_;
 314
 315         my $rpcenv = PVE::RPCEnvironment::get();
 316         my $user = $rpcenv->get_user();
 317
 318         my $id = $param->{id};
 319
 320         my $delete_job = sub {
 321             my $data = cfs_read_file('vzdump.cron');
 322
 323             my $jobs = $data->{jobs} || [];
 324             my $newjobs = [];
 325
 326             my $found;
 327             foreach my $job (@$jobs) {
 328                 if ($job->{id} eq $id) {
 329                     $found = 1;
 330                 } else {
 331                     push @$newjobs, $job;
 332                 }
 333             }
 334
 335             if (!$found) {
 336                 cfs_lock_file('jobs.cfg', undef, sub {
 337                     my $jobs_data = cfs_read_file('jobs.cfg');
 338
 339                     if (!defined($jobs_data->{ids}->{$id})) {
 340                         raise_param_exc({ id => "No such job '$id'" });
 341                     }
 342                     delete $jobs_data->{ids}->{$id};
 343
 344                     PVE::Jobs::remove_job($id, 'vzdump');
 345
 346                     cfs_write_file('jobs.cfg', $jobs_data);
 347                 });
 348                 die "$@" if $@;
 349             } else {
 350                 $data->{jobs} = $newjobs;
 351
 352                 cfs_write_file('vzdump.cron', $data);
 353             }
 354         };
 355         cfs_lock_file('vzdump.cron', undef, $delete_job);
 356         die "$@" if ($@);
 357
 358         return undef;
 359     }});
 360
 361 __PACKAGE__->register_method({
 362     name => 'update_job',
 363     path => '{id}',
 364     method => 'PUT',
 365     protected => 1,
 366     description => "Update vzdump backup job definition.",
 367     permissions => {
 368         check => ['perm', '/', ['Sys.Modify']],
 369         description => "The 'tmpdir', 'dumpdir' and 'script' parameters are additionally restricted to the 'root\@pam' user.",
 370     },
 371     parameters => {
 372         additionalProperties => 0,
 373         properties => PVE::VZDump::Common::json_config_properties({
 374             id => $vzdump_job_id_prop,
 375             schedule => {
 376                 description => "Backup schedule. The format is a subset of `systemd` calendar events.",
 377                 type => 'string', format => 'pve-calendar-event',
 378                 maxLength => 128,
 379                 optional => 1,
 380             },
 381             starttime => {
 382                 type => 'string',
 383                 description => "Job Start time.",
 384                 pattern => '\d{1,2}:\d{1,2}',
 385                 typetext => 'HH:MM',
 386                 optional => 1,
 387             },
 388             dow => {
 389                 type => 'string', format => 'pve-day-of-week-list',
 390                 optional => 1,
 391                 requires => 'starttime',
 392                 description => "Day of week selection.",
 393             },
 394             delete => {
 395                 type => 'string', format => 'pve-configid-list',
 396                 description => "A list of settings you want to delete.",
 397                 optional => 1,
 398             },
 399             enabled => {
 400                 type => 'boolean',
 401                 optional => 1,
 402                 description => "Enable or disable the job.",
 403                 default => '1',
 404             },
 405             'repeat-missed' => {
 406                 optional => 1,
 407                 type => 'boolean',
 408                 description => "If true, the job will be run as soon as possible if it was missed".
 409                     " while the scheduler was not running.",
 410                 default => 0,
 411             },
 412             comment => {
 413                 optional => 1,
 414                 type => 'string',
 415                 description => "Description for the Job.",
 416                 maxLength => 512,
 417             },
 418        }),
 419     },
 420     returns => { type => 'null' },
 421     code => sub {
 422         my ($param) = @_;
 423
 424         my $rpcenv = PVE::RPCEnvironment::get();
 425         my $user = $rpcenv->get_user();
 426
 427         assert_param_permission_common($rpcenv, $user, $param);
 428
 429         if (my $pool = $param->{pool}) {
 430             $rpcenv->check_pool_exist($pool);
 431             $rpcenv->check($user, "/pool/$pool", ['VM.Backup']);
 432         }
 433
 434         $schedule_param_check->($param);
 435
 436         my $id = extract_param($param, 'id');
 437         my $delete = extract_param($param, 'delete');
 438         $delete = { map { $_ => 1 } PVE::Tools::split_list($delete) } if $delete;
 439
 440         my $update_job = sub {
 441             my $data = cfs_read_file('vzdump.cron');
 442             my $jobs_data = cfs_read_file('jobs.cfg');
 443
 444             my $jobs = $data->{jobs} || [];
 445
 446             die "no options specified\n" if !scalar(keys $param->%*) && !scalar(keys $delete->%*);
 447
 448             PVE::VZDump::verify_vzdump_parameters($param);
 449             my $opts = PVE::VZDump::JobBase->check_config($id, $param, 0, 1);
 450
 451             # try to find it in old vzdump.cron and convert it to a job
 452             my ($idx) = grep { $jobs->[$_]->{id} eq $id } (0 .. scalar(@$jobs) - 1);
 453
 454             my $job;
 455             if (defined($idx)) {
 456                 $job = splice @$jobs, $idx, 1;
 457                 $job->{schedule} = $convert_to_schedule->($job);
 458                 delete $job->{starttime};
 459                 delete $job->{dow};
 460                 delete $job->{id};
 461                 $job->{type} = 'vzdump';
 462                 $jobs_data->{ids}->{$id} = $job;
 463             } else {
 464                 $job = $jobs_data->{ids}->{$id};
 465                 die "no such vzdump job\n" if !$job || $job->{type} ne 'vzdump';
 466             }
 467
 468             my $deletable = {
 469                 comment => 1,
 470                 'repeat-missed' => 1,
 471             };
 472
 473             for my $k (keys $delete->%*) {
 474                 if (!PVE::VZDump::option_exists($k) && !$deletable->{$k}) {
 475                     raise_param_exc({ delete => "unknown option '$k'" });
 476                 }
 477
 478                 delete $job->{$k};
 479             }
 480
 481             foreach my $k (keys %$param) {
 482                 $job->{$k} = $param->{$k};
 483             }
 484
 485             $job->{all} = 1 if (defined($job->{exclude}) && !defined($job->{pool}));
 486
 487             if (defined($param->{vmid})) {
 488                 delete $job->{all};
 489                 delete $job->{exclude};
 490                 delete $job->{pool};
 491             } elsif ($param->{all}) {
 492                 delete $job->{vmid};
 493                 delete $job->{pool};
 494             } elsif ($job->{pool}) {
 495                 delete $job->{vmid};
 496                 delete $job->{all};
 497                 delete $job->{exclude};
 498             }
 499
 500             PVE::VZDump::verify_vzdump_parameters($job, 1);
 501
 502             if (defined($idx)) {
 503                 cfs_write_file('vzdump.cron', $data);
 504             }
 505             cfs_write_file('jobs.cfg', $jobs_data);
 506
 507             PVE::Jobs::detect_changed_runtime_props($id, 'vzdump', $job);
 508
 509             return;
 510         };
 511         cfs_lock_file('vzdump.cron', undef, sub {
 512             cfs_lock_file('jobs.cfg', undef, $update_job);
 513             die "$@" if ($@);
 514         });
 515         die "$@" if ($@);
 516     }});
 517
 518 __PACKAGE__->register_method({
 519     name => 'get_volume_backup_included',
 520     path => '{id}/included_volumes',
 521     method => 'GET',
 522     protected => 1,
 523     description => "Returns included guests and the backup status of their disks. Optimized to be used in ExtJS tree views.",
 524     permissions => {
 525         check => ['perm', '/', ['Sys.Audit']],
 526     },
 527     parameters => {
 528         additionalProperties => 0,
 529         properties => {
 530             id => $vzdump_job_id_prop
 531         },
 532     },
 533     returns => {
 534         type => 'object',
 535         description => 'Root node of the tree object. Children represent guests, grandchildren represent volumes of that guest.',
 536         properties => {
 537             children => {
 538                 type => 'array',
 539                 items => {
 540                     type => 'object',
 541                     properties => {
 542                         id => {
 543                             type => 'integer',
 544                             description => 'VMID of the guest.',
 545                         },
 546                         name => {
 547                             type => 'string',
 548                             description => 'Name of the guest',
 549                             optional => 1,
 550                         },
 551                         type => {
 552                             type => 'string',
 553                             description => 'Type of the guest, VM, CT or unknown for removed but not purged guests.',
 554                             enum => ['qemu', 'lxc', 'unknown'],
 555                         },
 556                         children => {
 557                             type => 'array',
 558                             optional => 1,
 559                             description => 'The volumes of the guest with the information if they will be included in backups.',
 560                             items => {
 561                                 type => 'object',
 562                                 properties => {
 563                                     id => {
 564                                         type => 'string',
 565                                         description => 'Configuration key of the volume.',
 566                                     },
 567                                     name => {
 568                                         type => 'string',
 569                                         description => 'Name of the volume.',
 570                                     },
 571                                     included => {
 572                                         type => 'boolean',
 573                                         description => 'Whether the volume is included in the backup or not.',
 574                                     },
 575                                     reason => {
 576                                         type => 'string',
 577                                         description => 'The reason why the volume is included (or excluded).',
 578                                     },
 579                                 },
 580                             },
 581                         },
 582                     },
 583                 },
 584             },
 585         },
 586     },
 587     code => sub {
 588         my ($param) = @_;
 589
 590         my $rpcenv = PVE::RPCEnvironment::get();
 591
 592         my $user = $rpcenv->get_user();
 593
 594         my $vzconf = cfs_read_file('vzdump.cron');
 595         my $all_jobs = $vzconf->{jobs} || [];
 596         my $job;
 597         my $rrd = PVE::Cluster::rrd_dump();
 598
 599         for my $j (@$all_jobs) {
 600             if ($j->{id} eq $param->{id}) {
 601                $job = $j;
 602                last;
 603             }
 604         }
 605         if (!$job) {
 606             my $jobs_data = cfs_read_file('jobs.cfg');
 607             my $j = $jobs_data->{ids}->{$param->{id}};
 608             if ($j && $j->{type} eq 'vzdump') {
 609                 $job = $j;
 610             }
 611         }
 612         raise_param_exc({ id => "No such job '$param->{id}'" }) if !$job;
 613
 614         my $vmlist = PVE::Cluster::get_vmlist();
 615
 616         my @job_vmids;
 617
 618         my $included_guests = PVE::VZDump::get_included_guests($job);
 619
 620         for my $node (keys %{$included_guests}) {
 621             my $node_vmids = $included_guests->{$node};
 622             push(@job_vmids, @{$node_vmids});
 623         }
 624
 625         # remove VMIDs to which the user has no permission to not leak infos
 626         # like the guest name
 627         my @allowed_vmids = grep {
 628                 $rpcenv->check($user, "/vms/$_", [ 'VM.Audit' ], 1);
 629         } @job_vmids;
 630
 631         my $result = {
 632             children => [],
 633         };
 634
 635         for my $vmid (@allowed_vmids) {
 636
 637             my $children = [];
 638
 639             # It's possible that a job has VMIDs configured that are not in
 640             # vmlist. This could be because a guest was removed but not purged.
 641             # Since there is no more data available we can only deliver the VMID
 642             # and no volumes.
 643             if (!defined $vmlist->{ids}->{$vmid}) {
 644                 push(@{$result->{children}}, {
 645                     id => int($vmid),
 646                     type => 'unknown',
 647                     leaf => 1,
 648                 });
 649                 next;
 650             }
 651
 652             my $type = $vmlist->{ids}->{$vmid}->{type};
 653             my $node = $vmlist->{ids}->{$vmid}->{node};
 654
 655             my $conf;
 656             my $volumes;
 657             my $name = "";
 658
 659             if ($type eq 'qemu') {
 660                 $conf = PVE::QemuConfig->load_config($vmid, $node);
 661                 $volumes = PVE::QemuConfig->get_backup_volumes($conf);
 662                 $name = $conf->{name};
 663             } elsif ($type eq 'lxc') {
 664                 $conf = PVE::LXC::Config->load_config($vmid, $node);
 665                 $volumes = PVE::LXC::Config->get_backup_volumes($conf);
 666                 $name = $conf->{hostname};
 667             } else {
 668                 die "VMID $vmid is neither Qemu nor LXC guest\n";
 669             }
 670
 671             foreach my $volume (@$volumes) {
 672                 my $disk = {
 673                     # id field must be unique for ExtJS tree view
 674                     id => "$vmid:$volume->{key}",
 675                     name => $volume->{volume_config}->{file} // $volume->{volume_config}->{volume},
 676                     included=> $volume->{included},
 677                     reason => $volume->{reason},
 678                     leaf => 1,
 679                 };
 680                 push(@{$children}, $disk);
 681             }
 682
 683             my $leaf = 0;
 684             # it's possible for a guest to have no volumes configured
 685             $leaf = 1 if !@{$children};
 686
 687             push(@{$result->{children}}, {
 688                     id => int($vmid),
 689                     type => $type,
 690                     name => $name,
 691                     children => $children,
 692                     leaf => $leaf,
 693             });
 694         }
 695
 696         return $result;
 697     }});
 698
 699 1;