/ 
OpenVZ-0.01
River stage zero No dependents
/ OpenVZ::Vzctl

NAME

OpenVZ::Vzctl - Call OpenVZ vzctl command from your program

VERSION

This document describes v0.01 of OpenVZ::Vzctl - released April 17, 2012 as part of OpenVZ.

SYNOPSIS

use OpenVZ::Vzctl;

#XXX: need to add more examples

DESCRIPTION

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.

NOTE

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.

FUNCTIONS

vzctl

vzctl is used to call execute with vzctl as the specific command.

vzctl expects a hashref with the required keys subcommand and ctid and does NOT check the validity of any remaining keys.

A flag key is optional and accepts quiet and 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.

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).

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

subcommand_specs expects a list. The first element will be checked against a list of known subcommands for vzctl.

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

my $spec = subcommand_specs( 'stop' );

will return a hashref into $spec that looks like

$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.

known_commands

Returns a list of known vzctl commands

known_options

Given a command, returns a list of known options

capabilities

Returns a list of known capabilities for the vzctl set capability option.

iptables_modules

Returns a list of known iptables modules for the vzctl set iptables option.

features

Returns a list of known features for the vzctl set features option.

VZCTL COMMANDS

chkpnt

chkpnt expects a hash reference with the following keys and values.

ctid (required)

Can be either a CTID or name. The command vzlist -Ho name,ctid value is used to determine if value is a valid identifier.

create_dumpfile (optional)

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.

See the vzctl manpage for information on the chkpnt command.

create

create expects a hash reference with the following keys and values.

ctid (required)

See chkpnt for details.

config (optional)

Expects a scalar, but doesn't check validity of value.

hostname (optional)

Expects a scalar, but doesn't check validity of value.

ipadd (optional)

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.

ostemplate (optional)

Expects a scalar, but doesn't check validity of value.

private (optional)

Expects a scalar, but doesn't check validity of value.

root (optional)

Expects a scalar, but doesn't check validity of value.

See the vzctl manpage for information on the create command.

destroy

destroy expects a hash reference with the following keys and values.

ctid (required)

See chkpnt for details.

See the vzctl manpage for information on the destroy command.

enter

enter expects a hash reference with the following keys and values.

ctid (required)

See chkpnt for details.

exec (optional)

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

exec expects a hash reference with the following keys and values.

ctid (required)

See chkpnt for details.

command (required)

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

exec2 expects a hash reference with the following keys and values.

ctid (required)

See chkpnt for details.

command (required)

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 exec2 command.

mount

mount expects a hash reference with the following keys and values.

ctid (required)

See chkpnt for details.

See the vzctl manpage for information on the mount command.

quotainit

quotainit expects a hash reference with the following keys and values.

ctid (required)

See chkpnt for details.

See the vzctl manpage for information on the quotainit command.

quotaoff

quotaoff expects a hash reference with the following keys and values.

ctid (required)

See chkpnt for details.

See the vzctl manpage for information on the quotaoff command.

quotaon

quotaon expects a hash reference with the following keys and values.

ctid (required)

See chkpnt for details.

See the vzctl manpage for information on the quotaon command.

restart

restart expects a hash reference with the following keys and values.

ctid (required)

See chkpnt for details.

See the vzctl manpage for information on the restart command.

restore

restore expects a hash reference with the following keys and values.

ctid (required)

See chkpnt for details.

restore_dumpfile

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

runscript expects a hash reference with the following keys and values.

ctid (required)

See chkpnt for details.

script (required)

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

set expects a hash reference with the following keys and values.

ctid (required)

See chkpnt for details.

applyconfig
applyconfig_map
hostname
name
netif_add
netif_del
pci_add
pci_del
searchdomain

Expects a scalar. No other validation is performed.

avnumproc
dcachesize
dgramrcvbuf
diskinodes
diskspace
kmemsize
lockedpages
numfile
numflock
numiptent
numothersock
numproc
numpty
numsiginfo
numtcpsock
oomguarpages
othersockbuf
physpages
privvmpages
shmpages
swappages
tcprcvbuf
tcpsndbuf
vmguarpages

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.

bootorder
cpulimit
cpus
cpuunits
quotatime
quotaugidlimit

Expects an integer.

capability

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'.

cpumask

Expects either a comma separated list of integers or the word 'all'.

devices

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.

devnodes
features

Expects one of the following features

sysfs nfs sit ipip ppp ipgre bridge nfsd

followed by a colon and either 'on' or 'off'.

force
save

Expects either undef or the empty string.

ioprio

Expects a single integer from 0 to 7.

ipadd
ipdel

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.

iptables

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
nameserver
disabled
noatime
onboot

Expects either 'yes' or 'no'.

setmode

Expects either 'restart' or 'ignore'.

userpasswd

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

start expects a hash reference with the following keys and values.

ctid (required)

See chkpnt for details.

force
wait

Expects either undef or the empty string.

See the vzctl manpage for information on the start command.

status

status expects a hash reference with the following keys and values.

ctid (required)

See chkpnt for details.

See the vzctl manpage for information on the status command.

stop

stop expects a hash reference with the following keys and values.

ctid (required)

See chkpnt for details.

See the vzctl manpage for information on the stop command.

umount

umount expects a hash reference with the following keys and values.

ctid (required)

See chkpnt for details.

See the vzctl manpage for information on the umount command.

INSTALLATION

See perlmodinstall for information and options on installing Perl modules.

SEE ALSO

Please see those modules/websites for more information related to this module.

AUTHOR

Alan Young <harleypig@gmail.com>

COPYRIGHT AND LICENSE

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.

DISCLAIMER OF WARRANTY

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.