OpenVZ::Vzctl - Call OpenVZ vzctl command from your program
This document describes v0.01 of OpenVZ::Vzctl - released April 17, 2012 as part of OpenVZ.
use OpenVZ::Vzctl; #XXX: need to add more examples
This program is a simple (or not so simple in some cases) wrapper around the 'vzctl' program. It will do some basic verification on options and parameters but it will not (currently) do sanity checks on the values.
All of the commands for vzctl are implemented and all of the options for each command is provided for, but some commands and options I don't use so I'm not sure how to test them. Tests are welcome.
If you want to know what commands and options are available read vzctls man page. I followed that in creating this module.
vzctl
vzctl is used to call execute with vzctl as the specific command.
execute
vzctl expects a hashref with the required keys subcommand and ctid and does NOT check the validity of any remaining keys.
subcommand
ctid
A flag key is optional and accepts quiet and verbose.
flag
quiet
verbose
An example of a valid call would be
my $result = vzctl({ subcommand => 'set', 'ctid' => 101, ipadd => '1.2.3.4', save => undef });
In this case, set and 101 would be validated, but 1.2.3.4 and the value for save would just be passed along to execute as is.
set
101
1.2.3.4
save
The undef value in save is a hint to vzctl that the save parameter should be passed as a switch (i.e., --save instead of --save undef).
undef
When a value is an arrayref, e.g., ipadd => [qw( 1.2.3.4 2.3.4.5 )]. vzctl will send the same parameter multiple times. The previous example would become '--ipadd 1.2.3.4 --ipadd 2.3.4.5'.
You're probably better off if you use the functions designed for a specific command unless you know what you're doing.
subcommand_specs expects a list. The first element will be checked against a list of known subcommands for vzctl.
subcommand_specs
If the first element is a known subcommand a predefined hashref will be instantiated. Any following elements will be treated as additional specification names to be included. Duplicates will be silently ignored. If an element is preceded by a dash (-), that element will be removed from the hashref.
If the first element is not a known subcommand a hashref will be created with the specification names provided, including the first element. Using a dash makes no sense in this context, but will not cause any problems.
subcommand_specs will return the hashref described previously that can be used in the spec option of Params::Validate's validate_with function. E.g., the call
spec
Params::Validate
validate_with
my $spec = subcommand_specs( 'stop' );
will return a hashref into $spec that looks like
$spec
$spec = { flag => { regex => qr/^quiet|verbose/, optional => 1 }, ctid => { callback => { 'validate ctid' => \&_validate_ctid } }, }
while the call
my $spec = subcommand_specs( 'ctid' );
would yield
$spec = { ctid => { callback => { 'validate ctid' => \&_validate_ctid } } };
If a parameter is surrounded with square brackets ( [] ) the parameter is made optional.
Returns a list of known vzctl commands
Given a command, returns a list of known options
Returns a list of known capabilities for the vzctl set capability option.
vzctl set capability
Returns a list of known iptables modules for the vzctl set iptables option.
vzctl set iptables
Returns a list of known features for the vzctl set features option.
vzctl set features
chkpnt expects a hash reference with the following keys and values.
chkpnt
Can be either a CTID or name. The command vzlist -Ho name,ctid value is used to determine if value is a valid identifier.
vzlist -Ho name,ctid value
value
Expects a scalar that looks like a file but does not check if it's possible to write to the specified file. Regexp::Common's URI regex is used to determine what looks like a file.
URI
See the vzctl manpage for information on the chkpnt command.
create expects a hash reference with the following keys and values.
create
See chkpnt for details.
Expects a scalar, but doesn't check validity of value.
Expects a scalar or a reference to an array. Regexp::Common's net IPv4 regex is used to determine if the values are valid looking ips.
net IPv4
See the vzctl manpage for information on the create command.
destroy expects a hash reference with the following keys and values.
destroy
See the vzctl manpage for information on the destroy command.
enter expects a hash reference with the following keys and values.
enter
Expects a scalar or reference to an array but doesn't check for the validity of the command.
See the vzctl manpage for information on the enter command.
exec expects a hash reference with the following keys and values.
exec
Expects a scalar or a reference to an array but doesn't check for the validity of the command.
See the vzctl manpage for information on the exec command.
exec2 expects a hash reference with the following keys and values.
exec2
See the vzctl manpage for information on the exec2 command.
mount expects a hash reference with the following keys and values.
mount
See the vzctl manpage for information on the mount command.
quotainit expects a hash reference with the following keys and values.
quotainit
See the vzctl manpage for information on the quotainit command.
quotaoff expects a hash reference with the following keys and values.
quotaoff
See the vzctl manpage for information on the quotaoff command.
quotaon expects a hash reference with the following keys and values.
quotaon
See the vzctl manpage for information on the quotaon command.
restart expects a hash reference with the following keys and values.
restart
See the vzctl manpage for information on the restart command.
restore expects a hash reference with the following keys and values.
restore
Checks if the file exists, but does not check for validity of file format.
See the vzctl manpage for information on the restore command.
runscript expects a hash reference with the following keys and values.
runscript
Expects a scalar or a reference to an array but doesn't check for the validity of the script.
See the vzctl manpage for information on the runscript command.
set expects a hash reference with the following keys and values.
Expects a scalar. No other validation is performed.
Expects an integer followed by an optional 'g', 'm', 'k' or 'p', followed optionally by a colon and an integer and an optional 'g', 'm', 'k' or 'p'. E.g., 5M or 5M:15M.
Expects an integer.
Expects one of the following capabilities
chown dac_override dac_read_search fowner fsetid ipc_lock ipc_owner kill lease linux_immutable mknod net_admin net_bind_service net_broadcast net_raw setgid setpcap setuid setveid sys_admin sys_boot sys_chroot sys_module sys_nice sys_pacct sys_ptrace sys_rawio sys_resource sys_time sys_tty_config ve_admin
joined with either 'on' or 'off' with a colon. E.g., 'chown:on'.
Expects either a comma separated list of integers or the word 'all'.
Expects a device that matches the regex
/^(?:(?:(?:b|c):\d+:\d+)|all:(?:r?w?))|none$/
No other validation is performed.
XXX Better explanation needed here.
Expects one of the following features
sysfs nfs sit ipip ppp ipgre bridge nfsd
followed by a colon and either 'on' or 'off'.
Expects either undef or the empty string.
Expects a single integer from 0 to 7.
Expects either an array reference or a space separated list of ips to be added or deleted. Regexp::Common's net IPv4 regex is used to determine if the ips look valid. No other validation is performed.
ipdel also accepts 'all' to delete all ips.
ipdel
Expects either an array reference or space separated list of one or more of the following
ip_conntrack ip_conntrack_ftp ip_conntrack_irc ip_nat_ftp ip_nat_irc iptable_filter iptable_mangle iptable_nat ipt_conntrack ipt_helper ipt_length ipt_limit ipt_LOG ipt_multiport ipt_owner ipt_recent ipt_REDIRECT ipt_REJECT ipt_state ipt_tcpmss ipt_TCPMSS ipt_tos ipt_TOS ipt_ttl xt_mac
Expects either 'yes' or 'no'.
Expects either 'restart' or 'ignore'.
Expects two strings separated by a colon. No other validation is performed on the value.
See the vzctl manpage for information on the set command.
start expects a hash reference with the following keys and values.
start
See the vzctl manpage for information on the start command.
status expects a hash reference with the following keys and values.
status
See the vzctl manpage for information on the status command.
stop expects a hash reference with the following keys and values.
stop
See the vzctl manpage for information on the stop command.
umount expects a hash reference with the following keys and values.
umount
See the vzctl manpage for information on the umount command.
See perlmodinstall for information and options on installing Perl modules.
Please see those modules/websites for more information related to this module.
OpenVZ
Alan Young <harleypig@gmail.com>
This software is copyright (c) 2012 by Alan Young.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
To install OpenVZ, copy and paste the appropriate command in to your terminal.
cpanm
cpanm OpenVZ
CPAN shell
perl -MCPAN -e shell install OpenVZ
For more information on module installation, please visit the detailed CPAN module installation guide.