As I’ve been getting more and more familiar with the VI Perl Toolkit over the last couple of weeks I’ve discovered that the perl modules created and provided by VMware have some options and routines that are not discussed in the programming guide. This is my attempt to document the ones that I have found useful and you may be interested in.
There are some additional helper routines that can be found in the perl modules (the files that end in .pm) provided by the Toolkit, and the VMware employee(s) who have written them have done a pretty good job of documenting them in the code. Of special note (I may add them to this post at a later date) are the HostUtil and VMUtil modules, which have routines that streamline some of the more common operations (getting host and VM views, migrating VMs, etc).
Without futher ado…
Prerequesites
If you’re a perl programmer, this isn’t for you. If you aren’t, then…
To use these functions/subroutines you must include the module(s). For the Opts module, it is included when you use VIRuntime (or VIM25Runtime). For VIExt, you must include it expressly.
1 2 |
use VMware::VIRuntime; # includes VICommon and VILib use VMware::VIExt; |
Assertions
The provided assertion is checked, and if it fails the usage message is printed.
Opts::assert_usage( assert_condition, fail_message );
1 |
Opts::assert_usage(defined(Opts::get_option('required_1')), "required_1is required"); |
Option Alias (aliai?)
When adding user specified options to a VI Perl script (using Opts::add_options), they are generally passed in the following manner:
1 2 3 4 5 6 7 8 9 10 |
my %opts = ( 'option_name' => { alias => "O", type => "=s", help => "some help text", required => 0 } ); Opts::add_options(%opts); |
The “alias” option is the short name for the option. With the above example, you could provide the option as --option_name value
or -O value
.
Unnamed parameter
Many of the VMware provided scripts (the vswitch scripts come to mind) have a parameter specified at the end of the line that is not preceded by a --param_name
specifier. This is defined as _default_
, and can be retrieved using that name. If you provide _default_
in the options hash passed to Opts::add_options
the help will be provided when the usage message is written.
Example:
1 2 |
# command passed: script_name.pl --server your.server some_value print Opts::get_option('_default_'); # prints "some_value" |
Custom validation
By passing subroutines to Opts::validate()
you can do your own validation of options passed validation. If they do not, then the script exits in the normal way (print usage message). Multiple subroutines can be passed as additional arguments.
Opts::validate( string sub_routine_name, string ..., ... );
Example:
1 2 3 4 5 6 7 8 9 10 |
# if my_validate returns false (or 0) the script will exit and print the usage message Opts::validate(&my_validate); sub my_validate { if (defined(Opts::get_option('something_required')) { return 1; } else { return 0; } } |
Setting an Option’s value
Simply sets the value of an option to the value specified. The option must be a valid option (a predefined option such as --server
or a user created option via Opts::add_options
), it can not be “created” by this operation.
1 |
Opts::set_option('option_name', 'option_value'); |
Get a host view easily
Using the --vihost
option, get_host_view
retrieves the host view of an ESX host if you are connected to VC or the host directly. If required_host is specified, it will exit if --vihost
is not specified on the command line.
VIExt::get_host_view( bool required_host );
Example:
1 |
my $host = VIExt::get_host_view( 1 ); |
Fail
Shows a failure/error message and gracefully ends the script (disconnects and exits with code "1");
VIExt::fail( string message );
Example:
1 |
VIExt::fail("Unable to find host view"); |
Get common Managed-Object-Reference (MOR) Views
Get the file manager MOR
1 |
VIExt::get_file_manager(); |
Get the virtual disk manager MOR
1 |
VIExt::get_virtual_disk_manager(); |
Nice Sulli. Good info.
Thanks 🙂
…and I don’t even like perl (ok, maybe a little).