Citrix XenServer ® 5.6 Administrator's Guide Published June 2010 1.
Citrix XenServer ® 5.6 Administrator's Guide Copyright © 2009 Citrix All Rights Reserved. Version: 5.6 Citrix, Inc. 851 West Cypress Creek Road Fort Lauderdale, FL 33309 United States of America Disclaimers This document is furnished "AS IS." Citrix, Inc. disclaims all warranties regarding the contents of this document, including, but not limited to, implied warranties of merchantability and fitness for any particular purpose.
Table of Contents Document Overview .................................................................................... 1 How this Guide relates to other documentation .................................................................................. 1 Managing users ............................................................................................ 2 Authenticating users using Active Directory (AD) .................................................................................
Creating a resource pool ............................................................................................................. 20 Creating heterogeneous resource pools .......................................................................................... 21 Adding shared storage ................................................................................................................ 21 Removing a XenServer host from a resource pool .........................................................
Storage Overview ....................................................................................................................... 30 Storage Repositories (SRs) ................................................................................................... 30 Virtual Disk Images (VDIs) .................................................................................................... 30 Physical Block Devices (PBDs) .................................................................................
Creating a shared EqualLogic SR .................................................................................. 41 EqualLogic VDI Snapshot space allocation with XenServer EqualLogic Adapter ......................... 42 Creating a VDI using the CLI ................................................................................ 43 NetApp ............................................................................................................................ 43 Creating a shared NetApp SR over iSCSI ...
Adjusting the disk IO scheduler ............................................................................................. 61 Virtual disk QoS settings ............................................................................................................. 61 Configuring VM memory ........................................................................... 63 What is Dynamic Memory Control (DMC)? .......................................................................................
Initial networking configuration ............................................................................................. 72 Managing networking configuration ................................................................................................ 72 Creating networks in a standalone server ................................................................................ 72 Creating networks in resource pools ......................................................................................
Workload Balancing ................................................................................. 85 What’s New? ............................................................................................................................ 85 New Features .................................................................................................................... 85 Changes ..........................................................................................................................
Configuring Workload Balancing Settings ........................................................................................ 98 To display the Workload Balancing Configuration dialog box ........................................................ 99 Adjusting the Optimization Mode ........................................................................................... 99 Fixed .......................................................................................................................
Modifying the Aggressiveness Setting ................................................................... 107 Receiving Reports by Email Automatically (Report Subscriptions) ......................................... 108 To configure report subscriptions ........................................................................ 109 Choosing an Optimal Server for VM Initial Placement, Migrate, and Resume ........................................... 109 To start a virtual machine on the optimal server ............
Displaying Workload Balancing Reports ................................................................................. 117 Report Generation Features ........................................................................................ 117 Toolbar Buttons ....................................................................................................... 117 Workload Balancing Report Glossary ....................................................................................
Restoring a VM to its previous state ..................................................................................... 129 Deleting a snapshot .................................................................................................. 129 Snapshot Templates ........................................................................................................ 130 Creating a template from a snapshot ............................................................................
Command types ...................................................................................................................... 144 Parameter types ............................................................................................................... 145 Low-level param commands ............................................................................................... 145 Low-level list commands ..............................................................................................
license-server-address ............................................................................................... 158 license-server-port .................................................................................................... 158 host-license-add ...................................................................................................... 158 host-license-view ......................................................................................................
patch-precheck ........................................................................................................ 165 patch-upload ........................................................................................................... 165 PBD commands .............................................................................................................. 165 pbd-create ..............................................................................................................
sr-create ................................................................................................................. 175 sr-destroy ............................................................................................................... 175 sr-forget ................................................................................................................. 175 sr-introduce .............................................................................................................
vdi-introduce ........................................................................................................... 191 vdi-resize ................................................................................................................ 191 vdi-snapshot ........................................................................................................... 191 vdi-unlock ...............................................................................................................
vm-disk-add ............................................................................................................ 205 vm-disk-list ............................................................................................................. 206 vm-disk-remove ....................................................................................................... 206 vm-export ............................................................................................................... 206 vm-import .
pool-retrieve-wlb-recommendations ............................................................................ 212 pool-retrieve-wlb-report ........................................................................................... 212 pool-send-wlb-configuration ....................................................................................... 213 Index ..........................................................................................................
Document Overview This document is a system administrator's guide to XenServer™, the platform virtualization solution from Citrix®. It describes the tasks involved in configuring a XenServer deployment-- in particular, how to set up storage, networking and resource pools, and how to administer XenServer hosts using the xe command line interface (CLI). This section summarizes the rest of the guide so that you can find the information you need.
Managing users When you first install XenServer, a user account is added to XenServer automatically. This account is the local super user (LSU), or root, which is authenticated locally by the XenServer computer. The local super user (LSU), or root, is a special user account used for system administration and has all rights or permissions. In XenServer, the local super user is the default account at installation. The LSU is authenticated by XenServer and not an external authentication service.
XenCenter Term XenServer CLI Term Users Subjects Add users Add subjects Understanding Active Directory authentication in the XenServer environment Even though XenServers are Linux-based, XenServer lets you use Active Directory accounts for XenServer user accounts. To do so, it passes Active Directory credentials to the Active Directory domain controller. When added to XenServer, Active Directory users and groups become XenServer subjects, generally referred to as simply users in XenCenter.
configurations, the active directory server may provide the DNS itself. This can be achieved either using DHCP to provide the IP address and a list of DNS servers to the XenServer host, or by setting values in the PIF objects or using the installer if a manual static configuration is used. Citrix recommends enabling DHCP to broadcast host names. In particular, the host names localhost or linux should not be assigned to hosts.
1. Configure the DNS server to use on your XenServer hosts: xe pif-reconfigure-ip mode=static dns= 2. Manually set the management interface to use a PIF that is on the same network as your DNS server: xe host-management-reconfigure pif-uuid= Note: External authentication is a per-host property.
xe subject-list You may wish to apply a filter to the list, for example to get the subject identifier for a user named user1 in the testad domain, you could use the following command: xe subject-list other-config:subject-name='' 2. Remove the user using the subject-remove command, passing in the subject identifier you learned in the previous step: xe subject-remove subject-identifier= 3. You may wish to terminate any current session this user has already authenticated.
When you leave the domain (that is, disable Active Directory authentication and disconnect a pool or server from its domain), any users who authenticated to the pool or server with Active Directory credentials are disconnected. Use XenCenter to leave an AD domain. See the XenCenter help for more information. Alternately run the pool-disable-external-auth command, specifying the pool uuid if required. Note: Leaving the domain will not cause the host objects to be removed from the AD database.
The local super user (LSU), or root, is a special user account used for system administration and has all rights or permissions. In XenServer, the local super user is the default account at installation. The LSU is authenticated via XenServer and not external authentication service, so if the external authentication service fails, the LSU can still log in and manage the system. The LSU can always access the XenServer physical host via SSH.
A user's role can be changed in two ways: 1. Modify the subject -> role mapping (this requires the assign/modify role permission, only available to a Pool Administrator.) 2. Modify the user's containing group membership in Active Directory. Definitions of RBAC roles and permissions The following table summarizes which permissions are available for each role. For details on the operations available for each permission, see Definitions of permissions. Table 1.
Role Pool Admin permissions Pool Operator VM Power Admin VM Admin VM Operator VM change CD media X X X X X View VM consoles X X X X X XenCenter view mgmt ops X X X X X Cancel own tasks X X X X X X Read audit logs X X X X X X Configure, Initialize, Enable, Disable WLB X X X Apply WLB X Optimization Recommendations X Modify WLB X Report Subscriptions X Accept WLB X Placement Recommendations X X Display X WLB Configuration X X X X Generate WLB Reports X X
Table 2. Definitions of permissions Permission Allows Assignee To Rationale/Comments Assign/modify roles • Add/remove users This permission lets the user grant himself or herself any permission or perform any task.
Permission Allows Assignee To Rationale/Comments Pool management • Set pool properties (naming, default SRs) This permission includes all the actions required to maintain a pool.
Permission Allows Assignee To Rationale/Comments VM advanced operations • Adjust VM memory (through Dynamic Memory Control) This permission provides the assignee with enough privileges to start a VM on a different server if they are not satisfied with the server XenServer selected.
Permission Allows Assignee To Accept WLB Placement Recommendations • Select one of the servers Workload Balancing recommends for placement ("star" recommendations) Display WLB Configuration • View WLB settings for a pool as shown on the WLB tab Generate WLB Reports • View and run WLB reports, including the Pool Audit Trail report XenCenter view mgmt operations • Create and modify global XenCenter folders • Create and modify global XenCenter custom fields Rationale/Comments Folders, custom fields,
uuid( RO): 0165f154-ba3e-034e-6b27-5d271af109ba name ( RO): pool-admin description ( RO): The Pool Administrator role can do anything uuid ( RO): b9ce9791-0604-50cd-0649-09b3284c7dfd name ( RO): pool-operator description ( RO): The Pool Operator can do anything but access Dom0 and mange subjects and roles uuid( RO): 7955168d-7bec-10ed-105f-c6a7e6e63249 name ( RO): vm-power-admin description ( RO): The VM Power Administrator role can do anything \ affecting VM properties across the pool uuid ( RO): aaa00ab5-
uuid ( RO): bb6dd239-1fa9-a06b-a497-3be28b8dca44 subject-identifier ( RO): S-1-5-21-1539997073-1618981536-2562117463-2244 other-config (MRO): subject-name: example01\user_vm_admin; subject-upn: \ user_vm_admin@XENDT.
To change a subject's RBAC role: To change a user's role it is necessary to remove them from their existing role, and add them to a new role: 1.
How does XenServer compute the roles for the session? 1. The subject is authenticated via the Active Directory server to verify which containing groups the subject may also belong to. 2. XenServer then verifies which roles have been assigned both to the subject, and to its containing groups. 3. As subjects can be members of multiple Active Directory groups, they will inherit all of the permissions of the associated roles.
XenServer hosts and resource pools This chapter describes how resource pools can be created through a series of examples using the xe command line interface (CLI). A simple NFS-based shared storage configuration is presented and a number of simple VM management examples are discussed. Procedures for dealing with physical node failures are also described.
Note: The requirement for a XenServer host to have a static IP address to be part of a resource pool also applies to servers providing shared NFS or iSCSI storage for the pool. Although not a strict technical requirement for creating a resource pool, the advantages of pools (for example, the ability to dynamically choose on which XenServer host to run a VM and to dynamically move a VM between XenServer hosts) are only available if the pool has one or more shared storage repositories.
xe pool-param-set name-label=<"New Pool"> uuid= Creating heterogeneous resource pools Note: Heterogeneous resource pool creation is only available for XenServer Enterprise or Platinum editions. To learn more about XenServer editions and to find out how to upgrade, visit the Citrix website here here XenServer 5.6 simplifies expanding deployments over time by allowing disparate host hardware to be joined into a resource pool, known as heterogeneous resource pools.
Adding NFS shared storage to a resource pool using the CLI 1. Open a console on any XenServer host in the pool. 2. Create the storage repository on by issuing the command xe sr-create content-type=user type=nfs name-label=<"Example SR"> shared=true \ device-config:server= \ device-config:serverpath= The device-config:server refers to the hostname of the NFS server and deviceconfig:serverpath refers to the path on the NFS server.
High Availability This section explains the XenServer implementation of virtual machine high availability (HA), and how to configure it using the xe CLI. Note: XenServer HA is only available with XenServer Advanced edition or above. To find out about XenServer editions, visit the Citrix website here. HA Overview When HA is enabled, XenServer continually monitors the health of the hosts in a pool. The HA mechanism automatically moves protected VMs to a healthy host if the current VM host fails.
running on it to be stopped. The other servers will detect that the VMs are no longer running and the VMs will be restarted according to the restart priorities assign to them. The fenced server will enter a reboot sequence, and when it has restarted it will try to re-join the resource pool. Configuration Requirements To use the HA feature, you need: • Shared storage, including at least one iSCSI or Fibre Channel LUN of size 356MB or greater - the heartbeat SR.
1|2|3 when a pool is overcommited the HA mechanism will attempt to restart protected VMs with the lowest restart priority first best-effort VMs with this priority setting will be restarted only when the system has attempted to restart protected VMs ha-always-run=false VMs with this parameter set will not be restarted The restart priorities determine the order in which VMs are restarted when a failure occurs.
4. Run the pool-ha-compute-max-host-failures-to-tolerate command. This command returns the maximum number of hosts that can fail before there are insufficient resources to run all the protected VMs in the pool.
XenCenter offers you a dialog box to automate disabling the protection if you click on the Shutdown button of a protected VM. Note: If you shut down a VM from within the guest, and the VM is protected, it is automatically restarted under the HA failure conditions. This helps ensure that operator error (or an errant program that mistakenly shuts down the VM) does not result in a protected VM being left shut down accidentally. If you want to shut this VM down, disable its HA protection first.
Balancing's Host Power Management feature, use the pool-send-wlb-configuration command with the ParticipatesInPowerManagement= \ config:set_host_configuration= arguments. To enable Host Power On using the CLI 1. Run the command: xe host-set-power-on host=\ power-on-mode=("" , "wake-on-lan", "iLO", "DRAC","custom") power-on-config:key=value For iLO and DRAC the keys are power_on_ip, power_on_user, power_on_password.
• Possible values: • An empty string, representing power-control disabled • "iLO". Lets you specify HP iLO. • "DRAC". Lets you specify Dell DRAC. To use DRAC, you must have already installed the Dell supplemental pack. • "wake-on-lan". Lets you specify Wake on LAN. • Any other name (used to specify a custom power-on script). This option is used to specify a custom script for power management. • Type: string host.power_on_config • Definition: This contains key/value pairs for mode configuration.
Storage This chapter discusses the framework for storage abstractions. It describes the way physical storage hardware of various kinds is mapped to VMs, and the software objects used by the XenServer host API to perform storage-related tasks.
configuration fields that are used to connect to and interact with a given storage target. For example, NFS device configuration includes the IP address of the NFS server and the associated path that the XenServer host mounts. PBD objects manage the run-time attachment of a given SR to a given XenServer host. CLI operations relating to PBDs are described in the section called “PBD commands”.
VHD-based VDIs VHD files may be chained, allowing two VDIs to share common data. In cases where a VHD-backed VM is cloned, the resulting VMs share the common on-disk data at the time of cloning. Each proceeds to make its own changes in an isolated copy-on-write (CoW) version of the VDI. This feature allows VHD-based VMs to be quickly cloned from templates, facilitating very fast provisioning and deployment of new VMs.
reported for the SR will depend on the number of snapshots, and the amount of difference data written to a disk between each snapshot. LVM-based space utilization differs depending on whether an LVM SR is upgraded or created as a new SR in XenServer. Upgraded LVM SRs will retain a base node that is fully inflated to the size of the virtual disk, and any subsequent snapshot or clone operations will provision at least one additional node that is fully inflated.
SRs can also be destroyed when no longer in use to free up the physical device, or forgotten to detach the SR from one XenServer host and attach it to another. See the section called “Destroying or forgetting a SR” for details. Note: When specifying StorageLink configuration for a XenServer host or pool, supply either the default credentials of username: admin and password: storagelink, or any custom credentials specified during installation of the StorageLink Gateway service.
xe vdi-create sr-uuid= type=user virtual-size= \ name-label= sm-config:type=raw 2. Attach the new virtual disk to a VM and use your normal disk tools within the VM to partition and format, or otherwise make use of the new disk. You can use the vbd-create command to create a new VBD to map the virtual disk into your VM. Converting between VDI formats It is not possible to do a direct conversion between the raw and VHD formats.
xe sr-probe type=lvmoiscsi device-config:target=192.168.1.10 device-config:targetIQN=iqn.192.168.1.10:filer1 \ Error code: SR_BACKEND_FAILURE_107 Error parameters: , The SCSIid parameter is missing or incorrect, \
SR type device-config parameter, in order of dependency Can be probed? Required for sr-create? netapp target No Yes username No Yes password No Yes chapuser No No chappassword No No aggregate No Yes FlexVols No No allocation No No asis No No server No Yes serverpath Yes Yes lvm device No Yes ext device No Yes equallogic target No Yes username No Yes password No Yes chapuser No No chappassword No No storagepool No Yes target No Yes storageSy
SR type device-config parameter, in order of dependency Can be probed? Required for sr-create? provision-type Yes No protocol Yes No provision-options Yes No raid-type Yes No * Aggregate probing is only possible at sr-create time. It needs to be done there so that the aggregate can be specified at the point that the SR is created. Storage pool probing is only possible at sr-create time. It needs to be done there so that the aggregate can be specified at the point that the SR is created.
dm-multipath tools in linux, device mapper nodes are not automatically created for all LUNs on the system, and it is only when LUNs are actively used by the storage management layer that new device mapper nodes are provisioned. It is unnecessary therefore to use any of the dm-multipath CLI tools to query or refresh DM table nodes in XenServer.
The maximum supported VDI sizes are: Storage type Maximum VDI size EXT3 2TB LVM 2TB Netapp 2TB EqualLogic 15TB ONTAP(NetApp) 12TB Local LVM The Local LVM type presents disks within a locally-attached Volume Group. By default, XenServer uses the local disk on the physical host on which it is installed. The Linux Logical Volume Manager (LVM) is used to manage VM storage. A VDI is implemented in VHD format in an LVM logical volume of the specified size. XenServer versions prior to 5.
Parameter Name Description Required? Device device name on the local host to use for the SR Yes To create a local ext SR on /dev/sdb use the following command: xe sr-create host-uuid= content-type=user \ name-label=<"Example Local EXT3 SR"> shared=false \ device-config:device=/dev/sdb type=ext udev The udev type represents devices plugged in using the udev device manager as VDIs. XenServer has two SRs of type udev that represent removable storage.
Parameter Name Description Optional? target the IP address or hostname of the EqualLogic array that hosts the SR no username the login username used to manage the LUNs on the array no password the login password used to manage the LUNs on the array no storagepool the storage pool name no chapuser the username to be used for CHAP authentication yes chappassword the password to be used for CHAP authentication yes allocation specifies whether to use thick or thin provisioning.
then the plug-in will use all of the space on the SAN for creating VDIs. When the SR is created, a small amount of meta data is created, called the SR Management Volume. This will be displayed as the smallest volume (30MB). All of the VDIs in the SR are created with 100% space reserved for snapshots by default. This will also override the Group Defaults that are set by the administrator from the EqualLogic GUI/CLI.
The easiest way to create NetApp SRs is to use XenCenter. See the XenCenter help for details. See the section called “Creating a shared NetApp SR over iSCSI” for an example of how to create them using the xe CLI. FlexVols NetApp uses FlexVols as the basic unit of manageable data. There are limitations that constrain the design of NetApp-based SRs.
Thick or thin provisioning When creating NetApp storage, you can also choose the type of space management used. By default, allocated space is thickly provisioned to ensure that VMs never run out of disk space and that all virtual allocation guarantees are fully enforced on the filer. Selecting thick provisioning ensures that whenever a VDI (LUN) is allocated on the filer, sufficient space is reserved to guarantee that it will never run out of space and consequently experience failed writes to disk.
• General information on NetApp products • Data ONTAP • FlexVol • FlexClone • RAID-DP • Snapshot • FilerView Creating a shared NetApp SR over iSCSI Device-config parameters for netapp SRs: Parameter Name Description Optional? target the IP address or hostname of the NetApp server that hosts the SR no port the port to use for connecting to the NetApp server that hosts the SR. Default is port 80.
Note: This works on new VDI creation in the selected FlexVol, or on all FlexVols during an SR scan and overrides any manual size adjustments made by the administrator to the SR FlexVols. To create a NetApp SR, use the following command. xe sr-create host-uuid= content-type=user \ name-label=<"Example shared NetApp SR"> shared=true \ device-config:target=<192.168.1.
HBAs are identical to those for Fibre Channel HBAs, both of which are described in the section called “Creating a shared LVM over Fibre Channel / iSCSI HBA or SAS SR (lvmohba)”. Shared iSCSI support using the software iSCSI initiator is implemented based on the Linux Volume Manager (LVM) and provides the same performance benefits provided by LVM VDIs in the local disk case.
Once the HBA is physically installed into the XenServer host, use the following steps to configure the HBA: 1. Set the IP networking configuration for the HBA. This example assumes DHCP and HBA port 0. Specify the appropriate values if using static IP addressing or a multi-port HBA. /opt/QLogic_Corporation/SANsurferiCLI/iscli -ipdhcp 0 2. Add a persistent iSCSI target to port 0 of the HBA. /opt/QLogic_Corporation/SANsurferiCLI/iscli -pa 0 3.
Parameter Name Description Optional? chapuser the username to be used for CHAP authentication no chappassword the password to be used for CHAP authentication no port the network port number on which to query the target no usediscoverynumber the specific iscsi record index to use no To create a shared lvmoiscsi SR on a specific LUN of an iSCSI target use the following command.
xe sr-probe type=lvmohba \ host-uuid=1212c7b3-f333-4a8d-a6fb-80c5b79b5b31 Error code: SR_BACKEND_FAILURE_90 Error parameters: , The request is missing the device parameter, \
Note: You can use the BRAND_CONSOLE; Repair Storage Repository function to retry the PBD creation and plugging portions of the sr-create operation. This can be valuable in cases where the LUN zoning was incorrect for one or more hosts in a pool when the SR was created. Correct the zoning for the affected hosts and use the Repair Storage Repository function instead of removing and re-creating the SR. NFS VHD The NFS VHD type stores disks as VHD files on a remote NFS filesystem.
mode export. Asynchronous exports acknowledge writes that are not actually on disk, and so administrators should consider the risks of failure carefully in these situations. The XenServer NFS implementation uses TCP by default. If your situation allows, you can configure the implementation to use UDP in situations where there may be a performance benefit. To do this, specify the device-config parameter useUDP=true at SR creation time.
XenServer support for Fibre Channel does not support direct mapping of a LUN to a VM. HBA-based LUNs must be mapped to the host and specified for use in an SR. VDIs within the SR are exposed to VMs as standard block devices. Citrix StorageLink Gateway (CSLG) SRs The CSLG storage repository allows use of the Citrix StorageLink service for native access to a range of iSCSI and Fibre Channel arrays and automated fabric/initiator and array configuration features.
Parameter name Description Optional? storagePoolId The storage pool ID within the specified storage system to use for allocating storage No username The username to use for connection to the StorageLink service Yes * password The password to use for connecting to the StorageLink service Yes * cslport The port to use for connecting to the StorageLink service Yes * chapuser The username to use for CHAP authentication Yes chappassword The password to use for CHAP authentication Yes prot
Parameter name Description Optional? physical-size The total size of the SR in MB. Each pool will be created with a size equal to physical-size divided by pool-count. Yes * * Required when specifying the sm-config:pool-count parameter Note: When a new NetApp SR is created using StorageLink, by default a single FlexVol is created for the SR that contains all LUNs created for the SR.
xe sr-probe type=cslg device-config:target=192.168.128.
You can use grep to filter the sr-probe output to just the storage pool IDs xe sr-probe type=cslg device-config:target=192.168.128.10 | grep storageSystemId EMC__CLARIION__APM00074902515 HP__EVA__50014380013C0240 NETAPP__LUN__0AD4F00A 4.
Destroying or forgetting a SR You can destroy an SR, which actually deletes the contents of the SR from the physical media. Alternatively you can forget an SR, which allows you to re-attach the SR, for example, to another XenServer host, without removing any of the SR contents. In both cases, the PBD of the SR must first be unplugged. Forgetting an SR is the equivalent of the SR Detach operation within XenCenter. 1.
Resizing an SR If you have resized the LUN on which a iSCSI or HBA SR is based, use the following procedures to reflect the size change in XenServer: 1. iSCSI SRs - unplug all PBDs on the host that reference LUNs on the same target. This is required to reset the iSCSI connection to the target, which in turn will allow the change in LUN size to be recognized when the PBDs are replugged. 2. HBA SRs - reboot the host.
1. Shutdown the VM. 2. Use the xe CLI to identify the UUIDs of the VDIs to be moved. If the VM has a DVD drive its vdi-uuid will be listed as and can be ignored. xe vbd-list vm-uuid= Note: The vbd-list command displays both the VBD and VDI UUIDs. Be sure to record the VDI UUIDs rather than the VBD UUIDs. 3. In XenCenter select the VM's Storage tab. For each VDI to be moved, select the VDI and click the Detach button. This step can also be done using the vbd-destroy command.
Remember to set the scheduler to cfq on the SR, and to ensure that the PBD has been re-plugged in order for the scheduler change to take effect. The first parameter is qos_algorithm_type. This parameter needs to be set to the value ionice, which is the only type of QoS algorithm supported for virtual disks in this release. The QoS parameters themselves are set with key/value pairs assigned to the qos_algorithm_param parameter.
Configuring VM memory When a VM is first created, it is allocated a fixed amount of memory. To improve the utilization of physical memory in your XenServer environment, you can use Dynamic Memory Control (DMC), a memory management feature that enables dynamic reallocation of memory between VMs. XenCenter provides a graphical display of memory usage in its Memory tab. This is described in the XenCenter Help.
• Dynamic Minimum Memory: A lower memory limit that you assign to the VM. • Dynamic Higher Limit: An upper memory limit that you assign to the VM. For example, if the Dynamic Minimum Memory was set at 512 MB and the Dynamic Maximum Memory was set at 1024 MB this would give the VM a Dynamic Memory Range (DMR) of 512 - 1024 MB, within which, it would operate. With DMC, XenServer guarantees at all times to assign each VM memory within its specified DMR.
1. Target Mode: The administrator specifies a memory target for the guest.XenServer adjusts the guest's memory allocation to meet the target. Specifying a target is particularly useful in virtual server environments, and in any situation where you know exactly how much memory you want a guest to use. XenServer will adjust the guest's memory allocation to meet the target you specify. 2.
Operating System Supported Memory Limits x64 ≥ 2 GB ≤ 32 GB 4.5 - 4.8 x86 ≥ 256 MB ≤ 16 GB 5.0 - 5.4 x86 x64 ≥ 512 MB ≤ 16 GB 4.5 - 4.8 x86 ≥ 256 MB ≤ 16 GB 5.0 - 5.4 x86 x64 ≥ 512 MB ≤ 16 GB Oracle Enterprise Linux 5.0 - 5.
1. Find the uuid of the required VM: xe vm-list 2. Note the uuid, and then run the command param-name=memory-dynamic: xe vm-param-get uuid= param-name=memory-dynamic-{min,max} For example, the following displays the dynamic maximum memory properties for the VM with uuid beginning ec77 xe vm-param-get uuid= \ ec77a893-bff2-aa5c-7ef2-9c3acf0f83c0 \ param-name=memory-dynamic-max; 134217728 This shows that the static maximum memory for this VM is 134217728 bytes (128MB).
Update individual memory properties Warning: Citrix advises not to change the static minimum level as this is set at the supported level per operating system – refer to the memory constraints table for more details. Update the dynamic memory properties of a VM. 1. Find the uuid of the required VM: xe vm-list 2.
Networking This chapter discusses how physical network interface cards (NICs) in XenServer hosts are used to enable networking within Virtual Machines (VMs). XenServer supports up to 16 physical network interfaces (or up to 16 of bonded network interfaces) per XenServer host and up to 7 virtual network interfaces per VM. Note: XenServer provides automated configuration and management of NICs using the xe command line interface (CLI).
Network objects There are three types of server-side software objects which represent networking entities. These objects are: • A PIF, which represents a physical network interface on a XenServer host. PIF objects have a name and description, a globally unique UUID, the parameters of the NIC that they represent, and the network and server they are connected to. • A VIF, which represents a virtual interface on a Virtual Machine.
Using VLANs with dedicated storage NICs Dedicated storage NICs can be configured to use native VLAN / access mode ports as described above for management interfaces, or with trunk ports and XenServer VLANs as described above for virtual machines. To configure dedicated storage NICs, see the section called “Configuring a dedicated storage NIC”.
Note: Bonding is set up with an Up Delay of 31000ms and a Down Delay of 200ms. The seemingly long Up Delay is purposeful because of the time taken by some switches to actually start routing traffic. Without it, when a link comes back after failing, the bond might rebalance traffic onto it before the switch is ready to pass traffic. If you want to move both connections to a different switch, move one, then wait 31 seconds for it to be used again before moving the other.
• use an internal network • support advanced operations such as VLANs or NIC bonding To add or remove networks using XenCenter, refer to the XenCenter online Help. To add a new network using the CLI 1. Open the XenServer host text console. 2. Create the network with the network-create command, which returns the UUID of the newly created network: xe network-create name-label= At this point the network is not connected to a PIF and therefore is internal.
xe vlan-create network-uuid= pif-uuid= vlan=5 5. Attach VM VIFs to the new network. See the section called “Creating networks in a standalone server” for more details. Creating NIC bonds on a standalone host Citrix recommends using XenCenter to create NIC bonds. For details, refer to the XenCenter help. This section describes how to use the xe CLI to create bonded NIC interfaces on a standalone XenServer host.
8. Use the pif-reconfigure-ip command to remove the IP address configuration from the non-bonded PIF previously used for the management interface. This step is not strictly necessary but might help reduce confusion when reviewing the host networking configuration. xe pif-reconfigure-ip uuid= mode=None 9. Move existing VMs to the bond network using the vif-destroy and vif-create commands.
Warning: Do not attempt to create network bonds while HA is enabled. The process of bond creation will disturb the in-progress HA heartbeating and cause hosts to self-fence (shut themselves down); subsequently they will likely fail to reboot properly and will need the host-emergency-ha-disable command to recover. Adding NIC bonds to new resource pools 1. Select the host you want to be the master. The master host belongs to an unnamed pool by default.
a. Use the host-list command to find the UUID of the host being configured: xe host-list b. Use the pif-list command to determine the UUID of bond PIF on the new host. Include the hostuuid parameter to list only the PIFs on the host being configured: xe pif-list network-name-label= host-uuid= c. Use the pif-reconfigure-ip command to configure the desired management interface IP address settings for the bond PIF.
To add NIC bonds to the pool master and other hosts 1. Use the network-create command to create a new pool-wide network for use with the bonded NICs. This step should only be performed once per pool. The UUID of the new network is returned. xe network-create name-label= 2. Use XenCenter or the vm-shutdown command to shut down all VMs in the host pool to force all existing VIFs to be unplugged from their current networks. The existing VIFs will be invalid after the bond is enabled.
Configuring a dedicated storage NIC XenServer allows use of either XenCenter or the xe CLI to configure and dedicate a NIC to specific functions, such as storage traffic. Assigning a NIC to a specific function will prevent the use of the NIC for other functions such as host management, but requires that the appropriate network configuration be in place in order to ensure the NIC is used for the desired traffic.
• changing the hostname • adding or removing DNS servers • changing IP addresses • changing which NIC is used as the management interface • adding a new physical NIC to the server Hostname The system hostname is defined in the pool-wide database and modified using the xe host-set-hostnamelive CLI command as follows: xe host-set-hostname-live uuid= host-name=example The underlying control domain hostname changes dynamically to reflect the new hostname.
2. Use the host-list CLI command to confirm that the member host has successfully reconnected to the master host by checking that all the other XenServer hosts in the pool are visible: xe host-list Changing the IP address of the master XenServer host requires additional steps because each of the member hosts uses the advertised IP address of the pool master for communication and will not know how to contact the master when its IP address changes.
Warning: Once the management interface is disabled, you will have to log in on the physical host console to perform management tasks and external interfaces such as XenCenter will no longer work. Adding a new physical NIC Install a new physical NIC on a XenServer host in the usual manner. Then, after restarting the server, run the xe CLI command pif-scan to cause a new PIF object to be created for the new NIC.
1. Use XenCenter or the vm-shutdown command to shut down all VMs in the pool to force existing VIFs to be unplugged from their networks. xe vm-shutdown uuid= 2. Use the host-management-disable command to disable the management interface: xe host-management-disable 3. Use the pif-forget command to remove the two incorrect PIF records: xe pif-forget uuid=1ef8209d-5db5-cf69-3fe6-0e8d24f8f518 xe pif-forget uuid=829fd476-2bbb-67bb-139f-d607c09e9110 4.
Finally, re-plug the PIF or reboot the host for the change to take effect. Recovering from a bad network configuration In some cases it is possible to render networking unusable by creating an incorrect configuration. This is particularly true when attempting to make network configuration changes on a member XenServer host.
Workload Balancing What's New? This topic describes new features and changes from the previous release of Workload Balancing. New Features Workload Balancing now provides a series of features that work together to facilitate reducing power during off-peak work hours.
• Improved Error Messages. Improved error messages make issues easier to understand. Also, error messages are now documented with suggested actions. In addition, this release of Workload Balancing is aware of the XenServer Dynamic Memory Control feature — Workload Balancing considers a virtual machine's memory range and target when providing virtualmachine placement, host evacuation, and pool optimization recommendations.
Workload Balancing works by evaluating the utilization of workloads across a pool and, when a host exceeds its threshold, relocating it to a less-taxed host in the pool. To rebalance workloads, Workload Balancing moves workloads to keep hosts in balance. To ensure the rebalancing and placement recommendations align with your environment's needs, you can configure Workload Balancing to optimize workloads for either resource performance or to maximize density.
• Command Line. If you install Workload Balancing from the command line, the prerequisites are not checked. For Msiexec properties, see CTX124480. When you install Workload Balancing, Setup creates the data store by installing it across the network onto the database. (You do not need to run Workload Balancing Setup locally on the database server.) After installation, you must set up Workload Balancing server communication settings before you can use Workload Balancing to optimize workloads.
• Memory: 2GB recommended (1GB of RAM required) • Disk Space: • SQL Server Express: 4GB • SQL Server: 20GB (approximate amount consumed) Citrix recommends that the Workload Balancing server have a minimum of a dual-core processor. Workload Balancing Data Store Requirements This topic provides information about the SQL Server versions and configurations that Workload Balancing supports. It also provides information about additional compatibility and authentication requirements.
• SQL Server and Windows Authentication mode (Mixed Mode authentication) If you create an account on the database for use during Setup, the account must have sysadmin privileges for the database instance where you want to create the Workload Balancing data store.
WLB Access Control Permissions When Role Based Access Control (RBAC) is implemented in your environment, all user roles can display the WLB tab. However, not all roles can perform all operations.
To install Workload Balancing server The following procedure installs Workload Balancing on one computer: 1. Launch the Workload Balancing Setup wizard from Autorun.exe, and select the Workload Balancing option. Note: If you are installing on Windows Vista, Windows Server 2008, or Windows 7 and the User Account Control (UAC) is enabled, right-click Autorun.exe and select Run as administrator.
• SQL Server Authentication. To select this option, you must have configured SQL Server to support Mixed Mode authentication. Note: Citrix recommends clicking Test Connect to ensure Setup can use the credentials you provided to contact the database server. 8. In the Database Information page, select Install a new Workload Balancing data store and type the name you want to assign to the Workload Balancing database in SQL Server. The default database name is WorkloadBalancing. 9.
• If you used the Setup wizard, the log is at C:\Documents and Settings\username\Local Settings\Temp \msibootstrapper2CSM_MSI_Install.log (by default). On Windows Vista and Windows Server 2008, this log is at C:\Users\username\AppData\Local\Temp\msibootstrapper2CSM_MSI_Install.log. User name is the name of the user logged on during installation. • If you used the Setup properties (Msiexec), the log is at C:\log.txt (by default) or wherever you specified for Setup to create it.
The time it takes to upgrade the server may be affected by the distribution of the database file group. Additional time may be required to perform file group moves during the upgrade. In addition, the size of the database affects the time required to perform an upgrade. Upgrading Workload Balancing on the Same Operating System If you only want to upgrade the Workload Balancing server software and you are not upgrading operating system on its server, do the following: 1.
After Workload Balancing is running for a period of time, if you do not receive optimal placement recommendations, Citrix strongly recommends you evaluate your performance thresholds as described in the section called “Using Workload Balancing Reports for Tasks”. It is critical to set Workload Balancing to the correct thresholds for your environment or its recommendations might not be appropriate.
This must be the account or group that was configured during the installation of the Workload Balancing Server. For information, see the section called “Authorization for Workload Balancing ”. 6. In the XenServer Credentials section, enter the user name and password for the pool you are configuring (typically the password for the pool master). Workload Balancing will use these credentials to connect to the computers running XenServer in that pool.
Configuring Antivirus Software By default, most antivirus programs are configured to scan all files on the hard disk. If an antivirus program scans the frequently active Workload Balancing database, it impedes or slows down the normal operation of Workload Balancing. Consequently, you must configure antivirus software running on your Workload Balancing servers to exclude specific processes and files.
Before you edit your thresholds, you might find it handy to generate a the section called “Host Health History” report for each physical host in the pool. You can use either the Workload Balancing Configuration properties in XenCenter or the XE commands to modify the configuration settings. To update the credentials XenServer and the Workload Balancing server use to communicate, see Updating Workload Balancing Credentials. To display the Workload Balancing Configuration dialog box 1.
weekdays or weekends as a group when specifying days. For the hour, you can choose any hour and you can specify minutes in 15-minute intervals. To set an optimization mode for all time periods 1. In the Resources pane of XenCenter, select XenCenter > your-resource-pool. 2. In the Properties pane, click the WLB tab. 3. On the WLB tab, click Configure WLB. 4. In the left pane, click Optimization Mode. 5.
Accepting Optimization Recommendations Automatically Workload Balancing lets you configure for it to accept optimization recommendations on your behalf and perform the optimization actions it recommends automatically. This feature is required when you configure for hosts with light workloads to be powered down automatically (Maximum Density mode with Power Management).
If Workload Balancing detects a performance issue while the pool is in Maximum Density mode, it attempts to address the issue by recommending migrating workloads among the powered-on hosts. If Workload Balancing cannot resolve the issue using this method, it attempts to power-on a host. (Workload Balancing determines which host(s) to power-on by applying the same criteria it would if the optimization mode was set to Maximum Performance.
better with certain types of hardware), consider if you need to locate the virtual machines hosting these workloads in different pools. Because power management and VM consolidation are managed at the pool level, you should design pools so they contain workloads that you want consolidated at the same rate, factoring in considerations such as those discussed in the section called “Configuring Optimization Intervals, Report Subscriptions, and Data Storage”. • Exclude Hosts from Workload Balancing.
Workload Balancing determines whether to recommend relocating a workload and whether a physical host is suitable for a virtual-machine workload by evaluating: • Whether a resource's critical threshold is met on the physical host • (If the critical threshold is met) the importance assigned to a resource Note: To prevent data from appearing artificially high, Workload Balancing evaluates the daily averages for a resource and smooths utilization spikes.
The effect of the weighting varies according to the placement strategy you selected. For example, if you selected Maximum Performance and you set Network Writes towards Less Important, if the Network Writes on that server exceed the critical threshold you set, Workload Balancing still makes a recommendation to place a virtual machine's workload on a server but does so with the goal of ensuring performance for the other resources.
2. In the Properties pane, click the WLB tab. 3. In the WLB tab, click Configure WLB. 4. In the left pane, select Excluded Hosts. 5. In Excluded Hosts page, select the hosts for which you do not want WLB to recommend alternate placements and optimizations.
balancing from generating "artificial" recommendations for this period by setting the Relocation interval to more than an hour. • If server loads and activity increase gradually in your environment, you may want to increase the number of minutes for the optimization interval. When Automation is configured, it is especially important to be careful when modifying the optimization interval.
Example recommendation: [1] Move VM07 to host18 [2] Move VM07 to host20 [3] Move VM07 to host18. If 3 was specified for x, this is an example where Workload Balancing would not automatically apply the recommendation yet. The recommendations have to be exact: notice the move to the host is not the same for all three recommendations. When you set the aggressiveness setting higher (for example, Medium), Workload Balancing will be less strict.
If you want to use the default report delivery mechanism, no additional component installations or configurations are required. To configure report subscriptions 1. In the Resources pane of XenCenter, select XenCenter > your-resource-pool. 2. In the Properties pane, click the WLB tab. 3. In the WLB tab, click Configure WLB. 4. In the left pane, click Advanced. 5.
its historical records of performance metrics and your placement strategy. The optimal server is the server with the most stars. • One of the servers with star ratings listed under the Optimal Server command. Five stars indicates the most-recommended (optimal) server and five empty stars indicates the least-recommended server. Accepting Optimization Recommendations Workload Balancing provides recommendations about ways you can move virtual machines to optimize your environment.
• Uninstalling Workload Balancing Disabling Workload Balancing You can disable Workload Balancing for a resource pool, either temporarily or permanently: • Temporarily. Disabling Workload Balancing temporarily stops XenCenter from displaying recommendations for the specified resource pool. When you disable Workload Balancing temporarily, data collection stops for that resource pool. • Permanently.
You must enter all the information that you would normally enter when you initially configure a resource pool for use with Workload Balancing. For information, see the section called “Initializing Workload Balancing” or the section called “Updating Workload Balancing Credentials”.
c. In the WLB Server Credentials section, enter the user name (for example, workloadbalancing_user) and password the computers running XenServer will use to connect to the Workload Balancing server. This must be the account or group that was configured during the installation of the Workload Balancing Server. For information, see the section called “Authorization for Workload Balancing ”. d.
If an optimal server is not available, the words Click here to suspend the VM appear in the Enter Maintenance Mode dialog box. In this case, Workload Balancing does not recommend a placement because no host has sufficient resources to run this virtual machine. You can either suspend this virtual machine or exit Maintenance Mode and suspend a virtual machine on another host in the same pool.
at which you want to generate the report, the days on which you want to generate it, and when you want to start and stop automatic report delivery. Using Workload Balancing Reports for Tasks The Workload Balancing reports can help you perform capacity planning, determine virtual server health, and evaluate the effectiveness of your configured threshold levels.
• Deliver On. The day of the week you want Workload Balancing to generate and deliver the report. The schedule you are creating does not become active until you set this field to a day. Leaving this field at None means that no reports will be generated for this subscription. • Starting. The date you want Workload Balancing to begin generating the report. • Ending. The date you want Workload Balancing to stop generating the report.
Export. Lets you export the report as an Acrobat (.PDF) file or as an Excel file with a .XLS extension. Find. Lets you search for a word in a report, such as the name of a virtual machine. To print a Workload Balancing report Citrix recommends printing Workload Balancing reports in Landscape orientation. 1. After generating the report, click Page Setup. Page Setup also lets you control the margins and paper size. 2. In the Page Setup dialog, select Landscape and click OK. 3. (Optional.
Table 4. Report Toolbar Buttons Document Map. Lets you display a document map that helps you navigate through long reports. Page Forward/Back. Lets you move one page ahead or back in the report. Back to Parent Report. Lets you return to the parent report when working with drill-through reports. Stop Rendering. Cancels the report generation. Refresh. Lets you refresh the report display. Print.
Workload Balancing displays the average for each hour for the time period you set. The data point is based on a utilization average for that hour for all days in the time period. For example, in a report for May1, 2009 to May 15, 2009, the Average CPU Usage data point represents the resource utilization of all fifteen days at 12:00 hours combined together as an average.
• Event Action. The action that occurred. For definitions of these actions, see the section called “Audit Log Event Names”. • Succeeded. This provides that status of the action (that is, whether or not it was successful). Audit Log Event Names The following table defines some events that appear frequently in the XenServer Audit Log report. For additional event definitions, see the events section of the Citrix XenServer Management API Event Name Definition task.create Created a new task object. task.
Note: The High, Medium, and Low threshold ranges are based on the Critical threshold value you set when you initialized Workload Balancing. Pool Health History This report provides a line graph of resource utilization on all physical hosts in a pool over time. It lets you see the trend of resource utilization - if it tends to be increasing in relation to your thresholds (Critical, High, Medium, and Low).
• To Host. The physical server where the virtual machine was moved. • Time. The time when the optimization occurred. Virtual Machine Motion History This line graph displays the number of times virtual machines moved on a resource pool over a period of time. It indicates if a move resulted from an optimization recommendation and to which host the virtual machine moved. This report also indicates the reason for the optimization. You can use this report to audit the number of moves on a pool.
Backup and recovery This chapter presents the functionality designed to give you the best chance to recover your XenServer from a catastrophic failure of hardware or software, from lightweight metadata backups to full VM backups and portable SRs. Backups Citrix recommends that you frequently perform as many of the following backup procedures as possible to recover from possible server and/or software failure. To backup pool metadata 1. Run the command: xe pool-dump-database file-name= 2.
xe vm-export vm= filename= --metadata Full metadata backup and disaster recovery (DR) This section introduces the concept of Portable Storage Repositories (Portable SRs), and explains how they work and how to use them as part of a DR strategy. DR and metadata backup overview XenServer 5.6 introduces the concept of Portable SRs.
On the XenServer host menu-driven text console, under the Backup, Update and Restore menu there are options which provide a more user-friendly interface to these scripts. The operations should only be performed on the pool master. You can use these menu options to perform 3 operations: • Schedule a regular metadata backup to the default pool SR, either daily, weekly or monthly.
7. Every time a new SR is created the storage is checked to see if it contains an existing SR. If so, an option is presented allowing re-attachment of the existing SR. If this option is not displayed the parameters specified during SR creation are not correct. 8. Select Reattach. 9. Select the new SR in the tree view and then select the Storage tab to view the existing VDIs present on the SR. 10.
storage types the storage repository must have been upgraded if it was created on a previous version of XenServer and the volume must be in the default format (type=raw volumes cannot be snapshotted). The snapshotting operation is a 2 step process: • Capturing metadata as a template. • Creating a VDI snapshot of the disk(s).
Creating a snapshot with memory Run the vm-checkpoint command, giving a descriptive name for the snapshot with memory, so that you can identify it later: xe vm-checkpoint vm= new-name-label= When XenServer has completed creating the snapshot with memory - its uuid will be displayed.
For example, specifying power-state=halted will select all VMs whose power-state field is equal to 'halted'. Where multiple VMs are matching, the option --multiple must be specified to perform the operation. The full list of fields that can be matched can be obtained by the command xe vm-list params=all.
1. Run the snapshot-list command to find the UUID of the snapshot or checkpoint that you want to revert to: xe snapshot-list 2. Note the UUID of the snapshot, and then run the snapshot-uninstall command to remove it: xe snapshot-uninstall snapshot-uuid= 3. This command alerts you to the VM and VDIs that will be deleted. Type yes to confirm.
This will list all of the templates on the XenServer host. Exporting a snapshot to a template When you export a VM snapshot, a complete copy of the VM (including disk images) is stored as a single file on your local machine, with a .xva file extension. To do this: 1.
The more VBDs attached to a VM, the more likely it is that this timeout may be reached. Citrix recommends attaching no more that 2 VBDs to a VM to avoid reaching the timeout. However, there is a workaround to this problem. The probability of taking a successful VSS based snapshot of a VM with more than 2 VBDs can be increased manifold, if all the VDIs for the VM are hosted on different SRs.
VSS snap of volumes hosted on dynamic disks in the Windows Guest : The vm-snapshot-with-quiesce CLI and the XenServer VSS hardware provider do not support snapshots of volumes hosted on dynamic disks on the Windows VM. Coping with machine failures This section provides details of how to recover from various failure scenarios. All failure recovery scenarios require the use of one or more of the backup types listed in the section called “Backups”.
If you repair or replace the server that was the original master, you can simply bring it up, install the XenServer host software, and add it to the pool. Since the XenServer hosts in the pool are enforced to be homogeneous, there is no real need to make the replaced server the master. When a member XenServer host is transitioned to being a master, you should also check that the default pool storage repository is set to an appropriate value.
xe pool-emergency-transition-to-master xe pool-recover-slaves 2. If the commands succeed, restart the VMs. To restore a pool with all hosts failed 1. Run the command: xe pool-restore-database file-name= Warning: This command will only succeed if the target machine has an appropriate number of appropriately named NICs. 2.
Monitoring and managing XenServer XenServer and XenCenter provide access to alerts that are generated when noteworthy things happen. XenCenter provides various mechanisms of grouping and maintaining metadata about managed VMs, hosts, storage repositories, and so on. Note: Full monitoring and alerting functionality is only available is only available with XenServer Advanced edition or above. To find out about XenServer editions and how to upgrade, visit the Citrix website here.
• license_does_not_support_pooling • pbd_plug_failed_on_server_start • pool_master_transition The following alerts appear on the performance graphs in XenCenter.
alarm_trigger_sense high if alarm_trigger_level is a maximum value otherwise low if the alarm_trigger_level is a minimum value.
Alerts generated from XenServer can also be automatically e-mailed to the resource pool administrator, in addition to being visible from the XenCenter GUI. To configure this, specify the email address and SMTP server: pool:other-config:mail-destination= pool:other-config:ssmtp-mailhub=
Troubleshooting If you experience odd behavior, application crashes, or have other issues with a XenServer host, this chapter is meant to help you solve the problem if possible and, failing that, describes where the application logs are located and other information that can help your Citrix Solution Provider and Citrix track and resolve the issue. Troubleshooting of installation issues is covered in the XenServer Installation Guide.
xe host-param-set uuid= logging:syslog_destination= 2. Issue the command: xe host-syslog-reconfigure uuid= to enforce the change. (You can also execute this command remotely by specifying the host parameter.) XenCenter logs XenCenter also has client-side log. This file includes a complete description of all operations and errors that occur when using XenCenter.
Appendix A. Command line interface This chapter describes the XenServer command line interface (CLI). The xe CLI enables the writing of scripts for automating system administration tasks and allows integration of XenServer into an existing IT infrastructure. The xe command line interface is installed by default on XenServer hosts and is included with XenCenter. A stand-alone remote CLI is also available for Linux. On Windows, the xe.exe CLI executable is installed along with XenCenter.
Example: On the local XenServer host: xe vm-list Example: On the remote XenServer host: xe vm-list -user -password -server Shorthand syntax is also available for remote connection arguments: -u username -pw password -pwf password file -p port -s server Example: On a remote XenServer host: xe vm-list -u -pw -s Arguments are also taken from the environment variable XE_EXTRA_ARGS, in the form of comma-separated key/value pairs.
l, pressing TAB a second time will list the possibilities. This is particularly useful when specifying object UUIDs in commands. Note: When executing commands on a remote XenServer host, tab completion does not normally work. However if you put the server, username, and password in an environment variable called XE_EXTRA_ARGS on the machine from which you are entering the commands, tab completion is enabled. See the section called “Basic xe syntax” for details.
• vm Note that not every value of has the full set of -param- commands; some have just a subset. Parameter types The objects that are addressed with the xe commands have sets of parameters that identify them and define their states. Most parameters take a single value. For example, the name-label parameter of a VM contains a single string value.
-param-get uuid= param-name= [param-key=] Returns the value of a particular parameter. If the parameter is a map, specifying the param-key will get the value associated with that key in the map. If param-key is not specified, or if the parameter is a set, it will return a string representation of the set or map. -param-set uuid= param=... Sets the value of one or more parameters. -param-add uuid= param-name= [=...
For scripting, a useful technique is passing --minimal on the command line, causing xe to print only the first field in a comma-separated list. For example, the command xe vm-list --minimal on a XenServer host with three VMs installed gives the three UUIDs of the VMs, for example: a85d6717-7264-d00e-069b-3b1d19d56ad9,aaa3eec5-9499-bcf3-4c03-af10baea96b7, \ 42c044de-df69-4b30-89d9-2c199564581d xe command reference This section provides a reference to the xe commands.
CD commands Commands for working with physical CD/DVD drives on XenServer hosts.
Parameter Name Description Type missing true if SR scan operation reported this CD as not present on disk read only other-config A list of key/value pairs that specify additional configuration parameters for the CD read/write map parameter location The path on which the device is mounted read only managed true if the device is managed read only xenstore-data Data to be inserted into the xenstore tree read only map parameter sm-config names and descriptions of storage manager device config
Parameter Name Description Type uuid The unique identifier/object reference for the console read only vm-uuid The unique identifier/object reference of the VM this console is open on read only vm-name-label The name of the VM this console is open on read only protocol Protocol this console uses.
Blocks other commands from executing until an object exists that satisfies the conditions given on the command line. x=y means "wait for field x to take value y", and x=/=y means "wait for field x to take any value other than y". Example: wait for a specific VM to be running xe event-wait class=vm name-label=myvm power-state=running Blocks other commands until a VM called myvm is in the power-state "running.
Parameter Name Description Type enabled false if disabled which prevents any new VMs from starting on them, which prepares the XenServer hosts to be shut down or rebooted; true if the host is currently enabled read only API-version-major major version number read only API-version-minor minor version number read only API-version-vendor identification of API vendor read only API-version-vendor-implementation details of vendor implementation read only map parameter logging logging configurat
Parameter Name Description Type host-metrics-live true if the host is operational read only logging The syslog_destination key can be set to the hostname of a remote listening syslog service. read/write map parameter allowed-operations lists the operations allowed in this state. This list is advisory only and the server state may have changed by the time this field is read by a client. read only set parameter current-operations lists the operations currently in process.
Parameter Name Description Type uuid The unique identifier/object reference for the CPU read only number the number of the physical CPU core within the XenServer host read only vendor the vendor string for the CPU name, for example, "GenuineIntel" read only speed The CPU clock speed, in Hz read only modelname the vendor string for the CPU model, for example, "Intel(R) Xeon(TM) CPU 3.
backup file. The command should only be used from a remote off-host machine where you have space to hold the backup file. host-bugreport-upload host-bugreport-upload [=...] [url=] [http-proxy=] Generate a fresh bug report (using xen-bugtool, with all optional files included) and upload to the Citrix Support ftp site or some other location.
Reconfigure the management interface of this XenServer host. Use this command only if the XenServer host is in emergency mode, meaning that it is a member in a resource pool whose master has disappeared from the network and could not be contacted for some number of retries. host-enable host-enable [=...] Enables the specified XenServer hosts, which allows new VMs to be started on them.
details. If not specified, all system status information is saved in the file. The parameter output may be tar.bz2 (the default) or zip; if this parameter is not specified, the file is saved in tar.bz2 form. The host(s) on which this operation should be performed are selected using the standard selection mechanism (see host selectors above). host-get-system-status-capabilities host-get-system-status-capabilities [=...
The host(s) on which this operation should be performed are selected using the standard selection mechanism (see host selectors above). host-is-in-emergency-mode host-is-in-emergency-mode Returns true if the host the CLI is talking to is currently in emergency mode, false otherwise. This CLI command works directly on slave hosts even with no master host present.
host-license-view host-license-view [host-uuid=] For XenServer (free edition), displays the contents of the XenServer host license. Note: This command only applies to free XenServer. XenServer 5.6 Advanced edition and higher use the hostapply-edition, license-server-address and license-server-port commands. For these editions licensing has changed. They now use the licensing model described in the Citrix XenServer 5.6 Installation Guide.
Be careful when using this CLI command off-host and ensure that you have network connectivity on the new interface. Use xe pif-reconfigure to set one up first. Otherwise, subsequent CLI commands will reach the XenServer host. host-power-on host-power-on [host= ] Turns on power on XenServer hosts with Host Power On functionality enabled. Before using this command, host-set-power-on must be enabled on the host.
Change the hostname of the XenServer host specified by host-uuid. This command persistently sets both the hostname in the control domain database and the actual Linux hostname of the XenServer host. Note that hostname is not the same as the value of the name_label field. host-shutdown host-shutdown [=...] Shut down the specified XenServer hosts.
Set the output of the specified logger. Log messages are filtered by the subsystem in which they originated and the log level of the message. For example, send debug logging messages from the storage manager to a file by running the following command: xe log-set-output key=sm level=debug output= The optional parameter key specifies the particular logging subsystem. If this parameter is not set, it will default to all logging subsystems.
Network commands Commands for working with networks. The network objects can be listed with the standard object listing command (xe network-list), and the parameters manipulated with the standard parameter commands. See the section called “Low-level param commands” for details.
Parameter Name Description Type other-config:ethtool-sg set to on to enable scatter gather, off to disable read write other-config:ethtool-tso set to on to enable tcp segmentation offload, off to disable read write other-config:ethtool-ufo set to on to enable UDP fragment offload, off to disable read write other-config:ethtool-gso set to on to enable generic segmentation offload, off to disable read write blobs Binary data store read only network-create network-create name-label=
Parameter Name Description Type applied Whether or not the patch has been applied; true or false read only size Whether or not the patch has been applied; true or false read only patch-apply patch-apply uuid= Apply the specified patch file. patch-clean patch-clean uuid= Delete the specified patch file from the XenServer host. patch-pool-apply patch-pool-apply uuid= Apply the specified patch to all XenServer hosts in the pool.
Parameter Name Description Type sr-uuid the storage repository that the PBD points to read only device-config additional configuration information that is provided to the SR-backend-driver of a host read only map parameter currently-attached True if the SR is currently attached on this host, False otherwise read only host-uuid UUID of the physical machine on which the PBD is available read only host The host field is deprecated. Use host_uuid instead.
The PIF objects can be listed with the standard object listing command (xe pif-list), and the parameters manipulated with the standard parameter commands. See the section called “Low-level param commands” for details.
Parameter Name Description Type host-name-label the name of the XenServer host to which this PIF is connected read only IP-configuration-mode type of network address configuration used; DHCP or static read only IP IP address of the PIF, defined here if IPconfiguration-mode is static; undefined if DHCP read only netmask Netmask of the PIF, defined here if IPconfiguration-mode is static; undefined if supplied by DHCP read only gateway Gateway address of the PIF, defined here if IP-configuratio
Parameter Name Description Type other-config:ethtool-rx set to on to enable receive checksum, off to disable read write other-config:ethtool-tx set to on to enable transmit checksum, off to disable read write other-config:ethtool-sg set to on to enable scatter gather, off to disable read write other-config:ethtool-tso set to on to enable tcp segmentation offload, off to disable read write other-config:ethtool-ufo set to on to enable udp fragment offload, off to disable read write other-con
pif-plug pif-plug uuid= Attempt to bring up the specified physical interface. pif-reconfigure-ip pif-reconfigure-ip uuid= [ mode= | mode= ] gateway= IP= netmask= [DNS=] Modify the IP address of the PIF. For static IP configuration, set the mode parameter to static, with the gateway, IP, and netmask parameters set to the appropriate values.
Parameter Name Description Type master the unique identifier/object reference of XenServer host designated as the pool's master read only default-SR the unique identifier/object reference of the default SR for the pool read/write crash-dump-SR the unique identifier/object reference of the SR where any crash dumps for pool members are saved read/write suspend-image-SR the unique identifier/object reference of the SR where suspended VMs on pool members are saved read/write other-config a list
Parameter Name Description Type blobs binary data store read only wlb-url Path to the WLB server read only wlb-username Name of the user of the WLB service read only wlb-enabled True is WLB is enabled read/write wlb-verify-cert True if there is a certificate to verify read/write pool-designate-new-master pool-designate-new-master host-uuid= Instruct the specified member XenServer host to become the master of an existing pool.
pool-ha-disable pool-ha-disable Disables the High Availability functionality on the resource pool. pool-join pool-join master-address=
master-username= master-password= Instruct a XenServer host to join an existing pool. pool-recover-slaves pool-recover-slaves Instruct the pool master to try and reset the master address of all members currently running in emergency mode.Parameter Name Description Type vendor name of the vendor who created this plugin read only copyright copyright statement for this SM plugin read only required-api-version minimum SM API version required on the XenServer host read only configuration names and descriptions of device configuration keys read only capabilities capabilities of the SM plugin read only driver-filename the filename of the SR driver. read only SR commands Commands for controlling SRs (storage repositories).
Parameter Name Description Type physical-size total physical size of the SR, in bytes read only type type of the SR, used to specify the SR backend driver to use read only content-type the type of the SR's content. Used to distinguish ISO libraries from other SRs. For storage repositories that store a library of ISOs, the content-type must be set to iso. In other cases, Citrix recommends that this be set either to empty, or the string user.
sr-introduce sr-introduce name-label= physical-size= type= content-type= uuid= Just places an SR record into the database. The device-config parameters are specified by deviceconfig:=, for example: xe sr-introduce device-config:= Note: This command is never used in normal operation.
Parameter Name Description Type name-description the description string of the Task read only resident-on the unique identifier/object reference of the host on which the task is running read only status current status of the Task read only progress if the Task is still pending, this field contains the estimated percentage complete, from 0. to 1. If the Task has completed, successfully or unsuccessfully, this should be 1.
Templates are essentially VMs with the is-a-template parameter set to true. A template is a "gold image" that contains all the various configuration settings to instantiate a specific VM. XenServer ships with a base set of templates, which range from generic "raw" VMs that can boot an OS vendor installation CD (RHEL, CentOS, SLES, Windows) to complete pre-configured OS instances (the "Demo Linux VM" template).
Parameter Name Description Type memory-dynamic-min dynamic minimum memory in bytes. Currently unused, but if changed the same constraints for memory-dynamic-max must be obeyed. read/write memory-static-max statically-set (absolute) maximum memory in bytes. This is the main value used to determine the amount of memory assigned to a VM. read/write memory-static-min statically-set (absolute) minimum memory in bytes.
Parameter Name Description Type VCPUs-params configuration parameters for the selected VCPU policy. read/write map parameter You can tune a VCPU's pinning with xe vm-param-set \ uuid= \ VCPUs-params:mask=1,2,3 A VM created from this template will then run on physical CPUs 1, 2, and 3 only.
Parameter Name Description Type actions-after-crash action to take if a VM based on this template crashes read/write console-uuids virtual console devices read only set parameter platform platform-specific configuration read/write map parameter allowed-operations list of the operations allowed in this state read only set parameter current-operations list of the operations that are currently in progress on this template read only set parameter allowed-VBD-devices list of VBD identifiers av
Parameter Name Description Type PV-bootloader name of or path to bootloader read/write PV-bootloader-args string of miscellaneous arguments for the bootloader read/write last-boot-CPU-flags describes the CPU flags on which a VM based on this template was last booted; not populated for a template read only resident-on the XenServer host on which a VM based on this template is currently resident; appears as for a template read only affinity a XenServer host which a VM based o
Parameter Name Description Type memory-actual the actual memory being used by a VM based on this template; 0 for a template read only VCPUs-number the number of virtual CPUs assigned to a VM based on this template; 0 for a template read only VCPUs-Utilization list of virtual CPUs and their weight read only map parameter os-version the version of the operating system for a VM based on this template; appears as for a template read only map parameter PV-drivers-version the ver
Parameter Name Description Type guest-metrics-last-updated timestamp when the last write to these fields was performed by the in-guest agent, in the form yyyymmddThh:mm:ss z, where z is the single-letter military timezone indicator, for example, Z for UTC (GMT) read only actions-after-shutdown action to take after the VM has shutdown read/write actions-after-reboot action to take after the VM has rebooted read/write possible-hosts list of hosts that could potentially host the VM read only HVM
Parameter Name Description Type blocked-operations lists the operations that cannot be performed on this template read/write map parameter last-boot-record record of the last boot parameters for this template, in XML format read only ha-always-run True if an instance of this template will always restarted on another host in case of the failure of the host it is resident on read/write ha-restart-priority 1, 2, 3 or best effort.
VBD commands Commands for working with VBDs (Virtual Block Devices). A VBD is a software object that connects a VM to the VDI, which represents the contents of the virtual disk. The VBD has the attributes which tie the VDI to the VM (is it bootable, its read/write metrics, and so on), while the VDI has the information on the physical attributes of the virtual disk (which type of SR, whether the disk is shareable, whether the media is read/write or read only, and so on).
Parameter Name Description Type storage-lock True if a storage-level lock was acquired read only status-code error/success code associated with the last attach operation read only status-detail error/success information associated with the last attach operation status read only qos_algorithm_type the QoS algorithm to use read/write qos_algorithm_params parameters for the chosen QoS algorithm read/write map parameter qos_supported_algorithms supported QoS algorithms for this VBD read only
Create a new VBD on a VM. Appropriate values for the device field are listed in the parameter allowed-VBD-devices on the specified VM. Before any VBDs exist there, the allowable values are integers from 0-15. If the type is Disk, vdi-uuid is required. Mode can be RO or RW for a Disk. If the type is CD, vdi-uuid is optional; if no VDI is specified, an empty VBD will be created for the CD. Mode must be RO for a CD. vbd-destroy vbd-destroy uuid= Destroy the specified VBD.
VDI parameters VDIs have the following parameters: Parameter Name Description Type uuid the unique identifier/object reference for the VDI read only name-label the name of the VDI read/write name-description the description string of the VDI read/write allowed-operations a list of the operations allowed in this state read only set parameter current-operations a list of the operations that are currently in progress on this VDI read only set parameter sr-uuid SR in which the VDI resides re
Parameter Name Description Type managed true if the VDI is managed read only xenstore-data data to be inserted into the xenstore tree (/local/domain/0/backend/ vbd///smdata) after the VDI is attached. This is generally set by the SM backends on vdi_attach.
allocated SR does become full, disk space must be made available either on the SR target substrate or by deleting unused VDIs in the SR. Note: Some SR types might round up the virtual-size value to make it divisible by a configured block size. vdi-destroy vdi-destroy uuid= Destroy the specified VDI. Note: In the case of Local VHD and NFS SR types, disk space is not immediately released on vdi-destroy, but periodically during a storage repository scan operation.
Produces a read-write version of a VDI that can be used as a reference for backup and/or template creation purposes. You can perform a backup from a snapshot rather than installing and running backup software inside the VM. The VM can continue running while external backup software streams the contents of the snapshot to the backup media. Similarly, a snapshot can be used as a "gold image" on which to base a template. A template can be made using any VDIs.
Parameter Name Description Type MTU Maximum Transmission Unit of the VIF in bytes. This parameter is read-only, but you can override the MTU setting with the mtu key using the other-config map parameter.
Parameter Name Description Type other-config:promiscuous true to a VIF to be promiscuous on the bridge, so that it sees all traffic over the bridge. Useful for running an Intrusion Detection System (IDS) or similar in a VM.
Attempts to detach the VIF from the VM while it is running. VLAN commands Commands for working with VLANs (virtual networks). To list and edit virtual interfaces, refer to the PIF commands, which have a VLAN parameter to signal that they have an associated virtual network (see the section called “PIF commands”). For example, to list VLANs you need to use xe pif-list. vlan-create vlan-create pif-uuid= vlan= network-uuid= Create a new VLAN on a XenServer host.
Note: All writable VM parameter values can be changed while the VM is running, but the new parameters are not applied dynamically and will not be applied until the VM is rebooted.
Parameter Name Description Type VCPUs-params configuration parameters for the selected VCPU policy. read/write map parameter You can tune a VCPU's pinning with xe vm-param-set \ uuid= \ VCPUs-params:mask=1,2,3 The selected VM will then run on physical CPUs 1, 2, and 3 only.
Parameter Name Description Type actions-after-crash action to take if the VM crashes. For PV guests, valid parameters are: preserve (for analysis only), coredump_and_restart (record a coredump and reboot VM), coredump_and_destroy (record a coredump and leave VM halted), restart (no coredump and restart VM), and destroy (no coredump and leave VM halted).
Parameter Name Description Type HVM-shadow-multiplier Floating point value which controls the amount of shadow memory overhead to grant the VM. Defaults to 1.0 (the minimum value), and should only be changed by advanced users.
Parameter Name Description Type start-time timestamp of the date and time that the metrics for the VM were read, in the form yyyymmddThh:mm:ss z, where z is the single-letter military timezone indicator, for example, Z for UTC (GMT) read only install-time timestamp of the date and time that the metrics for the VM were read, in the form yyyymmddThh:mm:ss z, where z is the single-letter military timezone indicator, for example, Z for UTC (GMT) read only memory-actual the actual memory being used by
Parameter Name Description Type PV-drivers-up-to-date flag for latest version of the paravirtualized drivers for the VM read only memory memory metrics reported by the agent on the VM read only map parameter disks disk metrics reported by the agent on the VM read only map parameter networks network metrics reported by the agent on the VM read only map parameter other other metrics reported by the agent on the VM read only map parameter guest-metrics-last-updated timestamp when the last wr
Parameter Name Description Type snapshot_time the timestamp of the snapshot operation that created this VM snapshot read only memory-target the target amount of memory set for this VM read only blocked-operations lists the operations that cannot be performed on this VM read/write map parameter last-boot-record record of the last boot parameters for this template, in XML format read only ha-always-run True if this VM will always restarted on another host in case of the failure of the host it
vm-cd-insert vm-cd-insert cd-name= [=...] Insert a CD into the virtual CD drive. This command will only work if there is one and only one empty CD device attached to the VM. When there are two or more empty CD devices, use the xe vbd-insert command and specify the UUIDs of the VBD and of the VDI to insert. The VM or VMs on which this operation should be performed are selected using the standard selection mechanism (see VM selectors).
For example: xe vm-compute-maximum-memory vm=testvm total=`xe host-list params=memory-free --minimal` This command uses the value of the memory-free parameter returned by the xe host-list command to set the maximum memory of the VM named testvm. The VM or VMs on which this operation will be performed are selected using the standard selection mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the beginning of this section.
List the data sources that can be recorded for a VM. The VM or VMs on which this operation should be performed are selected using the standard selection mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the beginning of this section. vm-data-source-query vm-data-source-query selector value>...] data-source= [=
The disk-size parameter can be specified in bytes or using the IEC standard suffixes KiB (2 20 30 40 MiB (2 bytes), GiB (2 bytes), and TiB (2 bytes). 10 bytes), The VM or VMs on which this operation should be performed are selected using the standard selection mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the beginning of this section. vm-disk-list vm-disk-list [vbd-params] [vdi-params] [=...
The filename parameter can also point to an XVA-format VM, which is the legacy export format from XenServer 3.2 and is used by some third-party vendors to provide virtual appliances. This format uses a directory to store the VM data, so set filename to the root directory of the XVA export and not an actual file. Subsequent exports of the imported legacy guest will automatically be upgraded to the new filenamebased format, which stores much more data about the configuration of the VM.
Migrate the specified VMs between physical hosts. The host parameter can be either the name or the UUID of the XenServer host. By default, the VM will be suspended, migrated, and resumed on the other host. The live parameter activates XenMotion and keeps the VM running while performing the migration, thus minimizing VM downtime to less than a second.
Shut down the specified VM. The VM or VMs on which this operation should be performed are selected using the standard selection mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the beginning of this section. Use the force argument to cause an ungraceful shutdown, similar to pulling the plug on a physical server. vm-start vm-start [=...] [force=] [on=] [-multiple] Start the specified VMs.
vm-vif-list vm-vif-list [=...] Lists the VIFs from the specified VMs. The VM or VMs on which this operation should be performed are selected using the standard selection mechanism (see VM selectors). Note that the selectors operate on the VM records when filtering, and not on the VIF values. Optional arguments can be any number of the VM parameters listed at the beginning of this section. Workload Balancing commands Commands for controlling the Workload Balancing feature.
pool-certificate-list XenServer’s Workload Balancing component lets you use certificates to secure communication between XenServer pools and the Workload Balancing server. You can either use the default certificate, which is created automatically during Workload Balancing installation, or you can specify a certificate you have already created. To use your own certificate, the certificate must be in X.509 format.
pool-param-set pool-param-set wlb-verify-cert= uuid= Run this command on the pool, after running the pool-certificate-sync command, to make XenServer always verify the certificate when communicating with the Workload Balancing server. Tip: Pressing the Tab key automatically populates the UUID of the pool. pool-deconfigure-wlb Permanently deletes all workload balancing configuration. pool-retrieve-wlb-configuration Prints all workload balancing configuration to standard out.
xe pool-retrieve-wlb-report report=optimization_performance_history \ poolid=<51e411f1-62f4-e462-f1ed-97c626703cae> \ utcoffset=<-5> \ start=<-3> \ end=<0> \ filename= xe pool-retrieve-wlb-report report=pool_health_history \ poolid=<51e411f1-62f4-e462-f1ed-97c626703cae> \ utcoffset=<-5> \ start=<-3> \ end=<0> \
Filer, NetApp, 43 FlexVol, NetApp, 43 Index H A AMD-V (AMD hardware virtualization), 19 C CD commands, xe CLI, 148 CLI (see command line interface) Command line interface (CLI) basic xe syntax, 142 Bonding commands, 147 CD commands, 148 command types, 144 console commands, 149 event commands, 150 host (XenServer host) commands, 151 log commands, 161 low-level list commands, 146 low-level parameter commands, 145 message commands, 162 network commands, 163 overview, parameter types, 145 patch commands, 16
member, 133, 133 removing XenServer host from, 22 requirements for creating, 19 S SAN (see Storage Area Network) Shared network attached storage (NFS), 52 Shared storage, 21 Storage Area Network, 47 Storage Manager commands, xe CLI, 173 Storage repository (SR) CD-ROM, 41 commands, xe CLI, 174 DVD-ROM, 41 Fibre Channel storage area network (SAN), 53 local disk, 40 local hotplug devices, 41 NetApp Filer, 43 overview, 30 shared iSCSI storage area network (SAN), 47 shared network attached storage (NFS), 52 USB
