Rex::Virtualization::CBSD - CBSD virtualization module for bhyve
Version 1.0.0
use Rex::Commands::Virtualization; set virtualization => "CBSD"; vm 'create', name=>'foo', 'vm_os_type'=>'freebsd', 'vm_os_profile'=>'FreeBSD-x64-13.0', 'vm_ram'=>'1g', 'vm_cpus'=>'1', 'imgsize'=>'10g'; vm 'start' => 'foo'; # list the basic settings for the VM foo from the VM list my %vm_list = vm 'list'; print Dumper \%{ $vm_list{foo} }; # get all the config info for the VM foo and display it %vm_info=vm 'info' => 'foo'; foreach my $vm_info_key (@{keys(%vm_info)}){ print $vm_info_key.": ".$vm_info{$vm_info_key}."\n"; } # stop the VM foo vm 'stop' => 'foo'; # remove the VM foo vm 'remove' => 'foo'; # show all VM my %vm_list = vm 'list'; print Dumper \%vm_list;
This returns the CBSD base dir that the install is stored in.
No arguments are taken.
This will die upon error.
my $cbsd_base_dir=vm 'cbsd_base_dir'
Gets the next available VM name.
One argument is required and that is the base VM to use.
The optional argument 'lease_time' may be used to specify the number of seconds a lease for the VM name should last. The default is 30.
vm 'freejname' => 'foo'; # the same thing, but with a 60 second lease time vm 'freejname' => 'foo', lease_time => '60';
Creates a checkpoint via the command below.
cbsd bcheckpoint mode=create jname=$vm suspend=$suspend name=$name
The only required option is the key vm.
vm - VM to checkpoint name - name of checkpoint. by default: 'checkpoint'. suspend= - when set to 1 then turn off the domain immediately after checkpoint, for disk consistency. By default - 0, create checkpoint only.
vm 'bcheckpoint_create', vm=>'foo';
Removes all checkpoints via the command below.
cbsd bcheckpoint mode=destroyall jname=$vm
One argument is taken and that is the name of the VM.
# removes all checkpoints for the VM 'foo' vm 'bcheckpoint_destroyall', 'foo';
This closnes a VM.
old - The VM to clone. new - The name of the new VM. checkstate - 0 do not check for VM online. Default is 1 - check promote - Promotes clone to no longer be dependent from origin: 0 or 1. Default is 0 (not promote). This means new new VM operates in copy-on-write mode and will be promoted upon removal of the original. mac_reinit - 0,1 (default 1). 0 - leave old MAC. 1 set mac to re-generate
This will will die upon error.
vm 'bclone' old => 'foo', 'new' => 'bar';
Creates a new VM.
Below is a list of the basic options.
name - Name of the VM. bhyve_vnc_tcp_bind - VNC bind, e.g: '127.0.0.1', '0.0.0.0', '::1'. imgsize - VM first/boot disk size, e.g.: '10g', '21474836480000'. interface2 - <parent>, create VM with two interfaces, <parent> is uplink for nic2, do not confuse with the ci_interface2 parameter. nic_flags - '0' to disable. Pass additional flags for NIC, e.g.: 'private'. nic_flags2 - '0' to disable. Pass additional flags for NIC2, e.g.: 'private'. quiet - 0,1: be quiet, dont output verbose message. removejconf - 0,1: remove jconf after bcreate? 0 - don't remove. runasap - 0,1: when 1 - run a VM immediately (atomic bcreate+bstart). vm_cpus - VM CPUs cores, e.g.: '2'. vm_os_profile - <name>: full config file is: vm-${vm_os_type}-${vm_os_profile}.conf, file must be present in ~cbsd/etc/defaults/ or ~cbsd/etc/ directory. vm_os_type - <name>: full config file is: vm-${vm_os_type}-${vm_os_profile}.conf, file must be present in ~cbsd/etc/defaults/ or ~cbsd/etc/ directory. vm_ram - VM RAM, e.g.: '1g', '2147483648'. zfs_snapsrc - <name>: use ZFS snapshot as data source.
Below is a list of options for when using cloud init.
ci_gw4 - <ipv4> (cloud-init profile only): set IPv4 gateway for VM. ci_interface2 - configure second interface via cloud-init, do not confuse with the interface2 parameter. ci_interface_mtu - set MTU for NIC1, default: 1500. ci_interface_mtu2 - set MTU for NIC2, default: 1500. ci_ip4_addr - <ipv4> (cloud-init profile only): set IPv4 address for VM, default is: DHCP. Can be: 'DHCPv6' or static IPv4/IPv6. ci_ip4_addr2 - <ipv4> (cloud-init profile only): set IPv4 address for VM NIC2 (see also: ci_interface2,ci_gw42). Possible values same as ci_ip4_addr. ci_user_pubkey - full/relative path to authorized_keys or may contain pubkey string itself, e.g: ci_user_pubkey="ssh-ed25519 XXXXX root@my.domain". (cloud-init profile only): set authorized_keys file for cloud-init user for VM. ci_user_pw_user - set password for cloud-init user. ci_user_pw_root - set password for 'root' user.
A minimum of 'vm_os_type', 'vm_os_profile', 'vm_ram', 'vm_cpus', and 'imgsize' is needed.
This ran non-interactively.
This will die upon a error.
# create a x64 FreeBSD 13.0 VM named foo with 1G of ram, 1 CPU, and a 10G disk print Dumper vm 'create', name=>'foo', 'vm_os_type'=>'freebsd', 'vm_os_profile'=>'FreeBSD-x64-13.0', 'vm_ram'=>'1g', 'vm_cpus'=>'1', 'imgsize'=>'10g';
This returns a list of disks setup for use with Bhyve in CBSD via parsing the output of the command below.
cbsd bhyve-dsk-list display=jname,dsk_controller,dsk_path,dsk_size,dsk_sectorsize,bootable,dsk_zfs_guid header=0
This returned data is a array of hashes.
The keys are as below.
vm - The name of the VM in question. controller - Controller type configured for this. path - The path to the disk. size - Size of the disk in question. sectorsize - size of the sectors in question. bootable - If it is bootable. true/false zfs_guid - ZFS GUID of the disk.
This dies upon failure.
my @disks eval{ @disks=vm 'bdisk_list'; } or do { my $error = $@ || 'Unknown failure'; warn('Failed to the disk list... '.$error); } print Dumper(\@disks);
This fetches the available configuration information for a VM via the command below.
cbsd bget jname=$vm
The returned value is a flat hash of key value pairs.
my %vm_info eval{ %vm_info=vm 'binfo' => 'foo'; } or do { my $error = $@ || 'Unknown failure'; warn('Failed to get settings for the VM... '.$error); } foreach my $vm_info_key (@{keys(%vm_info)}){ print $vm_info_key.": ".$vm_info{$vm_info_key}."\n"; }
List available VMs.
The command used is...
cbsd bls display=nodename,jname,jid,vm_ram,vm_curmem,vm_cpus,pcpu,vm_os_type,ip4_addr,status,vnc,path header=0
The returned array is a hash of hashes. The first level hash is the jname.
nodename - The node name that this is set to run on. name - Name of the VM. jid - Jail ID/process ID of the VM if running. IF '0' it is not running. vm_ram - Max RAM for the VM. vm_curmem - Current RAM in use by the VM. vm_cpus - Number of virtual CPUs. pcpu - Current CPU usage. vm_os_type - OS type for the VM. ip4_addr - Expected IPv4 address for the VM. status - Current status of the VM. vnc - VNC address and port for the VM. path - Path to where the VM is stored.
my %vm_list; eval{ %vm_list=vm 'blist'; } or do { my $error = $@ || 'Unknown failure'; warn('Failed to list the VM... '.$error); } foreach my $vm_name (@{keys( %vm_list )}){ print "---------------------------\n". 'VM: '.$vm_name."\n". "---------------------------\n". 'jid: '.$vm_list{$vm_name}{jid}."\n". 'vm_ram: '.$vm_list{$vm_name}{vm_ram}."\n". 'vm_curmem: '.$vm_list{$vm_name}{vm_curmem}."\n". 'vm_cpus: '.$vm_list{$vm_name}{vm_cpus}."\n". 'vm_ram: '.$vm_list{$vm_name}{pcpu}."\n". 'vm_os_type: '.$vm_list{$vm_name}{vm_os_type}."\n". 'ip4_addr: '.$vm_list{$vm_name}{ip4_addr}."\n". 'status: '.$vm_list{$vm_name}{status}."\n". 'vnc: '.$vm_list{$vm_name}{vnc}."\n". 'path: '.$vm_list{$vm_name}{path}."\n". "\n" }
List configured NICs.
The command used is as below...
cbsd bhyve-nic-list display=nodename,jname,nic_driver,nic_parent,nic_hwaddr,nic_address,nic_mtu,nic_persistent,nic_ratelimit header=0
vm - The name of the VM in question. driver - The driver in use. As of currently either vtnet or e1000. node - The node it is on. parent - Either the name of the parent NIC, example 'bridge1', or set to 'auto'. hwaddr - The MAC address for the NIC. address - Address of the NIC. '0' if not configured. mtu - The MTU of NIC. '0' if default. persistent - 0/1 - 1 mean persistent nic (no managed by CBSD) ratelimit - Rate limit for the interface. '0' is the default. {tx}/{rx} (outgoing/incoming limit), {rxtx} - shared(rx+tx) limit, one value
my @nics eval{ @nics=vm 'bnic_list'; } or do { my $error = $@ || 'Unknown failure'; warn('Failed to the NIC list... '.$error); } print Dumper(\@nics);
This pauses a VM in question. The following modes are available. If no more is specified, audo is used.
auto - (by default) triggering - e.g, if vm active then pause on - pause, stop off - unpause, continue
The command called is as below.
cbsd 'bpause' => $vm mode=>$mode
eval{ vm 'bpause' => 'foo'; } or do { my $error = $@ || 'Unknown failure'; warn('Failed to pause the VM foo... '.$error); }
List configured PCI devices for a VM.
The command used is as below.
cbsd bpcibus mode=list jname=$vm
name - Drive name of the PCI item. bus - Bus number. slot - Slot number. function - Function number. desc - Description of the device.
One argument is required and that is the name of the VM.
my @devices eval{ @devices=vm 'bnic_list' => 'foo'; } or do { my $error = $@ || 'Unknown failure'; warn('Failed to the PCI device list... '.$error); } print Dumper(\@devices);
This removes the selected VM and remove the data. This is done via the command...
cbsd bremove $vm
eval{ vm 'bremove' => 'foo' } or do { my $error = $@ || 'Unknown failure'; warn('Failed to remove the VM foo... '.$error); }
This restarts the selected VM. This is done via the command...
cbsd brestart $vm
eval{ vm 'brestart' => 'foo' } or do { my $error = $@ || 'Unknown failure'; warn('Failed to restart the VM foo... '.$error); }
This sets various settings for a VM via the use of...
cbsd bset jname=$vm ...
One argument is equired and that is the VM name.
This will die upon failure. Please note the CBSD currently does not consider non-existent variables such as 'foofoo' to be a failure and silently ignores those.
# set the the VM foo to boot from net with a resolution of 800x600 vm 'bset' => 'foo', vm_boot => 'net', bhyve_vnc_resolution => '800x600';
This creates a disk snapshot of the specified VM via the command below.
cbsd bsnapshot mode=create jname=$vm snapname=$name
The following argument taken.
vm - The VM to snapshot. This is required. name - The snapshot name. If not specified it defaults to snapshot.
vm 'bsnapshot_create', vm=>'foo', name=>'aSnapshot';
This lists all the snapshots via the command below.
cbsd bsnapshot mode=list display=jname,snapname,creation,refer header=0
The return is a array of hashes. The hash keys are as below.
vm - Name of the VM the snapshot is for. name - Name of the snapshot. creation - The creation date. The format is YYYY-MM-DD__hh:mm. refer - ?
my @snaps=vm 'bsnapshot_list'; print Dumper \@snaps;
This removes the specified snapshot for the specified VM.
cbsd bsnapshot mode=destroy jname=$vm snapname=$name
The following argument required.
vm - The VM to snapshot. This is required. name - The snapshot name.
vm 'bsnapshot_remove', vm=>'foo', name=>'aSnapshot';
This removes specified snapshot for the specified VM.
cbsd bsnapshot mode=destroyall jname=$vm
vm - The VM to remove all snapshots for.
vm 'bsnapshot_removeall', vm=>'foo';
This rolls the disks for a VM back to a specified snapshot.
cbsd bsnapshot mode=rollback jname=$vm snapname=$name
vm - The VM to rollback. name - The snapshot name.
vm 'bsnapshot_rollback', vm=>'foo', name=>'aSnapshot';
This starts a VM. This is done via the command...
cbsd bstart jname=$vm
One argument is required and that is the name of the VM. If '*' or 'vm*' then start all VM whose names begin with 'vm', e.g. 'vm1', 'vm2'...
The following options may be used.
checkpoint - The name of the checkpoint to start the VM using.
eval{ vm 'bstart' => 'foo'; } or do { my $error = $@ || 'Unknown failure'; warn('Failed to start the VM foo... '.$error); } # starts foo from the checkpoint named checkpoint vm 'bstart' => 'foo', checkpoint=>'checkpoint';
This stops a VM. This is done via the command below...
cbsd bstop jname=$vm [hard_timeout=$timeout] [noacpi=$noacpi]
The following options are optional.
hard_timeout - Wait N seconds (30 by default) before hard reset. noacpi - 0,1. Set to 1 to prevent ACPI signal sending, just kill. By default it will attempt to use ACPI to ask it to shutdown.
eval{ vm 'bstop' => 'foo', hard_timeout => 60; } or do { my $error = $@ || 'Unknown failure'; warn('Failed to stop the VM foo... '.$error); }
This adds a p9 share for the specified VM. This is done via
cbsd bhyve-p9shares mode=attach jname=$vm p9device=$device p9path=$path
The keys below are required.
vm - Name of the VM the share is for. device - p9 device name, one word. path - The shared path.
vm 'p9shares_add', vm=>'foo', device=>'arc', path='/arc';
This lists the configured p9 shares. This is fetched using the command below.
cbsd bhyve-p9shares mode=list header=0 display=jname,p9device,p9path
The returned data is a array of hashes. The hash keys are as below.
my @shares=vm 'p9shares_list'; print Dumper \@shares;
This removes a p9 share for the specified VM. This is done via
cbsd bhyve-p9shares mode=deattach jname=$vm p9device=$device
vm - Name of the VM the share is for. device - p9 device name, one word.
vm 'p9shares_add', vm=>'foo', device=>'arc';
Get the VM OS profiles for a specified OS type.
One argument is required and that is the OS type.
An optional argument is taken and that is cloudinit. It is a Perl boolean value and if true it will only return profiles with cloudinit support.
The returned value is a array.
This will die upon failure.
# list the VM OS profiles for FreeBSD my @profiles=vm 'vm_os_profiles' => 'freebsd'; print Dumper @profiles; # list the VM OS profiles for FreeBSD @profiles=vm 'vm_os_profiles' => 'freebsd', cloudinit=>1; print Dumper @profiles;
One optional argument is taken and that is cloudinit. It is a Perl boolean value and if true it will only return profiles with cloudinit support.
The returned value is a two level hash. The keys for the first level are the OS types and the keys for the second level are the OS profile names.
my %os_profiles=vm 'vm_os_profiles_hash'; print Dumper %os_profiles; # print the OS profiles for FreeBSD print Dumper keys( %{ $os_profiles{freebsd} } ); my %os_profiles=vm 'vm_os_profiles_hash', cloudinit=>1; print Dumper %os_profiles;
Get the VM OS types there are profiles for.
# get a hash of all OS types and profiles my @os_types=vm 'vm_os_profiles'; print Dumper @os_types;
Zane C. Bowers-HAdley, <vvelox at vvelox.net>
<vvelox at vvelox.net>
Please report any bugs or feature requests to bug-rex-virtualization-cbsd at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Rex-Virtualization-CBSD. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-rex-virtualization-cbsd at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Rex::Virtualization::CBSD
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
https://rt.cpan.org/NoAuth/Bugs.html?Dist=Rex-Virtualization-CBSD
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Rex-Virtualization-CBSD
Repository
https://github.com/VVelox/Rex-Virtualization-CBSD
CPAN Ratings
https://cpanratings.perl.org/d/Rex-Virtualization-CBSD
Search CPAN
https://metacpan.org/release/Rex-Virtualization-CBSD
This software is Copyright (c) 2020 by Zane C. Bowers-HAdley.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)
To install Rex::Virtualization::CBSD, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Rex::Virtualization::CBSD
CPAN shell
perl -MCPAN -e shell install Rex::Virtualization::CBSD
For more information on module installation, please visit the detailed CPAN module installation guide.