Knife Plugin For XAPI to control xenserver
Latest commit 9bea7bd Mar 22, 2016 @spheromak Merge pull request #16 from Swiff/master
Timeout addition and fix

Knife Xapi

This plugin gives knife the ability to create guests on a XAPI compatable hyper visor


This plugin is distributed as a Ruby Gem. To install it, run:

gem install knife-xapi


Config options are extendable in the knife.rb the folowing config options can be defined there

  • knife[:xapi_host] The API Host to connect to
  • knife[:xapi_username] The User name to connect to the api with
  • knife[:xapi_password] The Password (if not set will prompt on commandline)
  • knife[:xapi_vm_template] Set a default template to be used when creating Guests
  • knife[:install_repo] The install repo config option to set when using Xen builtin templates
  • knife[:xapi_sr] The Storage Repository to provision from, uses pool/hypervisor default when not set
  • knife[:xapi_disk_size] Default VM disk size (8g if not specified)a
  • knife[:xapi_skip_disk] Skip adding any aditional disk to the vm.
  • knife[:xapi_cpus] The Default CPUs to provision for guests (2 if not specified)
  • knife[:xapi_mem] The Defaul ammount of Memory for guests (1g if not specified)
  • knife[:kernel_params] Optional Boot paramaters to pass to the guest
  • knife[:xapi_ssl_verify] Enable SSL Cert verification. Disabled due to xenserver not having valid certs on xapi

These options Controll xapi guest create bootstrap

  • knife[:domain] Set the domainname for the guest
  • knife[:run_list] Bootstrap Run list comma sepparated.
  • knife[:ssh_user] ssh user to login to the new vm as
  • knife[:ssh_port] ssh port to use
  • knife[:ssh_password] ssh password to use to login to the new vm
  • knife[:identity_file] ssh ident file
  • knife[:chef_node_name] node name to use for new guest chef run
  • knife[:bootstrap_version] version to bootstrap
  • knife[:bootstrap_template] template to use
  • knife[:template_file] path to a different template file you would like to use
  • knife[:environment] chef environment for first run
  • knife[:host_key_verify] true/false Honor hostkey verification or don't
  • knife[:ping_timeout] Seconds to timeout while waiting for an IP to be returned from guest
  • knife[:json_attributes] A JSON string to be added to the first run of chef-client
  • knife[:connect_timeout] Seconds to timeout while trying to connect to a guest


Note: The commands below when not specifing --host assumes that knife[:xapi_host] is set in ~/.chef/knife.rb

Guest Create

Basic usage to create a VM from existing VM template:

knife xapi guest create "NewBox" "Network 0"  --xapi-vm-template "MyBaseBox"   --host http://sandbox/ 

More verbose example using a kickstart file and booting the Centos 5 default template:

knife xapi guest create "MySpiffyBox" "pub_network" --host http://sandbox/ \
-B "dns= ks= " \
-R -C 4 -M 4g -D 5g 
  • -B Boot args where i am assigning all the centos/rhel boot args for kickstart file and dns
  • -R Repo URL used by xenserver to start the net install
  • -C Number of cpus for this guest
  • -M Memory size
  • -D Disk size


Using the same basic example you can bootstrap into a specific template

 knife xapi guest create "NewBox" "public" --xapi-vm-template "MyBaseBox" --host http://sandbox/ \
   --bootstrap-template centos5-gems --ssh-user root --ssh-password mypass \
   --run-list "role[base],role[spifybox]"

Guest Delete

Delete is pretty simple. When there are multiple vms with a name label you should be prompted to select one

knife xapi guest delete  testing 

If you know the UUID of the VM you can specify --uuid

knife xapi guest delete b461c0d2-d24d-bc02-3231-711101f57b8e --uuid

Guest List

List shows the vm's on the pool/host Ignoring Controll domains and templates. VM State, and Ip adress as reported through the xenapi. If you want to get the OpaqueRef, and UUID add -i or --show-id.

knife xapi guest list  
Name Label                 State        IP Address      
ks_test.local              Running      
dns01.local                Running      
dhcp01.local               Running      
jn_test.local              Running  

Start/Stop Guest

You can start/stop any instance with.. start and stop commands

knife xapi guest stop jn_test.local
knife xapi guest start jn_test.local

VDI Create

Create a disk on the xenserver with the specified size and name

xapi vdi create testing -D 20g 
  • -D is the short option for --xapi-disk-size
  • specify the SR to use with --xapi-sr or -S

VDI Delete

Remove a disk.

xapi vdi delete testing 

Delete has a special cleanup mode that will interactivly prompt you if you want to clean up non attached volumes

xapi vdi delete --interactive  

Delete also accepts a UUID for a disk with --uuid

VDI List

Report on xapi VDI's

knife xapi vdi list
VDI name: xs-tools.iso
  -UUID: bed2a28e-d68a-43d6-b8a1-2d30730b1561
    -Type: user
VDI name: chef-server-root
  -UUID: 159cbeb9-45c6-43e0-8631-b88d7644beae
  -Description: Root disk for chef-server-root created by jnelson with knfie xapi
    -Type: system
      -VM name: chef01.mkd.ktc
      -VM state: Running

Net list

Output info on host/pool networks lists the MTU, the extra info and name of the network.

Name:  vlan1120.stage
  Info: :
   MTU:  1500
  UUID:  73f6f18f-c1d9-664b-d4bb-7673ea0fc2a1


Every command should accept --help and display arguments that it accepts (as all knife plugins do)

knife xapi --help

knife xapi guest create --help