Archive/XCP Beginners Guide

Welcome!

By following this beginners guide, you will learn the outline concept of XCP by installing it and doing basic tasks without prior knowledge of XCP. Some basic knowledge about Linux, virtualization, networks and working on the command-line is necessary.

This guide also includes daily tasks like creating a new VM, which are being used explaining XCP and it's components.

What is XCP all about

By installing XCP from a single ISO-image, you get a ready-to-use virtualization plattform that consists from:

• Xen Hypervisor: providing the low level virtualization
• XAPI: the XCP toolstack which is used internally to manage the hypervisor
• xe: the command-line tool to configure and operate the XCP plattform
• xsconsole: a text-based UI to do basic tasks and configurations

The OS hosting all those components is based on CentOS (see XCP_Release_Features for current versions in use.

Requirements

Hardware

• 64bit x86 computer with at least 1GB of RAM
• Storage (HDD) with at least 40(?)GB to install XCP and some basic VMs (XCP itself will take a 4GB chunk)
• CD/DVD-Drive (netboot is possible, but not covered here)

Software

• The XCP ISO, see Downloads for the latest build. The ISO is ~450MB (1.6-release)
• Any guest OS (ISO-image suffices) you want to install

Installation

Just boot from the burned CD and follow the steps. For a quick trial&play installations, the defaults are fine. For a full explanation please refer to XCP_Installation.

First steps

Local terminals

While the system is coming up, you'll see the XCP logo with a progess bar. After loading and initializing the system has finished XCP will show xsconsole on screen including some basic information about the status of the system.

The second screen (Alt+F2) will get you a system log, which is usually empty after a clean boot.

On the third screen (Alt+F3) you get a login page with additional info about how to connect with externals tools (e.g. XenCenter) including the IP-address and the SSL certificate fingerprint.

To return to the xsconsole screen, press Alt+F1.

xsconsole

To gather basic information about the running XCP system and doing basic tasks like start/stop VMs, creating Storage Repositories. See xsconsole for a full list of possibilities.

Command Line

Choose 'Local Command Shell' from xsconsole, or type Alt+F3 and log into XCP. If you open a shell via xsconsole, type 'exit' to return and do not start xsconsole on your own again.

The main tool to manage XCP on this level is xe. A short overview of possible sub-commands can be listed by "xe help". A second tool availble on this level is xl(1), as before "xl help" to get a glimpse on possibilities. (TODO: xl wikipage). Both tools are leveraged by TAB-completion, for xe not only sub-commands are expandable, but also parameters and possible values.

To gather realtime information on the usage of the system by VMs, use 'xentop'.

Basic xe concept

Gather information

The main tool to operate XCP is xe. In short terms xe takes on argument as a subcommand, and if this subcommand needs further arguments, they have to follow suit. Possible subcommands and further arguments/values can be TAB-completed. See Command_Line_Interface for some syntax examples.

The subcommands are grouped in means what component you will be operating on. The grouping is done just by the naming of the subcommand, such as all subcommands operating on a VM start with 'vm-', e.g. "xe vm-list". Unless it would not make sense, each group has a 'list' feature, e.g. "xe vm-list", "xe network-list", ... .

Below is a selected list of components for xe:

• vm: virtual machines
• sr: storage repositories
• pbd: physical block device
• vbd: virtual block device
• vdi: virtual disk image
• pif: physical network interface
• vif: virtual network interface
• network: virtual networks

Any component with parameters, usually have an according component-param-* subcommand. These are 'list','get','set','add','clear','remove'; e.g. "xe sr-param-list". Since these commands must target a certain object, you need a unique identifier as an argument (called UUID).

Example: Let's get all set parameters from a certain Storage_Repository:

# xe sr-list
..some output..
uuid ( RO)                : 5bfbefea-9dc0-b541-93d0-fb2717f70752
          name-label ( RW): Local storage
    name-description ( RW): 
                host ( RO): your-xcp-hostname
                type ( RO): lvm
        content-type ( RO): user
..more output..

# xe sr-param-list uuid=5bfbefea-9dc0-b541-93d0-fb2717f70752
uuid ( RO)                    : 5bfbefea-9dc0-b541-93d0-fb2717f70752
              name-label ( RW): Local storage
        name-description ( RW): 
                    host ( RO): your-xcp-hostname
      allowed-operations (SRO): VDI.create; VDI.snapshot; PBD.create; PBD.destroy; plug; update; VDI.destroy; scan; VDI.clone; VDI.resize; unplug
..more output..

The -list subcommand has an option "--minimal" which will only output the UUIDs. Also it can take any parameter to lock down the search results:

# xe sr-list name-label=Local\ storage
uuid ( RO)                : 5bfbefea-9dc0-b541-93d0-fb2717f70752
          name-label ( RW): Local storage
    name-description ( RW): 
                host ( RO): your-XCP-hostname
                type ( RO): lvm
        content-type ( RO): user

# xe sr-list name-label="Local storage" --minimal
5bfbefea-9dc0-b541-93d0-fb2717f70752

So.. let's combine this to get a full parameter-list for an SR called "Local storage" (which is the default for any XCP install):

# xe sr-param-list uuid=$(xe sr-list name-label="Local storage" --minimal)
uuid ( RO)                    : 5bfbefea-9dc0-b541-93d0-fb2717f70752
              name-label ( RW): Local storage
        name-description ( RW): 
                    host ( RO): your-XCP-hostname
      allowed-operations (SRO): VDI.create; VDI.snapshot; PBD.create; PBD.destroy; plug; update; VDI.destroy; scan; VDI.clone; VDI.resize; unplug
..more output..

Note: $(command) puts the output of 'command' in the given location

Set parameters

TBD

VM installation

To install an OS within a VM some prerequisites must be met:

• Install media: either CD/DVD or ISO-image (via ISO SR)
• Network: basic layout, requirements like Internet access or plain internal network should be thought of beforehand

ISO SR

If an installation via physical media or via netboot is not possible or just not wanted, it's possible to install the VM from an ISO image stored within an SR. Please refrain from putting the images into the SR which holds xs-tools.iso (TBD: reasoning), rather create a new SR which can be located either on local disk of the XCP host or via NFS, iSCSI or whatever means you can establish. For this trial&play guide we will use some diskspace located within the XCP partition itself next to the XCP system ISO SR (TBD: naming).

# ISOSRID=$(xe sr-create name-label="My ISO library" type=iso content-type=iso device-config:legacy_mode=true device-config:location=/var/opt/xen/iso_import/MyISOlib)
(no output)
#

Breakdown:

• ISOSRID=$(....): the 'sr-create' subcommand will output a generated UUID pointing to this new SR. For bash-beginners: the NAME=$(...) syntax assigns this UUID to the variable $SRID which will be used later on. Keep in mind, this guide makes more use out of this construct.
• name-label: this will be the literal name of this SR, pick any name you like (as long as it is ASCII(?))
• type=iso, content-type=iso: the images put into this SR are ISO images are presented to the VMs as ISO (as in real CD/DVD devices)
• device-config:legacy_mode=true: TBD (from my understanding: HVM?)
• device-config:location=/some/path: this defines the directory where the ISO images are put into already or later on

Now copy any ISO image you want to use into the given directory. Then run "xe sr-scan $SRID"; do this every time after you've added (or deleted) an ISO image. After this you can see the ISO images as a virtualized CD:

# xe cd-list  
..some output, e.g. physical CD drives..
uuid ( RO)          : 096dc05c-0b73-4b88-926e-964a6673cb01
    name-label ( RW): centos62_x86_64_mini.iso
..more output, e.g. xs-tools.iso

# CDID=$(xe cd-list name-label=centos62_x86_64_mini.iso --minimal)
(no output)
#

The second command stores the UUID of the virtualized CD containing centos62_x86_64_mini.iso into the shell variable $CDID as you might have figured out already.

VM creation

To outline how quickly a VM can be created from xe only, see these commands with an explanation following it:

# VMID=$(xe vm-install new-name-label=TestVM1 template="Other install media")
# LOCALSRID=$(xe sr-param-get param=uuid name-label="Local Storage" --minimal)
# VDIID=$(xe vdi-create name-label="VDI for TestVM1" sr-uuid=$LOCALSRID type=user virtual-size=10GiB)
# VBDID=$(xe vbd-create vid-uuid=$VDIID vm-uuid=$VMID bootable=false type=Disk device=xvda
# xe vbd-plug uuid=$VBDID
# xe vm-cd-add vm=$VMID device=0 cd-name=centos62_x86_64_mini.iso
# xe vm-param-set uuid=$VMID other-config:install-repository=cdrom

Breakdown 'vm-install':

• new-name-label: literal name as you see fit for the new VM
• sr-param-get: get the UUID of the default SR for storing VM images
• template: using an XCP template named exactly this way

Breakdown 'vdi-create':

• name-label: literal name for the Virtual_Disk_Image being used as install-disk for this VM
• sr-uuid: as from sr-param-get
• type=user: TBD
• virtual-size: set the size of the installdisk in SI units

Breakdown 'vbd-create': Note: think of VBD as a "cable" between the VDI and the VM

• vid-uuid: "cable" starts at the disk $VDIID
• vm-uuid: "cable" ends at the VM $VMID
• bootable: you want to boot from CD for installation, so set the disk to false for now
• type=Disk: target is a disk (and not some read-only media)
• device=xvda: this device-name will be used by the installer from within the VM, if unsure about how the OS being installed names it, use 'device=0'. You cannot use names at your will here (not like name-labels).

Breakdown 'vbd-plug': Note: with 'vbd-create' only the "cable" usage was defined, now plug it in.

• uuid: since start and endpoint are already defined, just plug the cable on both sides (VDI/VM)

Breakdown 'vm-cd-add':

• vm: add the following "CD Drive" to this VM
• device=0: let it be the first "CD Drive" (Sidenote: this is /dev/sr0 in CentOS)
• cd-name: use this ISO (it must appear with name-label like this in 'xe cd-list')

Breakdown 'vm-param-set':

• uuid: this VM is about to be changed
• other-config: change the install-behaviour to look for install-repositories on "cdrom" (which is on what you just defined via vm-cd-add)

Nothing happens? Well, so far you only defined the outline of this VM. Now for booting and installation.

Misc

handy xe snippets

To Do: Add here