src/PVE/API2/Storage/Status.pm

   1 package PVE::API2::Storage::Status;
   2
   3 use strict;
   4 use warnings;
   5
   6 use File::Basename;
   7 use File::Path;
   8 use POSIX qw(ENOENT);
   9
  10 use PVE::Cluster;
  11 use PVE::Exception qw(raise_param_exc);
  12 use PVE::INotify;
  13 use PVE::JSONSchema qw(get_standard_option);
  14 use PVE::RESTHandler;
  15 use PVE::RPCEnvironment;
  16 use PVE::RRD;
  17 use PVE::Tools qw(run_command);
  18
  19 use PVE::API2::Storage::Content;
  20 use PVE::API2::Storage::FileRestore;
  21 use PVE::API2::Storage::PruneBackups;
  22 use PVE::Storage;
  23
  24 use base qw(PVE::RESTHandler);
  25
  26 __PACKAGE__->register_method ({
  27     subclass => "PVE::API2::Storage::PruneBackups",
  28     path => '{storage}/prunebackups',
  29 });
  30
  31 __PACKAGE__->register_method ({
  32     subclass => "PVE::API2::Storage::Content",
  33     # set fragment delimiter (no subdirs) - we need that, because volume
  34     # IDs may contain a slash '/'
  35     fragmentDelimiter => '',
  36     path => '{storage}/content',
  37 });
  38
  39 __PACKAGE__->register_method ({
  40    subclass => "PVE::API2::Storage::FileRestore",
  41    path => '{storage}/file-restore',
  42 });
  43
  44 __PACKAGE__->register_method ({
  45     name => 'index',
  46     path => '',
  47     method => 'GET',
  48     description => "Get status for all datastores.",
  49     permissions => {
  50         description => "Only list entries where you have 'Datastore.Audit' or 'Datastore.AllocateSpace' permissions on '/storage/<storage>'",
  51         user => 'all',
  52     },
  53     protected => 1,
  54     proxyto => 'node',
  55     parameters => {
  56         additionalProperties => 0,
  57         properties => {
  58             node => get_standard_option('pve-node'),
  59             storage => get_standard_option('pve-storage-id', {
  60                 description => "Only list status for  specified storage",
  61                 optional => 1,
  62                 completion => \&PVE::Storage::complete_storage_enabled,
  63             }),
  64             content => {
  65                 description => "Only list stores which support this content type.",
  66                 type => 'string', format => 'pve-storage-content-list',
  67                 optional => 1,
  68                 completion => \&PVE::Storage::complete_content_type,
  69             },
  70             enabled => {
  71                 description => "Only list stores which are enabled (not disabled in config).",
  72                 type => 'boolean',
  73                 optional => 1,
  74                 default => 0,
  75             },
  76             target => get_standard_option('pve-node', {
  77                 description => "If target is different to 'node', we only lists shared storages which " .
  78                     "content is accessible on this 'node' and the specified 'target' node.",
  79                 optional => 1,
  80                 completion => \&PVE::Cluster::get_nodelist,
  81             }),
  82             'format' => {
  83                 description => "Include information about formats",
  84                 type => 'boolean',
  85                 optional => 1,
  86                 default => 0,
  87             },
  88         },
  89     },
  90     returns => {
  91         type => 'array',
  92         items => {
  93             type => "object",
  94             properties => {
  95                 storage => get_standard_option('pve-storage-id'),
  96                 type => {
  97                     description => "Storage type.",
  98                     type => 'string',
  99                 },
 100                 content => {
 101                     description => "Allowed storage content types.",
 102                     type => 'string', format => 'pve-storage-content-list',
 103                 },
 104                 enabled => {
 105                     description => "Set when storage is enabled (not disabled).",
 106                     type => 'boolean',
 107                     optional => 1,
 108                 },
 109                 active => {
 110                     description => "Set when storage is accessible.",
 111                     type => 'boolean',
 112                     optional => 1,
 113                 },
 114                 shared => {
 115                     description => "Shared flag from storage configuration.",
 116                     type => 'boolean',
 117                     optional => 1,
 118                 },
 119                 total => {
 120                     description => "Total storage space in bytes.",
 121                     type => 'integer',
 122                     renderer => 'bytes',
 123                     optional => 1,
 124                 },
 125                 used => {
 126                     description => "Used storage space in bytes.",
 127                     type => 'integer',
 128                     renderer => 'bytes',
 129                     optional => 1,
 130                 },
 131                 avail => {
 132                     description => "Available storage space in bytes.",
 133                     type => 'integer',
 134                     renderer => 'bytes',
 135                     optional => 1,
 136                 },
 137                 used_fraction => {
 138                     description => "Used fraction (used/total).",
 139                     type => 'number',
 140                     renderer => 'fraction_as_percentage',
 141                     optional => 1,
 142                 },
 143             },
 144         },
 145         links => [ { rel => 'child', href => "{storage}" } ],
 146     },
 147     code => sub {
 148         my ($param) = @_;
 149
 150         my $rpcenv = PVE::RPCEnvironment::get();
 151         my $authuser = $rpcenv->get_user();
 152
 153         my $localnode = PVE::INotify::nodename();
 154
 155         my $target = $param->{target};
 156
 157         undef $target if $target && ($target eq $localnode || $target eq 'localhost');
 158
 159         my $cfg = PVE::Storage::config();
 160
 161         my $info = PVE::Storage::storage_info($cfg, $param->{content}, $param->{format});
 162
 163         raise_param_exc({ storage => "No such storage." })
 164             if $param->{storage} && !defined($info->{$param->{storage}});
 165
 166         my $res = {};
 167         my @sids = PVE::Storage::storage_ids($cfg);
 168         foreach my $storeid (@sids) {
 169             my $data = $info->{$storeid};
 170             next if !$data;
 171             my $privs = [ 'Datastore.Audit', 'Datastore.AllocateSpace' ];
 172             next if !$rpcenv->check_any($authuser, "/storage/$storeid", $privs, 1);
 173             next if $param->{storage} && $param->{storage} ne $storeid;
 174
 175             my $scfg = PVE::Storage::storage_config($cfg, $storeid);
 176
 177             next if $param->{enabled} && $scfg->{disable};
 178
 179             if ($target) {
 180                 # check if storage content is accessible on local node and specified target node
 181                 # we use this on the Clone GUI
 182
 183                 next if !$scfg->{shared};
 184                 next if !PVE::Storage::storage_check_node($cfg, $storeid, undef, 1);
 185                 next if !PVE::Storage::storage_check_node($cfg, $storeid, $target, 1);
 186             }
 187
 188             if ($data->{total}) {
 189                 $data->{used_fraction} = ($data->{used} // 0) / $data->{total};
 190             }
 191
 192             $res->{$storeid} = $data;
 193         }
 194
 195         return PVE::RESTHandler::hash_to_array($res, 'storage');
 196     }});
 197
 198 __PACKAGE__->register_method ({
 199     name => 'diridx',
 200     path => '{storage}',
 201     method => 'GET',
 202     description => "",
 203     permissions => {
 204         check => ['perm', '/storage/{storage}', ['Datastore.Audit', 'Datastore.AllocateSpace'], any => 1],
 205     },
 206     parameters => {
 207         additionalProperties => 0,
 208         properties => {
 209             node => get_standard_option('pve-node'),
 210             storage => get_standard_option('pve-storage-id'),
 211         },
 212     },
 213     returns => {
 214         type => 'array',
 215         items => {
 216             type => "object",
 217             properties => {
 218                 subdir => { type => 'string' },
 219             },
 220         },
 221         links => [ { rel => 'child', href => "{subdir}" } ],
 222     },
 223     code => sub {
 224         my ($param) = @_;
 225
 226         my $res = [
 227             { subdir => 'content' },
 228             { subdir => 'download-url' },
 229             { subdir => 'file-restore' },
 230             { subdir => 'import-metadata' },
 231             { subdir => 'prunebackups' },
 232             { subdir => 'rrd' },
 233             { subdir => 'rrddata' },
 234             { subdir => 'status' },
 235             { subdir => 'upload' },
 236         ];
 237
 238         return $res;
 239     }});
 240
 241 __PACKAGE__->register_method ({
 242     name => 'read_status',
 243     path => '{storage}/status',
 244     method => 'GET',
 245     description => "Read storage status.",
 246     permissions => {
 247         check => ['perm', '/storage/{storage}', ['Datastore.Audit', 'Datastore.AllocateSpace'], any => 1],
 248     },
 249     protected => 1,
 250     proxyto => 'node',
 251     parameters => {
 252         additionalProperties => 0,
 253         properties => {
 254             node => get_standard_option('pve-node'),
 255             storage => get_standard_option('pve-storage-id'),
 256         },
 257     },
 258     returns => {
 259         type => "object",
 260         properties => {},
 261     },
 262     code => sub {
 263         my ($param) = @_;
 264
 265         my $cfg = PVE::Storage::config();
 266
 267         my $info = PVE::Storage::storage_info($cfg, $param->{content});
 268
 269         my $data = $info->{$param->{storage}};
 270
 271         raise_param_exc({ storage => "No such storage." })
 272             if !defined($data);
 273
 274         return $data;
 275     }});
 276
 277 __PACKAGE__->register_method ({
 278     name => 'rrd',
 279     path => '{storage}/rrd',
 280     method => 'GET',
 281     description => "Read storage RRD statistics (returns PNG).",
 282     permissions => {
 283         check => ['perm', '/storage/{storage}', ['Datastore.Audit', 'Datastore.AllocateSpace'], any => 1],
 284     },
 285     protected => 1,
 286     proxyto => 'node',
 287     parameters => {
 288         additionalProperties => 0,
 289         properties => {
 290             node => get_standard_option('pve-node'),
 291             storage => get_standard_option('pve-storage-id'),
 292             timeframe => {
 293                 description => "Specify the time frame you are interested in.",
 294                 type => 'string',
 295                 enum => [ 'hour', 'day', 'week', 'month', 'year' ],
 296             },
 297             ds => {
 298                 description => "The list of datasources you want to display.",
 299                 type => 'string', format => 'pve-configid-list',
 300             },
 301             cf => {
 302                 description => "The RRD consolidation function",
 303                 type => 'string',
 304                 enum => [ 'AVERAGE', 'MAX' ],
 305                 optional => 1,
 306             },
 307         },
 308     },
 309     returns => {
 310         type => "object",
 311         properties => {
 312             filename => { type => 'string' },
 313         },
 314     },
 315     code => sub {
 316         my ($param) = @_;
 317
 318         return PVE::RRD::create_rrd_graph(
 319             "pve2-storage/$param->{node}/$param->{storage}",
 320             $param->{timeframe}, $param->{ds}, $param->{cf});
 321     }});
 322
 323 __PACKAGE__->register_method ({
 324     name => 'rrddata',
 325     path => '{storage}/rrddata',
 326     method => 'GET',
 327     description => "Read storage RRD statistics.",
 328     permissions => {
 329         check => ['perm', '/storage/{storage}', ['Datastore.Audit', 'Datastore.AllocateSpace'], any => 1],
 330     },
 331     protected => 1,
 332     proxyto => 'node',
 333     parameters => {
 334         additionalProperties => 0,
 335         properties => {
 336             node => get_standard_option('pve-node'),
 337             storage => get_standard_option('pve-storage-id'),
 338             timeframe => {
 339                 description => "Specify the time frame you are interested in.",
 340                 type => 'string',
 341                 enum => [ 'hour', 'day', 'week', 'month', 'year' ],
 342             },
 343             cf => {
 344                 description => "The RRD consolidation function",
 345                 type => 'string',
 346                 enum => [ 'AVERAGE', 'MAX' ],
 347                 optional => 1,
 348             },
 349         },
 350     },
 351     returns => {
 352         type => "array",
 353         items => {
 354             type => "object",
 355             properties => {},
 356         },
 357     },
 358     code => sub {
 359         my ($param) = @_;
 360
 361         return PVE::RRD::create_rrd_data(
 362             "pve2-storage/$param->{node}/$param->{storage}",
 363             $param->{timeframe}, $param->{cf});
 364     }});
 365
 366 # makes no sense for big images and backup files (because it
 367 # create a copy of the file).
 368 __PACKAGE__->register_method ({
 369     name => 'upload',
 370     path => '{storage}/upload',
 371     method => 'POST',
 372     description => "Upload templates and ISO images.",
 373     permissions => {
 374         check => ['perm', '/storage/{storage}', ['Datastore.AllocateTemplate']],
 375     },
 376     protected => 1,
 377     parameters => {
 378         additionalProperties => 0,
 379         properties => {
 380             node => get_standard_option('pve-node'),
 381             storage => get_standard_option('pve-storage-id'),
 382             content => {
 383                 description => "Content type.",
 384                 type => 'string', format => 'pve-storage-content',
 385                 enum => ['iso', 'vztmpl'],
 386             },
 387             filename => {
 388                 description => "The name of the file to create. Caution: This will be normalized!",
 389                 maxLength => 255,
 390                 type => 'string',
 391             },
 392             checksum => {
 393                 description => "The expected checksum of the file.",
 394                 type => 'string',
 395                 requires => 'checksum-algorithm',
 396                 optional => 1,
 397             },
 398             'checksum-algorithm' => {
 399                 description => "The algorithm to calculate the checksum of the file.",
 400                 type => 'string',
 401                 enum => ['md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512'],
 402                 requires => 'checksum',
 403                 optional => 1,
 404             },
 405             tmpfilename => {
 406                 description => "The source file name. This parameter is usually set by the REST handler. You can only overwrite it when connecting to the trusted port on localhost.",
 407                 type => 'string',
 408                 optional => 1,
 409                 pattern => '/var/tmp/pveupload-[0-9a-f]+',
 410             },
 411         },
 412     },
 413     returns => { type => "string" },
 414     code => sub {
 415         my ($param) = @_;
 416
 417         my $rpcenv = PVE::RPCEnvironment::get();
 418
 419         my $user = $rpcenv->get_user();
 420
 421         my $cfg = PVE::Storage::config();
 422
 423         my $node = $param->{node};
 424         my $scfg = PVE::Storage::storage_check_enabled($cfg, $param->{storage}, $node);
 425
 426         die "can't upload to storage type '$scfg->{type}'\n"
 427             if !defined($scfg->{path});
 428
 429         my $content = $param->{content};
 430
 431         my $tmpfilename = $param->{tmpfilename};
 432         die "missing temporary file name\n" if !$tmpfilename;
 433
 434         my $size = -s $tmpfilename;
 435         die "temporary file '$tmpfilename' does not exist\n" if !defined($size);
 436
 437         my $filename = PVE::Storage::normalize_content_filename($param->{filename});
 438
 439         my $path;
 440
 441         if ($content eq 'iso') {
 442             if ($filename !~ m![^/]+$PVE::Storage::ISO_EXT_RE_0$!) {
 443                 raise_param_exc({ filename => "wrong file extension" });
 444             }
 445             $path = PVE::Storage::get_iso_dir($cfg, $param->{storage});
 446         } elsif ($content eq 'vztmpl') {
 447             if ($filename !~ m![^/]+$PVE::Storage::VZTMPL_EXT_RE_1$!) {
 448                 raise_param_exc({ filename => "wrong file extension" });
 449             }
 450             $path = PVE::Storage::get_vztmpl_dir($cfg, $param->{storage});
 451         } else {
 452             raise_param_exc({ content => "upload content type '$content' not allowed" });
 453         }
 454
 455         die "storage '$param->{storage}' does not support '$content' content\n"
 456             if !$scfg->{content}->{$content};
 457
 458         my $dest = "$path/$filename";
 459         my $dirname = dirname($dest);
 460
 461         # best effort to match apl_download behaviour
 462         chmod 0644, $tmpfilename;
 463
 464         my $err_cleanup = sub { unlink $dest; die "cleanup failed: $!\n" if $! && $! != ENOENT };
 465
 466         my $cmd;
 467         if ($node ne 'localhost' && $node ne PVE::INotify::nodename()) {
 468             my $remip = PVE::Cluster::remote_node_ip($node);
 469
 470             my @ssh_options = ('-o', 'BatchMode=yes');
 471
 472             my @remcmd = ('/usr/bin/ssh', @ssh_options, $remip, '--');
 473
 474             eval { # activate remote storage
 475                 run_command([@remcmd, '/usr/sbin/pvesm', 'status', '--storage', $param->{storage}]);
 476             };
 477             die "can't activate storage '$param->{storage}' on node '$node': $@\n" if $@;
 478
 479             run_command(
 480                 [@remcmd, '/bin/mkdir', '-p', '--', PVE::Tools::shell_quote($dirname)],
 481                 errmsg => "mkdir failed",
 482             );
 483
 484             $cmd = ['/usr/bin/scp', @ssh_options, '-p', '--', $tmpfilename, "[$remip]:" . PVE::Tools::shell_quote($dest)];
 485
 486             $err_cleanup = sub { run_command([@remcmd, 'rm', '-f', '--', $dest]) };
 487         } else {
 488             PVE::Storage::activate_storage($cfg, $param->{storage});
 489             File::Path::make_path($dirname);
 490             $cmd = ['cp', '--', $tmpfilename, $dest];
 491         }
 492
 493         # NOTE: we simply overwrite the destination file if it already exists
 494         my $worker = sub {
 495             my $upid = shift;
 496
 497             print "starting file import from: $tmpfilename\n";
 498
 499             eval {
 500                 my ($checksum, $checksum_algorithm) = $param->@{'checksum', 'checksum-algorithm'};
 501                 if ($checksum_algorithm) {
 502                     print "calculating checksum...";
 503
 504                     my $checksum_got = PVE::Tools::get_file_hash($checksum_algorithm, $tmpfilename);
 505
 506                     if (lc($checksum_got) eq lc($checksum)) {
 507                         print "OK, checksum verified\n";
 508                     } else {
 509                         print "\n";  # the front end expects the error to reside at the last line without any noise
 510                         die "checksum mismatch: got '$checksum_got' != expect '$checksum'\n";
 511                     }
 512                 }
 513             };
 514             if (my $err = $@) {
 515                 # unlinks only the temporary file from the http server
 516                 unlink $tmpfilename;
 517                 warn "unable to clean up temporory file '$tmpfilename' - $!\n"
 518                     if $! && $! != ENOENT;
 519                 die $err;
 520             }
 521
 522             print "target node: $node\n";
 523             print "target file: $dest\n";
 524             print "file size is: $size\n";
 525             print "command: " . join(' ', @$cmd) . "\n";
 526
 527             eval { run_command($cmd, errmsg => 'import failed'); };
 528
 529             unlink $tmpfilename; # the temporary file got only uploaded locally, no need to rm remote
 530             warn "unable to clean up temporary file '$tmpfilename' - $!\n" if $! && $! != ENOENT;
 531
 532             if (my $err = $@) {
 533                 eval { $err_cleanup->() };
 534                 warn "$@" if $@;
 535                 die $err;
 536             }
 537             print "finished file import successfully\n";
 538         };
 539
 540         return $rpcenv->fork_worker('imgcopy', undef, $user, $worker);
 541    }});
 542
 543 __PACKAGE__->register_method({
 544     name => 'download_url',
 545     path => '{storage}/download-url',
 546     method => 'POST',
 547     description => "Download templates and ISO images by using an URL.",
 548     proxyto => 'node',
 549     permissions => {
 550         description => 'Requires allocation access on the storage and as this allows one to probe'
 551             .' the (local!) host network indirectly it also requires one of Sys.Modify on / (for'
 552             .' backwards compatibility) or the newer Sys.AccessNetwork privilege on the node.',
 553         check => [ 'and',
 554             ['perm', '/storage/{storage}', [ 'Datastore.AllocateTemplate' ]],
 555             [ 'or',
 556                 ['perm', '/', [ 'Sys.Audit', 'Sys.Modify' ]],
 557                 ['perm', '/nodes/{node}', [ 'Sys.AccessNetwork' ]],
 558             ],
 559         ],
 560     },
 561     protected => 1,
 562     parameters => {
 563         additionalProperties => 0,
 564         properties => {
 565             node => get_standard_option('pve-node'),
 566             storage => get_standard_option('pve-storage-id'),
 567             url => {
 568                 description => "The URL to download the file from.",
 569                 type => 'string',
 570                 pattern => 'https?://.*',
 571             },
 572             content => {
 573                 description => "Content type.", # TODO: could be optional & detected in most cases
 574                 type => 'string', format => 'pve-storage-content',
 575                 enum => ['iso', 'vztmpl'],
 576             },
 577             filename => {
 578                 description => "The name of the file to create. Caution: This will be normalized!",
 579                 maxLength => 255,
 580                 type => 'string',
 581             },
 582             checksum => {
 583                 description => "The expected checksum of the file.",
 584                 type => 'string',
 585                 requires => 'checksum-algorithm',
 586                 optional => 1,
 587             },
 588             compression => {
 589                 description =>
 590                     "Decompress the downloaded file using the specified compression algorithm.",
 591                 type => 'string',
 592                 enum => $PVE::Storage::Plugin::KNOWN_COMPRESSION_FORMATS,
 593                 optional => 1,
 594             },
 595             'checksum-algorithm' => {
 596                 description => "The algorithm to calculate the checksum of the file.",
 597                 type => 'string',
 598                 enum => ['md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512'],
 599                 requires => 'checksum',
 600                 optional => 1,
 601             },
 602             'verify-certificates' => {
 603                 description => "If false, no SSL/TLS certificates will be verified.",
 604                 type => 'boolean',
 605                 optional => 1,
 606                 default => 1,
 607             },
 608         },
 609     },
 610     returns => {
 611         type => "string"
 612     },
 613     code => sub {
 614         my ($param) = @_;
 615
 616         my $rpcenv = PVE::RPCEnvironment::get();
 617         my $user = $rpcenv->get_user();
 618
 619         my $cfg = PVE::Storage::config();
 620
 621         my ($node, $storage, $compression) = $param->@{qw(node storage compression)};
 622         my $scfg = PVE::Storage::storage_check_enabled($cfg, $storage, $node);
 623
 624         die "can't upload to storage type '$scfg->{type}', not a file based storage!\n"
 625             if !defined($scfg->{path});
 626
 627         my ($content, $url) = $param->@{'content', 'url'};
 628
 629         die "storage '$storage' is not configured for content-type '$content'\n"
 630             if !$scfg->{content}->{$content};
 631
 632         my $filename = PVE::Storage::normalize_content_filename($param->{filename});
 633
 634         my $path;
 635         if ($content eq 'iso') {
 636             if ($filename !~ m![^/]+$PVE::Storage::ISO_EXT_RE_0$!) {
 637                 raise_param_exc({ filename => "wrong file extension" });
 638             }
 639             $path = PVE::Storage::get_iso_dir($cfg, $storage);
 640         } elsif ($content eq 'vztmpl') {
 641             if ($filename !~ m![^/]+$PVE::Storage::VZTMPL_EXT_RE_1$!) {
 642                 raise_param_exc({ filename => "wrong file extension" });
 643             }
 644             $path = PVE::Storage::get_vztmpl_dir($cfg, $storage);
 645         } else {
 646             raise_param_exc({ content => "upload content-type '$content' is not allowed" });
 647         }
 648
 649         PVE::Storage::activate_storage($cfg, $storage);
 650         File::Path::make_path($path);
 651
 652         my $dccfg = PVE::Cluster::cfs_read_file('datacenter.cfg');
 653         my $opts = {
 654             hash_required => 0,
 655             verify_certificates => $param->{'verify-certificates'} // 1,
 656             http_proxy => $dccfg->{http_proxy},
 657         };
 658
 659         my ($checksum, $checksum_algorithm) = $param->@{'checksum', 'checksum-algorithm'};
 660         if ($checksum) {
 661             $opts->{"${checksum_algorithm}sum"} = $checksum;
 662             $opts->{hash_required} = 1;
 663         }
 664
 665         my $worker = sub {
 666             if ($compression) {
 667                 die "decompression not supported for $content\n" if $content ne 'iso';
 668                 my $info = PVE::Storage::decompressor_info('iso', $compression);
 669                 die "no decompression method found\n" if !$info->{decompressor};
 670                 $opts->{decompression_command} = $info->{decompressor};
 671             }
 672             PVE::Tools::download_file_from_url("$path/$filename", $url, $opts);
 673         };
 674
 675         my $worker_id = PVE::Tools::encode_text($filename); # must not pass : or the like as w-ID
 676
 677         return $rpcenv->fork_worker('download', $worker_id, $user, $worker);
 678     }});
 679
 680 __PACKAGE__->register_method({
 681     name => 'get_import_metadata',
 682     path => '{storage}/import-metadata',
 683     method => 'GET',
 684     description =>
 685         "Get the base parameters for creating a guest which imports data from a foreign importable"
 686         ." guest, like an ESXi VM",
 687     proxyto => 'node',
 688     permissions => {
 689         description => "You need read access for the volume.",
 690         user => 'all',
 691     },
 692     protected => 1,
 693     parameters => {
 694         additionalProperties => 0,
 695         properties => {
 696             node => get_standard_option('pve-node'),
 697             storage => get_standard_option('pve-storage-id'),
 698             volume => {
 699                 description => "Volume identifier for the guest archive/entry.",
 700                 type => 'string',
 701             },
 702         },
 703     },
 704     returns => {
 705         type => "object",
 706         description => 'Information about how to import a guest.',
 707         additionalProperties => 0,
 708         properties => {
 709             type => {
 710                 type => 'string',
 711                 enum => [ 'vm' ],
 712                 description => 'The type of guest this is going to produce.',
 713             },
 714             source => {
 715                 type => 'string',
 716                 enum => [ 'esxi' ],
 717                 description => 'The type of the import-source of this guest volume.',
 718             },
 719             'create-args' => {
 720                 type => 'object',
 721                 additionalProperties => 1,
 722                 description => 'Parameters which can be used in a call to create a VM or container.',
 723             },
 724             'disks' => {
 725                 type => 'object',
 726                 additionalProperties => 1,
 727                 optional => 1,
 728                 description => 'Recognised disk volumes as `$bus$id` => `$storeid:$path` map.',
 729             },
 730             'net' => {
 731                 type => 'object',
 732                 additionalProperties => 1,
 733                 optional => 1,
 734                 description => 'Recognised network interfaces as `net$id` => { ...params } object.',
 735             },
 736             'warnings' => {
 737                 type => 'array',
 738                 description => 'List of known issues that can affect the import of a guest.'
 739                     .' Note that lack of warning does not imply that there cannot be any problems.',
 740                 optional => 1,
 741                 items => {
 742                     type => "object",
 743                     additionalProperties => 1,
 744                     properties => {
 745                         'type' => {
 746                             description => 'What this warning is about.',
 747                             enum => [
 748                                 'cdrom-image-ignored',
 749                                 'guest-is-running',
 750                                 'nvme-unsupported',
 751                                 'ovmf-with-lsi-unsupported',
 752                                 'serial-port-socket-only',
 753                             ],
 754                             type => 'string',
 755                         },
 756                         'key' => {
 757                             description => 'Related subject (config) key of warning.',
 758                             optional => 1,
 759                             type => 'string',
 760                         },
 761                         'value' => {
 762                             description => 'Related subject (config) value of warning.',
 763                             optional => 1,
 764                             type => 'string',
 765                         },
 766                     },
 767                 },
 768             },
 769         },
 770     },
 771     code => sub {
 772         my ($param) = @_;
 773
 774         my $rpcenv = PVE::RPCEnvironment::get();
 775         my $authuser = $rpcenv->get_user();
 776
 777         my ($storeid, $volume) = $param->@{qw(storage volume)};
 778         my $volid = "$storeid:$volume";
 779
 780         my $cfg = PVE::Storage::config();
 781
 782         PVE::Storage::check_volume_access($rpcenv, $authuser, $cfg, undef, $volid);
 783
 784         return PVE::Tools::run_with_timeout(30, sub {
 785             my $import = PVE::Storage::get_import_metadata($cfg, $volid);
 786             return $import->get_create_args();
 787         });
 788     }});
 789
 790 1;