XAPI Command Line Interface

XCP Command Line Interface

XE Basics

The xapi toolstack includes a powerful command-line interface (“xe”) which talks to both hosts and Resource Pools over https, invoking XenAPI operations over XMLRPC. Commands may be issued both from within domain zero (xe is on the $PATH by default) and from remote hosts. For users of the bash shell extensive tab completion is available, greatly increasing usability. Please refer to the “Xen Cloud Platform Administrator Guide”, chapter 8 on page 123 for more information and details on each of the xe commands.

For installing the 'xe' CLI on another Linux box, see XCP Install CLI

Basic xe Syntax

When run from domain zero:

xe <command-name> <argument=value>*

When run from another host:

xe –s <host> -u <username> -pw <password> <command-name> <argument=value>*

Note:

With any command, hitting the “Tab” key on a keyboard will list out any options available for a particular command as well as complete command syntax. Values containing spaces should be enclosed with double-quotes.

Common Commands

List CD/ISO

Power on VM

Mount an ISO

Show list of VMs on host

List SRs

Delete/Destroy VM on host

Create Storage Repository

Destroy Storage Repository

Common Host (Xen Cloud Platform host) Commands

List Host in Pool

Enable a Xen Cloud Platform Host

Reboot a Xen Cloud Platform Host

Shutdown a Xen Cloud Platform Host

Virtual Machine Examples

This is a simple overview of a two easy was to get a Xen Cloud Platform host up and running with a virtual machine. Two examples will be provided:

1. Debian Lenny 5.0 VM: Install and configure a Debian based VM using a network repository leveraging the xe command line interface.
2. General VM: Install and configure a VM leveraging the local CDRom of the host and the xe commend line interface.

Debian Lenny 5.0 Example

1. Download the lenny.xva from http://www.xen.org/files/XenCloud/Software/lenny.xva, saving to location where running the xe command line, either in domain zero or some other host.
2. Import lenny.xva to your Xen Cloud Platform host:
   • a) # xe vm-import filename=lenny.xva
3. Create a VM based on the Lenny template:
   • a) # xe vm-install template=Debian\ Lenny\ 5.0 new-name-label=<name of VM>

 b. Note the UUID output.  

1. Set other-config to point to your Debian repository:
   • a) # xe vm-param-set uuid=<uuid of new VM> other-config:install-repository=http://ftp.debian.org/
2. Identify the target network interface.
   • a) #xe network-list

 b. Note the uuid of xenbr desired for use (xenbr<N> corresponds to NIC<N>)

1. Add a VIF on an appropriate network:
   • a) #xe vif-create network-uuid=<network uuid from above> vm-uuid=<uuid of new VM> device=0

 b. Note the uuid output of the new VIF.

1. Start the VM, then go to its console and the Debian installer should be running and ready to install on the guest.
   • a) # xe vm-start vm=<name of VM>

General VM Example

1. Create a VM based on a base template:
   • a) # xe vm-install template=<name of target template> new-name-label=<name of VM>

 b. Note the UUID output.  

1. Identify the target network interface.
   • a) #xe network-list

 b. Note the uuid of xenbr desired for use

1. Add a VIF on an appropriate network (use xe network-list to find the list of networks):
   • a) #xe vif-create network-uuid=<network uuid from above> vm-uuid=<uuid of new VM> device=0

 b. Note the uuid output of the new VIF.

1. View the CD list attached the host
   • a) # xe cd-list

 b. Note the name label

1. Add a new virtual CD to the selected VM
   • a) xe vm-cd-add cd-name=<CDRom name label> vm=<name of new VM> device=<integer not used>
2. Lists CDs attached to the specified VMs.
   • a) #xe vm-cd-list vm=<name of new VM>
3. Start the VM, then go to its console and the CD based OS installer should be running and ready to install on the guest.
   • a) # xe vm-start uuid=<uuid of new VM>

Developer XAPI Viewer (with Console)

The Developer XAPI view tool is a simple way to view the various XAPI commands in a simple GUI, but also do things like:

• Start a virtual machine
• Connect to a virtual machine via a Java console
• Shutdown a virtual machine

Start a Virtual Machine

1. Open up a web browser.
   • a) Firefox 3.5.3 and Java 6 Update 15 (build 1.6.0_15-b03)

 b. Chrome 3.0.195.27 and Java 6 Update 15 (build 1.6.0_15-b03)

1. Type the IP of your host into the URL bar and connect.
2. Type in the user name and password of your XCP host connection.
3. The list of XenAPI classes will appear.
4. Click on the “Console” class and your list of running virtual machines will appear.
5. Click on the target virtual machine and virtual machine properties will appear.
6. Click on “Start” to boot the virtual machine.

Console Connections

1. Open up a web browser.
   • a) Firefox 3.5.3 and Java 6 Update 15 (build 1.6.0_15-b03)

 b. Chrome 3.0.195.27 and Java 6 Update 15 (build 1.6.0_15-b03)

1. Type the IP of your host into the URL bar and connect.
2. Type in the user name and password of your XCP host connection.
3. The list of XenAPI classes will appear.
4. Click on the “Console” class and your list of running virtual machines will appear.
5. Click on the target virtual machine and the console windows will open (requires Java).
6. Click “Undock” to get a better console view of the virtual machine.

Shutdown/Restart Options for a Virtual Machine

1. Open up a web browser.
   • a) Firefox 3.5.3 and Java 6 Update 15 (build 1.6.0_15-b03)

 b. Chrome 3.0.195.27 and Java 6 Update 15 (build 1.6.0_15-b03)

1. Type the IP of your host into the URL bar and connect.
2. Type in the user name and password of your XCP host connection.
3. The list of XenAPI classes will appear.
4. Click on the “Console” class and your list of running virtual machines will appear.
5. Click on the target virtual machine and virtual machine properties will appear.
6. Click on any of the following options
   • a) clean_reboot to reboot the virtual machine properly leveraging the underlying operating system. This requires the VM to have the PV drivers/ guest tools installed.

 b. clean_shutdown to shutdown reboot the virtual machine properly leveraging the underlying operating system. This requires the VM to have the PV drivers/ guest tools installed.

 c. hard_reboot to force reboot the virtual machine.

 d. hard_shutdown to force shutdown reboot the virtual machine.

Install the PV Drivers on a Windows Virtual Machine

1. Log onto the host console (e.g. via ssh)
2. Run the following xe command:
   • a) # xe vm-cd-eject vm=<target VM name>

 b. # xe vm-cd-insert cd-name=xs-tools.iso vm=<target VM name>

 c. NOTE: VM can be either off or booted.

1. Install the PV Drivers leveraging the console feature available in the XAPI Viewer tool.