Archive/XCP Beginners Guide

To Do: This guide is under construction. The following items still need to be done: Check some of the areas marked with (?) Complete areas marked TBD Create Storage_Repository article Add handy xe snippets

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 available on this level is XL, as before "xl help" to get a glimpse on possibilities. 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).

# 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

Breakdown:

• sr-create: this subcommand will output a generated UUID pointing to this new SR.
• 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 uuid=$(xe sr-list name-label="My ISO library" --minimal)"; 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

#

VM creation (CentOS6 minimal 64bit)

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-list 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 vdi-uuid=$VDIID vm-uuid=$VMID bootable=false type=Disk device=xvda)
# xe vm-cd-add vm=$VMID device=1 cd-name=centos62_x86_64_mini.iso
# xe vm-param-set uuid=$VMID other-config:install-repository=cdrom
# xe vm-memory-limits-set uuid=$VMID static-min=512MiB dynamic-min=512MiB dynamic-max=512MiB static-max=512MiB

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

Breakdown 'vm-memory-limits-set':

• uuid: this VM is about to be changed
• min/max values: min+maximum 512MB; otherwise CentOS installer wont start/work. Ordering of min/max is important even with all values the same!

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

# xe vm-start uuid=$VMID
# xe vm-param-get uuid=$VMID param-name=dom-id
23
# xenstore-read /local/domain/23/console/vnc-port
5901

Breakdown:

• vm-start: obviously start the VM
• vm-param-get: get the domain-id for this VM (this changes with every reboot of the VM!), result '23'
• xenstore-read: get the VNC listener port for the VM with dom-id 23, result '5901'

You can now connect with vncviewer to hostname-from-dom0:5901 and you'll find the regular CentOS installer shell. Waiting here until installation is over.

To nstall XS-Tools the default installed xs-tools.iso can be used, first steps on dom0:

dom0# xe vm-cd-eject vm=$VMID
dom0# xe vm-cd-insert vm=$VMID cd-name=xs-tools.iso
</pre
and from within domU:
<pre>
domU# mount /dev/sr0 /mnt
mount: block device /dev/sr0 is write-protected, mounting read-only
domU# cd /mnt/Linux/
domU#  ./install.sh 

Detected `CentOS release 6.2 (Final)' (centos version 6).

The following changes will be made to this Virtual Machine:
  * update arp_notify sysctl.conf.
  * packages to be installed/upgraded:
    - xe-guest-utilities-6.1.0-1031.x86_64.rpm
    - xe-guest-utilities-xenstore-6.1.0-1031.x86_64.rpm

Continue? [y/n] y


Preparing...                ########################################### [100%]
   1:xe-guest-utilities-xens########################################### [ 50%]
   2:xe-guest-utilities     ########################################### [100%]

You should now reboot this Virtual Machine.

For performance considerations you might want to switch from HVM to PV:

# xe vm-shutdown uuid=$VMID
# xe vm-param-set uuid=$VMID HVM-boot-policy=""
# xe vm-param-set uuid=$VMID PV-bootloader="pygrub"
# xe vm-param-set uuid=$VMID PV-args="xen_pv_hvm=enable"
# xe vm-start uuid=$VMID

That's about it.

Misc

handy xe snippets

Configure a static IP-address for xenbr1 (via eth1):

# xe pif-reconfigure-ip IP=10.23.42.23 netmask=255.255.255.0 mode=static uuid=$(xe pif-list device=eth1 --minimal)

Create additional SR on a second disk, here /dev/sdb:

# pvcreate /dev/sdb
# vgcreate vg_second_sr /dev/sdb
# lvcreate -l "100%PVS" -n "lv_second_sr" vg_second_sr
# xe sr-create name-label="Secondary Storage" type=lvm content-type=user device-config:device=/dev/vg_second_sr/lv_second_sr

Add secondary storage from above SR into a VM, mounting as /home

dom0# VMID=$(xe vm-list name-label=TestVM1 --minimal)
dom0# SRID=$(xe sr-list name-label="Secondary Storage" --minimal)
dom0# VDIID=$(xe vdi-create name-label=secondary_disk sr-uuid=$SRID type=user virtual-size=10GiB)
dom0# VBDID=$(xe vbd-create vdi-uuid=$VDIID vm-uuid=$VMID bootable=false type=Disk device=xvdb)
dom0# xe vbd-plug uuid=$VBDID
### disk /dev/xvdb now usable from within domU "TestVM1"
domU# pvcreate /dev/xvdb
domU# vgcreate vg_home /dev/xvdb
domU# lvcreate -l "100%PVS" -n "lv_home" vg_home
domU# mkfs.ext4 /dev/vg_home/lv_home
domU# mount /dev/mapper/vg_home-lv_home /home
###add line '/dev/mapper/vg_home-lv_home /home                       ext4    defaults        1 1' to /etc/fstab