src/PVE/CLIHandler.pm

   1 package PVE::CLIHandler;
   2
   3 use strict;
   4 use warnings;
   5 use JSON;
   6
   7 use PVE::SafeSyslog;
   8 use PVE::Exception qw(raise raise_param_exc);
   9 use PVE::RESTHandler;
  10 use PVE::PTY;
  11 use PVE::INotify;
  12 use PVE::CLIFormatter;
  13
  14 use base qw(PVE::RESTHandler);
  15
  16 # $cmddef defines which (sub)commands are available in a specific CLI class.
  17 # A real command is always an array consisting of its class, name, array of
  18 # position fixed (required) parameters and hash of predefined parameters when
  19 # mapping a CLI command t o an API call. Optionally an output method can be
  20 # passed at the end, e.g., for formatting or transformation purpose, and
  21 # a schema of additional properties/arguments which are added to
  22 # the method schema and gets passed to the formatter.
  23 #
  24 # [class, name, fixed_params, API_pre-set params, output_sub ]
  25 #
  26 # In case of so called 'simple commands', the $cmddef can be also just an
  27 # array.
  28 #
  29 # Examples:
  30 # $cmddef = {
  31 #     command => [ 'PVE::API2::Class', 'command', [ 'arg1', 'arg2' ], { node => $nodename } ],
  32 #     do => {
  33 #         this => [ 'PVE::API2::OtherClass', 'method', [ 'arg1' ], undef, sub {
  34 #             my ($res) = @_;
  35 #             print "$res\n";
  36 #         }],
  37 #         that => [ 'PVE::API2::OtherClass', 'subroutine' [] ],
  38 #     },
  39 #     dothat => { alias => 'do that' },
  40 # }
  41 my $cmddef;
  42 my $exename;
  43 my $cli_handler_class;
  44
  45 my $standard_mappings = {
  46     'pve-password' => {
  47         name => 'password',
  48         desc => '<password>',
  49         interactive => 1,
  50         func => sub {
  51             my ($value) = @_;
  52             return $value if $value;
  53             return PVE::PTY::get_confirmed_password();
  54         },
  55     },
  56 };
  57 sub get_standard_mapping {
  58     my ($name, $base) = @_;
  59
  60     my $std = $standard_mappings->{$name};
  61     die "no such standard mapping '$name'\n" if !$std;
  62
  63     my $res = $base || {};
  64
  65     foreach my $opt (keys %$std) {
  66         next if defined($res->{$opt});
  67         $res->{$opt} = $std->{$opt};
  68     }
  69
  70     return $res;
  71 }
  72
  73 my $gen_param_mapping_func = sub {
  74     my ($cli_handler_class) = @_;
  75
  76     my $param_mapping = $cli_handler_class->can('param_mapping');
  77
  78     if (!$param_mapping) {
  79         my $read_password = $cli_handler_class->can('read_password');
  80         my $string_param_mapping = $cli_handler_class->can('string_param_file_mapping');
  81
  82         return $string_param_mapping if !$read_password;
  83
  84         $param_mapping = sub {
  85             my ($name) = @_;
  86
  87             my $password_map = get_standard_mapping('pve-password', {
  88                 func => $read_password
  89             });
  90             my $map = $string_param_mapping ? $string_param_mapping->($name) : [];
  91             return [@$map, $password_map];
  92         };
  93     }
  94
  95     return $param_mapping;
  96 };
  97
  98 my $assert_initialized = sub {
  99     my @caller = caller;
 100     die "$caller[0]:$caller[2] - not initialized\n"
 101         if !($cmddef && $exename && $cli_handler_class);
 102 };
 103
 104 my $abort = sub {
 105     my ($reason, $cmd) = @_;
 106     print_usage_short (\*STDERR, $reason, $cmd);
 107     exit (-1);
 108 };
 109
 110 my $expand_command_name = sub {
 111     my ($def, $cmd) = @_;
 112
 113     return $cmd if exists $def->{$cmd}; # command is already complete
 114
 115     my $is_alias = sub { ref($_[0]) eq 'HASH' && exists($_[0]->{alias}) };
 116     my @expanded = grep { /^\Q$cmd\E/ && !$is_alias->($def->{$_}) } keys %$def;
 117
 118     return $expanded[0] if scalar(@expanded) == 1; # enforce exact match
 119
 120     return undef;
 121 };
 122
 123 my $get_commands = sub {
 124     my $def = shift // die "no command definition passed!";
 125     return [ grep { !(ref($def->{$_}) eq 'HASH' && defined($def->{$_}->{alias})) } sort keys %$def ];
 126 };
 127
 128 my $complete_command_names = sub { $get_commands->($cmddef) };
 129
 130 # traverses the command definition using the $argv array, resolving one level
 131 # of aliases.
 132 # Returns the matching (sub) command and its definition, and argument array for
 133 # this (sub) command and a hash where we marked which (sub) commands got
 134 # expanded (e.g. st => status) while traversing
 135 sub resolve_cmd {
 136     my ($argv, $is_alias) = @_;
 137
 138     my ($def, $cmd) = ($cmddef, $argv);
 139     my $cmdstr = $exename;
 140
 141     if (ref($argv) eq 'ARRAY') {
 142         my $expanded_last_arg;
 143         my $last_arg_id = scalar(@$argv) - 1;
 144
 145         for my $i (0..$last_arg_id) {
 146             $cmd = $expand_command_name->($def, $argv->[$i]);
 147             if (defined($cmd)) {
 148                 # If the argument was expanded (or was already complete) and it
 149                 # is the final argument, tell our caller about it:
 150                 $expanded_last_arg = $cmd if $i == $last_arg_id;
 151             } else {
 152                 # Otherwise continue with the unexpanded version of it.
 153                 $cmd = $argv->[$i];
 154             }
 155             $cmdstr .= " $cmd";
 156             $def = $def->{$cmd};
 157             last if !defined($def);
 158
 159             if (ref($def) eq 'ARRAY') {
 160                 # could expand to a real command, rest of $argv are its arguments
 161                 my $cmd_args = [ @$argv[$i+1..$last_arg_id] ];
 162                 return ($cmd, $def, $cmd_args, $expanded_last_arg, $cmdstr);
 163             }
 164
 165             if (defined($def->{alias})) {
 166                 die "alias loop detected for '$cmd'" if $is_alias; # avoids cycles
 167                 # replace aliased (sub)command with the expanded aliased command
 168                 splice @$argv, $i, 1, split(/ +/, $def->{alias});
 169                 return resolve_cmd($argv, 1);
 170             }
 171         }
 172         # got either a special command (bashcomplete, verifyapi) or an unknown
 173         # cmd, just return first entry as cmd and the rest of $argv as cmd_arg
 174         my $cmd_args = [ @$argv[1..$last_arg_id] ];
 175         return ($argv->[0], $def, $cmd_args, $expanded_last_arg, $cmdstr);
 176     }
 177     return ($cmd, $def, undef, undef, $cmdstr);
 178 }
 179
 180 sub generate_usage_str {
 181     my ($format, $cmd, $indent, $separator, $sortfunc) = @_;
 182
 183     $assert_initialized->();
 184     die 'format required' if !$format;
 185
 186     $sortfunc //= sub { sort keys %{$_[0]} };
 187     $separator //= '';
 188     $indent //= '';
 189
 190     my $param_cb = $gen_param_mapping_func->($cli_handler_class);
 191
 192     my ($subcmd, $def, undef, undef, $cmdstr) = resolve_cmd($cmd);
 193
 194     my $generate;
 195     $generate = sub {
 196         my ($indent, $separator, $def, $prefix) = @_;
 197
 198         my $str = '';
 199         if (ref($def) eq 'HASH') {
 200             my $oldclass = undef;
 201             foreach my $cmd (&$sortfunc($def)) {
 202
 203                 if (ref($def->{$cmd}) eq 'ARRAY') {
 204                     my ($class, $name, $arg_param, $fixed_param, undef, $formatter_properties) = @{$def->{$cmd}};
 205
 206                     $str .= $separator if $oldclass && $oldclass ne $class;
 207                     $str .= $indent;
 208                     $str .= $class->usage_str($name, "$prefix $cmd", $arg_param,
 209                                               $fixed_param, $format, $param_cb, $formatter_properties);
 210                     $oldclass = $class;
 211
 212                 } elsif (defined($def->{$cmd}->{alias}) && ($format eq 'asciidoc')) {
 213
 214                     $str .= "*$prefix $cmd*\n\nAn alias for '$exename $def->{$cmd}->{alias}'.\n\n";
 215
 216                 } else {
 217                     next if $def->{$cmd}->{alias};
 218
 219                     my $substr = $generate->($indent, '', $def->{$cmd}, "$prefix $cmd");
 220                     if ($substr) {
 221                         $substr .= $separator if $substr !~ /\Q$separator\E{2}/;
 222                         $str .= $substr;
 223                     }
 224                 }
 225
 226             }
 227         } else {
 228             my ($class, $name, $arg_param, $fixed_param, undef, $formatter_properties) = @$def;
 229             $abort->("unknown command '$cmd'") if !$class;
 230
 231             $str .= $indent;
 232             $str .= $class->usage_str($name, $prefix, $arg_param, $fixed_param, $format, $param_cb, $formatter_properties);
 233         }
 234         return $str;
 235     };
 236
 237     return $generate->($indent, $separator, $def, $cmdstr);
 238 }
 239
 240 __PACKAGE__->register_method ({
 241     name => 'help',
 242     path => 'help',
 243     method => 'GET',
 244     description => "Get help about specified command.",
 245     parameters => {
 246         additionalProperties => 0,
 247         properties => {
 248             'extra-args' => PVE::JSONSchema::get_standard_option('extra-args', {
 249                 description => 'Shows help for a specific command',
 250                 completion => $complete_command_names,
 251             }),
 252             verbose => {
 253                 description => "Verbose output format.",
 254                 type => 'boolean',
 255                 optional => 1,
 256             },
 257         },
 258     },
 259     returns => { type => 'null' },
 260
 261     code => sub {
 262         my ($param) = @_;
 263
 264         $assert_initialized->();
 265
 266         my $cmd = $param->{'extra-args'};
 267
 268         my $verbose = defined($cmd) && $cmd;
 269         $verbose = $param->{verbose} if defined($param->{verbose});
 270
 271         if (!$cmd) {
 272             if ($verbose) {
 273                 print_usage_verbose();
 274             } else {
 275                 print_usage_short(\*STDOUT);
 276             }
 277             return undef;
 278         }
 279
 280         my $str;
 281         if ($verbose) {
 282             $str = generate_usage_str('full', $cmd, '');
 283         } else {
 284             $str = generate_usage_str('short', $cmd, ' ' x 7);
 285         }
 286         $str =~ s/^\s+//;
 287
 288         if ($verbose) {
 289             print "$str\n";
 290         } else {
 291             print "USAGE: $str\n";
 292         }
 293
 294         return undef;
 295
 296     }});
 297
 298 sub print_simple_asciidoc_synopsis {
 299     $assert_initialized->();
 300
 301     my $synopsis = "*${exename}* `help`\n\n";
 302     $synopsis .= generate_usage_str('asciidoc');
 303
 304     return $synopsis;
 305 }
 306
 307 sub print_asciidoc_synopsis {
 308     $assert_initialized->();
 309
 310     my $synopsis = "";
 311
 312     $synopsis .= "*${exename}* `<COMMAND> [ARGS] [OPTIONS]`\n\n";
 313
 314     $synopsis .= generate_usage_str('asciidoc');
 315
 316     $synopsis .= "\n";
 317
 318     return $synopsis;
 319 }
 320
 321 sub print_usage_verbose {
 322     $assert_initialized->();
 323
 324     print "USAGE: $exename <COMMAND> [ARGS] [OPTIONS]\n\n";
 325
 326     my $str = generate_usage_str('full');
 327
 328     print "$str\n";
 329 }
 330
 331 sub print_usage_short {
 332     my ($fd, $msg, $cmd) = @_;
 333
 334     $assert_initialized->();
 335
 336     print $fd "ERROR: $msg\n" if $msg;
 337     print $fd "USAGE: $exename <COMMAND> [ARGS] [OPTIONS]\n\n";
 338
 339     print {$fd} generate_usage_str('short', $cmd, ' ' x 7, $cmd ? '' : "\n", sub {
 340         my ($h) = @_;
 341         return sort {
 342             if (ref($h->{$a}) eq 'ARRAY' && ref($h->{$b}) eq 'ARRAY') {
 343                 # $a and $b are both real commands order them by their class
 344                 return $h->{$a}->[0] cmp $h->{$b}->[0] || $a cmp $b;
 345             } elsif (ref($h->{$a}) eq 'ARRAY' xor ref($h->{$b}) eq 'ARRAY') {
 346                 # real command and subcommand mixed, put sub commands first
 347                 return ref($h->{$b}) eq 'ARRAY' ? -1 : 1;
 348             } else {
 349                 # both are either from the same class or subcommands
 350                 return $a cmp $b;
 351             }
 352         } keys %$h;
 353     });
 354 }
 355
 356 my $print_bash_completion = sub {
 357     my ($simple_cmd, $bash_command, $cur, $prev) = @_;
 358
 359     my $debug = 0;
 360
 361     return if !(defined($cur) && defined($prev) && defined($bash_command));
 362     return if !defined($ENV{COMP_LINE});
 363     return if !defined($ENV{COMP_POINT});
 364
 365     my $cmdline = substr($ENV{COMP_LINE}, 0, $ENV{COMP_POINT});
 366     print STDERR "\nCMDLINE: $ENV{COMP_LINE}\n" if $debug;
 367
 368     my $args = PVE::Tools::split_args($cmdline);
 369     shift @$args; # no need for program name
 370     my $print_result = sub {
 371         foreach my $p (@_) {
 372             print "$p\n" if $p =~ m/^\Q$cur\E/;
 373         }
 374     };
 375
 376     my ($cmd, $def) = ($simple_cmd, $cmddef);
 377     if (!$simple_cmd) {
 378         ($cmd, $def, $args, my $expanded) = resolve_cmd($args);
 379
 380         if (defined($expanded) && $prev ne $expanded) {
 381             print "$expanded\n";
 382             return;
 383         }
 384
 385         if (ref($def) eq 'HASH') {
 386             &$print_result(@{$get_commands->($def)});
 387             return;
 388         }
 389     }
 390     return if !$def;
 391
 392     my $pos = scalar(@$args) - 1;
 393     $pos += 1 if $cmdline =~ m/\s+$/;
 394     print STDERR "pos: $pos\n" if $debug;
 395     return if $pos < 0;
 396
 397     my $skip_param = {};
 398
 399     my ($class, $name, $arg_param, $uri_param, undef, $formatter_properties) = @$def;
 400     $arg_param //= [];
 401     $uri_param //= {};
 402
 403     $arg_param = [ $arg_param ] if !ref($arg_param);
 404
 405     map { $skip_param->{$_} = 1; } @$arg_param;
 406     map { $skip_param->{$_} = 1; } keys %$uri_param;
 407
 408     my $info = $class->map_method_by_name($name);
 409
 410     my $prop = { %{$info->{parameters}->{properties}} }; # copy
 411     $prop = { %$prop, %$formatter_properties } if $formatter_properties;
 412
 413     my $print_parameter_completion = sub {
 414         my ($pname) = @_;
 415         my $d = $prop->{$pname};
 416         if ($d->{completion}) {
 417             my $vt = ref($d->{completion});
 418             if ($vt eq 'CODE') {
 419                 my $res = $d->{completion}->($cmd, $pname, $cur, $args);
 420                 &$print_result(@$res);
 421             }
 422         } elsif ($d->{type} eq 'boolean') {
 423             &$print_result('0', '1');
 424         } elsif ($d->{enum}) {
 425             &$print_result(@{$d->{enum}});
 426         }
 427     };
 428
 429     # positional arguments
 430     if ($pos < scalar(@$arg_param)) {
 431         my $pname = $arg_param->[$pos];
 432         &$print_parameter_completion($pname);
 433         return;
 434     }
 435
 436     my @option_list = ();
 437     foreach my $key (keys %$prop) {
 438         next if $skip_param->{$key};
 439         push @option_list, "--$key";
 440     }
 441
 442     if ($cur =~ m/^-/) {
 443         &$print_result(@option_list);
 444         return;
 445     }
 446
 447     if ($prev =~ m/^--?(.+)$/ && $prop->{$1}) {
 448         my $pname = $1;
 449         &$print_parameter_completion($pname);
 450         return;
 451     }
 452
 453     &$print_result(@option_list);
 454 };
 455
 456 sub verify_api {
 457     my ($class) = @_;
 458
 459     # simply verify all registered methods
 460     PVE::RESTHandler::validate_method_schemas();
 461 }
 462
 463 my $get_exe_name = sub {
 464     my ($class) = @_;
 465
 466     my $name = $class;
 467     $name =~ s/^.*:://;
 468     $name =~ s/_/-/g;
 469
 470     return $name;
 471 };
 472
 473 sub generate_bash_completions {
 474     my ($class) = @_;
 475
 476     # generate bash completion config
 477
 478     $exename = &$get_exe_name($class);
 479
 480     print <<__EOD__;
 481 # $exename bash completion
 482
 483 # see http://tiswww.case.edu/php/chet/bash/FAQ
 484 # and __ltrim_colon_completions() in /usr/share/bash-completion/bash_completion
 485 # this modifies global var, but I found no better way
 486 COMP_WORDBREAKS=\${COMP_WORDBREAKS//:}
 487
 488 complete -o default -C '$exename bashcomplete' $exename
 489 __EOD__
 490 }
 491
 492 sub generate_zsh_completions {
 493     my ($class) = @_;
 494
 495     # generate zsh completion config
 496
 497     $exename = &$get_exe_name($class);
 498
 499     print <<__EOD__;
 500 #compdef _$exename $exename
 501
 502 function _$exename() {
 503     local cwords line point cmd curr prev
 504     cwords=\${#words[@]}
 505     line=\$words
 506     point=\${#line}
 507     cmd=\${words[1]}
 508     curr=\${words[cwords]}
 509     prev=\${words[cwords-1]}
 510     compadd \$(COMP_CWORD="\$cwords" COMP_LINE="\$line" COMP_POINT="\$point" \\
 511         $exename bashcomplete "\$cmd" "\$curr" "\$prev")
 512 }
 513 __EOD__
 514 }
 515
 516 sub generate_asciidoc_synopsys {
 517     my ($class) = @_;
 518     $class->generate_asciidoc_synopsis();
 519 };
 520
 521 sub generate_asciidoc_synopsis {
 522     my ($class) = @_;
 523
 524     $cli_handler_class = $class;
 525
 526     $exename = &$get_exe_name($class);
 527
 528     no strict 'refs';
 529     my $def = ${"${class}::cmddef"};
 530     $cmddef = $def;
 531
 532     if (ref($def) eq 'ARRAY') {
 533         print_simple_asciidoc_synopsis();
 534     } else {
 535         $cmddef->{help} = [ __PACKAGE__, 'help', ['cmd'] ];
 536
 537         print_asciidoc_synopsis();
 538     }
 539 }
 540
 541 # overwrite this if you want to run/setup things early
 542 sub setup_environment {
 543     my ($class) = @_;
 544
 545     # do nothing by default
 546 }
 547
 548 my $handle_cmd  = sub {
 549     my ($args, $preparefunc, $param_cb) = @_;
 550
 551     $cmddef->{help} = [ __PACKAGE__, 'help', ['extra-args'] ];
 552
 553     my ($cmd, $def, $cmd_args, undef, $cmd_str) = resolve_cmd($args);
 554
 555     $abort->("no command specified") if !$cmd;
 556
 557     # call verifyapi before setup_environment(), don't execute any real code in
 558     # this case
 559     if ($cmd eq 'verifyapi') {
 560         PVE::RESTHandler::validate_method_schemas();
 561         return;
 562     }
 563
 564     $cli_handler_class->setup_environment();
 565
 566     if ($cmd eq 'bashcomplete') {
 567         &$print_bash_completion(undef, @$cmd_args);
 568         return;
 569     }
 570
 571     # checked special commands, if def is still a hash we got an incomplete sub command
 572     $abort->("incomplete command '$cmd_str'", $args) if ref($def) eq 'HASH';
 573
 574     &$preparefunc() if $preparefunc;
 575
 576     my ($class, $name, $arg_param, $uri_param, $outsub, $formatter_properties) = @{$def || []};
 577     $abort->("unknown command '$cmd_str'") if !$class;
 578
 579     my ($res, $formatter_params) = $class->cli_handler(
 580         $cmd_str, $name, $cmd_args, $arg_param, $uri_param, $param_cb, $formatter_properties);
 581
 582     if (defined $outsub) {
 583         my $result_schema = $class->map_method_by_name($name)->{returns};
 584         $outsub->($res, $result_schema, $formatter_params);
 585     }
 586 };
 587
 588 my $handle_simple_cmd = sub {
 589     my ($args, $preparefunc, $param_cb) = @_;
 590
 591     my ($class, $name, $arg_param, $uri_param, $outsub, $formatter_properties) = @{$cmddef};
 592     die "no class specified" if !$class;
 593
 594     if (scalar(@$args) >= 1) {
 595         if ($args->[0] eq 'help') {
 596             my $str = "USAGE: $name help\n";
 597             $str .= generate_usage_str('long');
 598             print STDERR "$str\n\n";
 599             return;
 600         } elsif ($args->[0] eq 'verifyapi') {
 601             PVE::RESTHandler::validate_method_schemas();
 602             return;
 603         }
 604     }
 605
 606     $cli_handler_class->setup_environment();
 607
 608     if (scalar(@$args) >= 1) {
 609         if ($args->[0] eq 'bashcomplete') {
 610             shift @$args;
 611             &$print_bash_completion($name, @$args);
 612             return;
 613         }
 614     }
 615
 616     &$preparefunc() if $preparefunc;
 617
 618     my ($res, $formatter_params) = $class->cli_handler(
 619         $name, $name, \@ARGV, $arg_param, $uri_param, $param_cb, $formatter_properties);
 620
 621     if (defined $outsub) {
 622         my $result_schema = $class->map_method_by_name($name)->{returns};
 623         $outsub->($res, $result_schema, $formatter_params);
 624     }
 625 };
 626
 627 sub run_cli_handler {
 628     my ($class, %params) = @_;
 629
 630     $cli_handler_class = $class;
 631
 632     $ENV{'PATH'} = '/sbin:/bin:/usr/sbin:/usr/bin';
 633
 634     foreach my $key (keys %params) {
 635         next if $key eq 'prepare';
 636         next if $key eq 'no_init'; # not used anymore
 637         next if $key eq 'no_rpcenv'; # not used anymore
 638         die "unknown parameter '$key'";
 639     }
 640
 641     my $preparefunc = $params{prepare};
 642
 643     my $param_cb = $gen_param_mapping_func->($cli_handler_class);
 644
 645     $exename = &$get_exe_name($class);
 646
 647     my $logid = $ENV{PVE_LOG_ID} || $exename;
 648     initlog($logid);
 649
 650     no strict 'refs';
 651     $cmddef = ${"${class}::cmddef"};
 652
 653     if (ref($cmddef) eq 'ARRAY') {
 654         $handle_simple_cmd->(\@ARGV, $preparefunc, $param_cb);
 655     } else {
 656         $handle_cmd->(\@ARGV, $preparefunc, $param_cb);
 657     }
 658
 659     exit 0;
 660 }
 661
 662 1;