Citrix XenServer ® 6.0 Administrator's Guide Published Friday, 02 March 2012 1.
Citrix XenServer ® 6.0 Administrator's Guide Copyright © 2012 Citrix Systems. Inc. All Rights Reserved. Version: 6.0 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.
Contents Document Overview .......................................................................................... 1 Introducing XenServer ........................................................................................................ 1 Benefits of Using XenServer ........................................................................................ 1 Administering XenServer ............................................................................................. 2 XenServer Editions .....
Hosts and Resource Pools Overview .................................................................................. 22 Requirements for Creating Resource Pools ......................................................................... 22 Creating a Resource Pool .................................................................................................. 23 Creating Heterogeneous Resource Pools ............................................................................ 23 Adding Shared Storage .......
Storage Overview ............................................................................................................. 34 Storage Repositories (SRs) ......................................................................................... 34 Virtual Disk Images (VDIs) ......................................................................................... 34 Physical Block Devices (PBDs) ....................................................................................
LVM over Hardware HBA ........................................................................................... 49 Storage Configuration ....................................................................................................... 49 Creating Storage Repositories .................................................................................... 49 Upgrading LVM Storage from XenServer 5.0 or Earlier ................................................. 50 LVM Performance Considerations ............
xe CLI Commands ............................................................................................................. 64 Display the Static Memory Properties of a VM ........................................................... 64 Display the Dynamic Memory Properties of a VM ....................................................... 65 Updating Memory Properties .................................................................................... 65 Update Individual Memory Properties ...................
Creating a NIC bond ......................................................................................... 79 Controlling the MAC Address of the Bond .......................................................... 79 Reverting NIC bonds ......................................................................................... 80 Creating NIC bonds in resource pools ........................................................................ 80 Adding NIC bonds to new resource pools ................................
vApps ............................................................................................................................... 92 Using the Manage vApps dialog box in XenCenter ...................................................... 93 Backing Up and Restoring XenServer Hosts and VMs .......................................................... 93 Backing up Virtual Machine metadata ....................................................................... 94 Backing up single host installations ...........
Alerts ............................................................................................................................. 106 Customizing Alerts .................................................................................................. 107 Configuring Email Alerts .......................................................................................... 108 Custom Fields and Tags ...................................................................................................
Bond Parameters ............................................................................................ 118 bond-create .................................................................................................... 118 bond-destroy .................................................................................................. 118 CD Commands ........................................................................................................ 118 CD Parameters ...............................
host-bugreport-upload .................................................................................... 129 host-crashdump-destroy .................................................................................. 129 host-crashdump-upload ................................................................................... 129 host-disable .................................................................................................... 129 host-dmesg ....................................................
Log Commands ....................................................................................................... 136 log-set-output ................................................................................................. 136 Message Commands ............................................................................................... 136 Message Parameters ....................................................................................... 136 message-create ...............................
pif-unplug ....................................................................................................... 144 Pool Commands ...................................................................................................... 144 Pool Parameters ............................................................................................. 144 pool-designate-new-master ............................................................................. 145 pool-dump-database ...............................
template-export .............................................................................................. 157 Update Commands ................................................................................................. 157 update-upload ................................................................................................ 158 User Commands ..................................................................................................... 158 user-password-change .......................
VLAN Commands .................................................................................................... 166 vlan-create ..................................................................................................... 167 pool-vlan-create .............................................................................................. 167 vlan-destroy .................................................................................................... 167 VM Commands .............................
vm-recover ..................................................................................................... 179 vm-reset-powerstate ....................................................................................... 179 vm-resume ..................................................................................................... 180 vm-shutdown ................................................................................................. 180 vm-start ............................................
Modifying the Workload Balancing configuration options .......................................... 187 Editing the Workload Balancing configuration file ..................................................... 187 Increasing the Detail in the Workload Balancing Log .................................................
Document Overview This document is a system administrator's guide for Citrix XenServer®, the complete server virtualization platform from Citrix®. It contains procedures to guide you through configuring a XenServer deployment. In particular, it focuses on setting up storage, networking and resource pools, and how to administer XenServer hosts using the xe command line interface.
• Increasing portability of VM images, as one VM image will work on a range of deployment infrastructures Administering XenServer There are two methods by which to administer XenServer: XenCenter and the XenServer Command-Line Interface (CLI). XenCenter is a graphical, Windows-based user interface. XenCenter allows you to manage XenServer hosts, pools and shared storage, and to deploy, manage and monitor VMs from your Windows desktop machine.
Rolling Pool Upgrade Wizard: • Simplify upgrades (automated or semi-automated) to XenServer 6.0 with a wizard that performs pre-checks with a step-by-step process that blocks unsupported upgrades. Microsoft SCVMM and SCOM Support: • Manage XenServer hosts and VMs with System Center Virtual Machine Manager (SCVMM) 2012. System Center Operations Manager (SCOM) 2012 will also be able to manage and monitor XenServer hosts and VMs.
VM Protection and Recovery: • Now available for Advanced, Enterprise and Platinum Edition customers. NFS Support for High Availability: • HA Heartbeat disk can now reside on a NFS storage repository. XenCenter Improvements: • XenCenter operations now run in parallel, and XenCenter will be available in Japanese and Simplified Chinese (ETA Q4 2011). Host Architectural Improvements: • XenServer 6.0 now runs on the Xen 4.1 hypervisor, provides GPT support and a smaller, more scalable Dom0.
Managing Users Defining users, groups, roles and permissions allows you to control who has access to your XenServer hosts and pools and what actions they can perform. 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.
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.
Note the following: • XenServer labels its AD entry on the AD database using its hostname. Therefore, if two XenServer hosts have the same hostname and are joined to the same AD domain, the second XenServer will overwrite the AD entry of the first XenServer, regardless of if they are in the same or in different pools, causing the AD authentication on the first XenServer to stop working. It is possible to use the same hostname in two XenServer hosts, as long as they join different AD domains.
Note: XenServer uses Likewise (Likewise uses Kerberos) to authenticate the AD user in the AD server, and to encrypt communications with the AD server. How does XenServer manage the machine account password for AD integration? Similarly to Windows client machines, Likewise automatically updates the machine account password, renewing it once every 30 days, or as specified in the machine account password renewal policy in the AD server. For more information, refer to http://support.microsoft.com/kb/154501.
you wish to manage user permissions in Active Directory, you could create a single group that you then add and remove users to/from; alternatively, you can add and remove individual users from XenServer, or a combination of users and groups as your would be appropriate for your authentication requirements. The subject list can be managed from XenCenter or using the CLI as described below.
they may be able to continue to access the pool using XenCenter or other API sessions that they have already created. In order to terminate these sessions forcefully, XenCenter and the CLI provide facilities to terminate individual sessions, or all currently active sessions. See the XenCenter help for more information on procedures using XenCenter, or below for procedures using the CLI.
RBAC depends on Active Directory for authentication services. Specifically, XenServer keeps a list of authorized users based on Active Directory user and group accounts. As a result, you must join the pool to the domain and add Active Directory accounts before you can assign roles. 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.
Note: You cannot add, remove or modify roles in this version of XenServer. Warning: You can not assign the role of pool-admin to an AD group which has more than 500 members, if you want users of the AD group to have SSH access. For a summary of the permissions available for each role and more detailed information on the operations available for each permission, see the section called “Definitions of RBAC Roles and Permissions”. All XenServer users need to be allocated to an appropriate role.
Role permissions Pool Admin Pool Operator Cancel task of any user X X Pool management X X VM advanced operations X X X VM create/ destroy operations X X X X 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 logs X X X X X X X X audit Configure, Initialize, Enable, Disable WLB Apply WLB X Optimization Recommendations X Modify WLB Report Subscriptions X X VM Power Admin VM Admi
Role permissions Pool Admin Pool Operator VM Power Admin VM Admin VM Operator Read Only Connect to pool and read all pool metadata X X X X X X Definitions of Permissions The following table provides additional details about permissions: 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 Accept WLB Recommendations Allows Assignee To Placement Rationale/Comments • 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 XenCenter folders global • Create and modify global XenCenter custom fields • Create and modify Xen
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 manage 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): aaa00a
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.
1. Run the commands: xe subject-role-remove uuid= role-name= \ xe subject-role-add uuid= role-name= \ To ensure that the new role takes effect, the user should be logged out and logged back in again (this requires the "Logout Active User Connections" permission - available to a Pool Administrator or Pool Operator).
In this illustration, since Subject 2 (Group 2) is the Pool Operator and User 1 is a member of Group 2, when Subject 3 (User 1) tries to log in, he or she inherits both Subject 3 (VM Operator) and Group 2 (Pool Operator) roles. Since the Pool Operator role is higher, the resulting role for Subject 3 (User 1) is Pool Operator and not VM Operator.
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.
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.
XenServer 6.0 simplifies expanding deployments over time by allowing disparate host hardware to be joined into a resource pool, known as heterogeneous resource pools. Heterogeneous resource pools are made possible by leveraging technologies in recent Intel (FlexMigration) and AMD (Extended Migration) CPUs that provide CPU "masking" or "leveling". These features allow a CPU to be configured to appear as providing a different make, model, or functionality than it actually does.
subsequently join will also be connected to the storage. The Universally Unique Identifier (UUID) of the created storage repository will be printed on the screen. 3. Find the UUID of the pool by the command xe pool-list 4. Set the shared storage as the pool-wide default with the command xe pool-param-set uuid= default-SR= Since the shared storage has been set as the pool-wide default, all future VMs will have their disks created on shared storage by default.
Warning: Citrix highly recommends rebooting all XenServers prior to installing an update and then verifying their configuration. This is because some configuration changes only take effect when a XenServer is rebooted, so the reboot may uncover configuration problems that would cause the update to fail. To prepare a XenServer host in a pool for maintenance operations using the CLI 1.
Block Devices (VBDs) and networks can affect which VMs may be restarted on which hosts. Currently it is not possible for XenServer to check all actions before they occur and determine if they will cause violation of HA demands. However an asynchronous notification is sent if HA becomes unsustainable. Overcommitment Warning If you attempt to start or resume a VM and that action causes the pool to be overcommitted, a warning alert is raised.
• it must have its virtual disks on shared storage (any type of shared storage may be used; the iSCSI, NFS or Fibre Channel LUN is only required for the storage heartbeat and can be used for virtual disk storage if you prefer, but this is not necessary) • it must not have a connection to a local DVD drive configured • it should have its virtual network interfaces on pool-wide networks.
best-effort priority setting are not part of the failover plan and are not guaranteed to be kept running, since capacity is not reserved for them. If the pool experiences server failures and enters a state where the number of tolerable failures drops to zero, the protected VMs will no longer be guaranteed to be restarted. If this condition is reached, a system alert will be generated.
Recovering an Unreachable Host If for some reason a host cannot access the HA statefile, it is possible that a host may become unreachable. To recover your XenServer installation it may be necessary to disable HA using the host-emergency-ha-disable command: xe host-emergency-ha-disable --force If the host was the pool master, then it should start up as normal with HA disabled. Slaves should reconnect and automatically disable HA.
• Hewlett-Packard Integrated Lights-Out (iLO). To use XenServer with iLO, you must enable iLO on the host and connect interface to the network. For more information, see HP’s iLO documentation. • A custom script based on the XenAPI that enables you to turn the power on and off through XenServer. For more information, see the section called “Configuring a Custom Script for XenServer's Host Power On Feature”. Using the Host Power On feature requires three tasks: 1.
When you create a custom script, run it from the command line each time you want to control power remotely on XenServer. Alternatively, you can specify it in XenCenter and use the XenCenter UI features to interact with it. The XenServer API is documented in the document, the [Citrix XenServer Management API], which is available from the Citrix Web site. Note: Do not modify the scripts provided by default in the /etc/xapi.d/plugins/ directory.
The result is only displayed when the script is unsuccessful. import XenAPI def custom(session,remote_host, power_on_config): result="Power On Not Successful" for key in power_on_config.keys(): result=result+" key="+key+" value="+power_on_config[key] return result Note: After creation, save the script in the /etc/xapi.d/plugins with a .py extension.
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 storagerelated tasks.
Virtual Block Devices (VBDs) Virtual Block Devices are connector objects (similar to the PBD described above) that allows mappings between VDIs and VMs. In addition to providing a mechanism for attaching (also called plugging) a VDI into a VM, VBDs allow for the fine-tuning of parameters regarding QoS (quality of service), statistics, and the bootability of a given VDI. CLI operations relating to VBDs are described in the section called “VBD Commands”.
unused space on the underlying CoW instance disk is reclaimed when a snapshot or clone occurs. The difference between the two behaviors can be characterized in the following way: • For LVM-based VHDs, the difference disk nodes within the chain consume only as much data as has been written to disk but the leaf nodes (VDI clones) remain fully inflated to the virtual size of the disk.
operations are mapped directly onto the array APIs using a LUN per VDI representation. This includes activating the data path on demand such as when a VM is started or migrated to another host. Managed NetApp LUNs are accessible using the NetApp SR driver type, and are hosted on a Network Appliance device running a version of Ontap 7.0 or greater. LUNs are allocated and mapped dynamically to the host using the XenServer host management framework.
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 6.0 did not use the VHD format and will remain in legacy mode. See the section called “Upgrading LVM Storage from XenServer 5.0 or Earlier” for information about upgrading a storage repository to the new format.
xe sr-create host-uuid= content-type=iso \ type=iso name-label=<"Example ISO SR"> \ device_config:location=> Software iSCSI Support XenServer provides support for shared SRs on iSCSI LUNs. iSCSI is supported using the open-iSCSI software iSCSI initiator or by using a supported iSCSI Host Bus Adapter (HBA).
For more information on using CSL SR types with XenCenter, see the XenCenter online help. Because the CSL SR can be used to access different storage arrays, the exact features available for a given CSL SR depend on the capabilities of the array. All CSL SRs use a LUN-per-VDI model where a new LUN is provisioned for each virtual disk (VDI). CSL SRs can co-exist with other SR types on the same storage array hardware, and multiple CSL SRs can be defined within the same resource pool.
Parameter name Description Optional? target The server name or IP address of the array management console No storageSystemId The storage system ID to use for allocating storage No 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 array management console Yes adapterid The name of the adapter No password The password to use for connecting to the array management console Yes chapuser T
To Create a CSL SR Using the CLI 1. Use the sr-probe command with the device-config:target parameter and username and password credentials to identify the available storage system IDs.
xe sr-probe type=cslg device-config:adapterid=NETAPP \ device-config:username=**** device-config:password=**** \ device-config:target=**** devfiler NetApp FAS3020 (devfiler) NetApp FAS3020 3064792 NETAPP__LUN__0A50E2F6 PROVISIONING THIN_PROVISIONIN
You can use grep to filter the sr-probe output to just display the storage system IDs: xe sr-probe type=cslg device-config:adapterid=NETAPP \ device-config:username=xxxx device-config:password=xxxx \ device-config:target=xxxx | grep storageSystemId devfiler NetApp FAS3020 (devfiler) NetApp FAS3020 3064792 NETAPP__LUN__0A50E2F6
/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. Use the xe sr-probe command to force a rescan of the HBA controller and display available LUNs. See the section called “Probing an SR” and the section called “Creating a Shared LVM over Fibre Channel / iSCSI HBA or SAS SR (lvmohba)” for more details.
Parameter Name Description Required? port the network port number on which to query the target no usediscoverynumber the specific iSCSI record index to use no incoming_chapuser the username that the iSCSI filter will use to authenticate against the host no incoming_chappassword the password that the iSCSI filter will use to authenticate against the host 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, \
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. NFS is a ubiquitous form of storage infrastructure that is available in many environments. XenServer allows existing NFS servers that support NFS V3 over TCP/IP to be used immediately as a storage repository for virtual disks (VDIs). VDIs are stored in the Microsoft VHD format only.
Creating a Shared NFS SR (NFS) Device-config parameters for NFS SRs: Parameter Name Description Required? server IP address or hostname of the NFS server Yes serverpath path, including the NFS mount point, to the NFS server that hosts the SR Yes To create a shared NFS SR on 192.168.1.10:/export1 use the following command. xe sr-create host-uuid= content-type=user \ name-label=<"Example shared NFS SR"> shared=true \ device-config:server=<192.168.1.
There are two basic steps involved in creating a new storage repository for use on a XenServer host using the CLI: 1. Probe the SR type to determine values for any required parameters. 2. Create the SR to initialize the SR object and associated PBD objects, plug the PBDs, and activate the SR. These steps differ in detail depending on the type of SR being created. In all examples the sr-create command returns the UUID of the created SR if successful.
To check if an SR has been upgraded, verify that its sm-config:use_vhd key is true. To check if a VDI was created with type=raw, check its sm-config map. The sr-param-list and vdi-param-list xe commands can be used respectively for this purpose. Creating a Raw Virtual Disk Using the xe CLI 1.
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 Can be probed? Required for sr-create? 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 storageSystemId Yes Yes storagePoolId Yes Yes username No No ‡ password No No ‡ cslport No No ‡ chapuser
† 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. ‡ If the username, password, or port configuration of the StorageLink service are changed from the default value then the appropriate parameter and value must be specified. Storage Multipathing Dynamic multipathing support is available for Fibre Channel and iSCSI storage backends.
Multipath support in EqualLogic arrays does not encompass Storage IO multipathing in the traditional sense of the term. Multipathing must be handled at the network/NIC bond level. Refer to the EqualLogic documentation for information about configuring network failover for EqualLogic SRs/LVMoISCSI SRs. MPP RDAC Driver Support for LSI Arrays. XenServer supports the LSI Multi-Path Proxy Driver (MPP) for the Redundant Disk Array Controller (RDAC). By default this driver is disabled. To enable the driver: 1.
The following example introduces a SR of type lvmoiscsi. 1. Probe the existing SR to determine its UUID: xe sr-probe type=lvmoiscsi device-config:target=<192.168.1.10> \ device-config:targetIQN=<192.168.1.10:filer1> \ device-config:SCSIid=<149455400000000000000000002000000b70200000f000000> 2. Introduce the existing SR UUID returned from the sr-probe command.
6. Click Repair to create and plug a PBD for each host in the pool. Moving Virtual Disk Images (VDIs) Between SRs The set of VDIs associated with a VM can be copied from one SR to another to accommodate maintenance requirements or tiered storage configurations. XenCenter provides the ability to copy a VM and all of its VDIs to the same or a different SR, and a combination of XenCenter and the xe CLI can be used to copy individual VDIs.
to the SR. The corresponding PBD must be unplugged and re-plugged for the scheduler parameter to take effect. The disk scheduler can be adjusted using the following command: xe sr-param-set other-config:scheduler=noop|cfq|anticipatory|deadline \ uuid= Note: This will not effect EqualLogic, NetApp or NFS storage. Automatically Reclaiming Space When Deleting Snapshots When deleting snapshots with XenServer 6.
2. This command suspends the VM (unless it is already powered down), initiates the space reclamation process, and then resumes the VM. Note: Citrix recommends that, before executing the off-line coalesce tool, you shutdown or suspend the VM manually (using either XenCenter or the XenServer CLI). If you execute the coalesce tool on a VM that is running, the tool automatically suspends the VM, performs the required VDI coalesce operation(s), and resumes the VM.
xe xe xe xe xe vbd-param-set uuid= qos_algorithm_type=ionice vbd-param-set uuid= qos_algorithm_params:sched=rt vbd-param-set uuid= qos_algorithm_params:class=5 sr-param-set uuid= other-config:scheduler=cfq pbd-plug uuid= 60
Configuring VM Memory When a VM is first created, it is allocated a fixed amount of memory. To improve the utilisation 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.
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. The Concept of Static Range Many Operating Systems that XenServer supports do not fully ‘understand’ the notion of dynamically adding or removing memory.
XenServer to repartition host memory dynamically in response to changing numbers of guests, or changing host memory pressure. XenServer chooses a target from within the range and adjusts the guest's memory allocation to meet the target. Note: It is possible to change between target mode and dynamic range mode at any time for any running guest. Simply specify a new target, or a new dynamic range, and XenServer takes care of the rest.
Operating System RedHat Linux Oracle Linux Enterprise Enterprise Supported Memory Limits 4.5 - 4.8 x86 ≥ 256 MB ≤ 16 GB 5.0 - 5.6 x86 x64 ≥ 512 MB ≤ 16 GB 6.0 x86 ≥512 MB ≤8 GB x64 ≥512 MB ≤32 GB x86 ≥ 512 MB ≤ 64 GB x64 ≥ 512 MB ≤ 128 GB x86 ≥512 MB ≤8 GB x64 ≥512 MB ≤32 GB 9 SP4 x86 ≥ 256 MB ≤ 16 GB 10 SP1,SP2,SP3,SP4 x86 ≥ 512 MB ≤ 16 GB x64 ≥ 512 MB ≤ 128 GB x86 ≥ 512 MB ≤ 16 GB x64 ≥ 512 MB ≤ 128 GB Lenny (5.0) x86 ≥ 128 MB ≤ 32 GB Squeeze (6.
xe vm-param-get uuid= param-name=memory-static-{min,max} For example, the following displays the static maximum memory properties for the VM with the uuid beginning ec77: xe vm-param-get uuid= \ ec77a893-bff2-aa5c-7ef2-9c3acf0f83c0 \ param-name=memory-static-max; 268435456 This shows that the static maximum memory for this VM is 268435456 bytes (256MB).
xe vm-memory-limits-set \ uuid= \ static-min= \ dynamic-min= \ dynamic-max= static-max= Note: • To allocate a specific amount memory to a VM that won't change, set the Dynamic Maximum and Dynamic Minimum to the same value. • You cannot increase the dynamic memory of a VM beyond the static maximum. • To alter the static maximum of a VM – you will need to suspend or shut down the VM.
Xen Memory Usage When calculating the memory footprint of a Xen host there are two components that must be taken into consideration. First there is the memory consumed by the Xen hypervisor itself; then there is the memory consumed by the control domain of the host. The control domain is a privileged VM that provides low-level services to other VMs, such as providing access to physical devices. It also runs the management tool stack.
name default description memory-overhead 1048576 (for example) The memory overhead due to virtualization Dynamic memory values must be within the boundaries set by the static memory values. Additionally the memory target must fall in the range between the dynamic memory values. Note: The amount of memory reported in XenCenter on the General tab in the Xen field may exceed the values set using this mechanism.
Networking This chapter provides an overview of XenServer networking, including networks, VLANs, and NIC bonds. It also discusses how to manage your networking configuration and troubleshoot it. Important: As of this release, the XenServer default network stack is the vSwitch; however, you can revert to the Linux network stack if desired by using the instructions in the section called “vSwitch Networks”.
• Provides detailed visibility into the behavior and performance of all traffic sent in the virtual network environment. A vSwitch greatly simplifies IT administration in virtualized networking environments—all VM configuration and statistics remain bound to the VM even if it migrates from one physical host in the resource pool to another. See the XenServer vSwitch Controller User Guide for more details.
• A network, which is a virtual Ethernet switch on a XenServer host. Network objects have a name and description, a globally unique UUID, and the collection of VIFs and PIFs connected to them. Both XenCenter and the xe CLI allow configuration of networking options, control over which NIC is used for management operations, and creation of advanced networking features such as virtual local area networks (VLANs) and NIC bonds.
together so they logically function as one network card. Both NICs have the same MAC address and, in the case of management interfaces, have one IP address. If one NIC in the bond fails, the host's network traffic is automatically redirected through the second NIC. NIC bonding is sometimes also known as NIC teaming. XenServer supports up to eight bonded networks. You can bond two NICs together of any type (management interfaces or non-management interfaces).
When bonded NICs are used for VM (guest) traffic, you do not need to configure an IP address for the bond. This is because the bond operates at Layer 2 of the OSI model, the data link layer, and no IP addressing is used at this layer. When used for non-VM traffic (to connect to shared network storage or XenCenter for management), you must configure an IP address for the bond. If you bond a management interface to a non-management NIC, as of XenServer 6.
This illustration shows how two NICs in a bonded pair use the same network settings, as represented by the networks in each host. The NICs in the bonds connect to different switches for redundancy. Active-Active Bonding Active-Active, which is the default bonding mode, is an active/active configuration for guest traffic: both NICs can route VM traffic simultaneously.
This illustration shows how, when configured in Active-active mode, the links that are active in bonds vary according to traffic type. In the top picture of a management network, NIC 1 is active and NIC 2 is passive. For the VM traffic, both NICs in the bond are active. For the storage traffic, only NIC 3 is active and NIC 4 is passive. XenServer load balances the traffic between NICs by using the source MAC address of the packet.
Tip: Configuring active-passive mode in XenCenter is easy. You simply select Active-passive as the bond mode when you create the bond. Important: After you have created VIFs or your pool is in production, be extremely careful about making changes to bonds or creating new bonds. Initial Networking Configuration The XenServer host networking configuration is specified during initial host installation.
Creating cross-server private networks requires Citrix XenServer Advanced editions or higher. To learn more about XenServer editions, and to find out how to upgrade, visit the Citrix website here. Previous versions of XenServer allowed you to create single-server private networks that allowed VMs running on the same host to communicate with each other.
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.
This section describes how to use the xe CLI to bond NIC interfaces on a XenServer host that is not in a pool. See the section called “Creating NIC bonds in resource pools” for details on using the xe CLI to create NIC bonds on XenServer hosts that comprise a resource pool. Creating a NIC bond When you bond a NIC, the bond absorbs the PIF/NIC currently in use as the primary management interface. From XenServer 6.0 onwards, the primary management interface is automatically moved to the bond PIF.
Reverting NIC bonds If reverting a XenServer host to a non-bonded configuration, be aware that the bond-destroy command automatically configures the primary-slave as the interface to be used for the primary management interface. Consequently, all VIFs will be moved to the primary management interface. The term primary-slave refers to the PIF that the MAC and IP configuration was copied from when creating the bond. When bonding two NICs, the primary slave is: 1.
• Use the host-list command to find the UUID of the host being configured: xe host-list Adding NIC bonds to an existing pool Warning: Do not attempt to create network bonds while HA is enabled. The process of bond creation disturbs the in-progress HA heartbeating and causes hosts to self-fence (shut themselves down); subsequently they will likely fail to reboot properly and you will need to run the hostemergency-ha-disable command to recover them.
If you want to use a storage interface that can be routed from the primary management interface also (bearing in mind that this configuration is not the best practice), you have two options: • After a host reboot, ensure that the storage interface is correctly configured, and use the xe pbd-unplug and xe pbd-plug commands to reinitialize the storage connections on the host. This restarts the storage connection and routes it over the correct interface.
The QoS value limits the rate of transmission from the VM. The QoS setting does not limit the amount of data the VM can receive. If such a limit is desired, Citrix recommends limiting the rate of incoming packets higher up in the network (for example, at the switch level).
Hostname The system hostname, also known as the domain or DNS name, is defined in the pool-wide database and modified using the xe host-set-hostname-live CLI command as follows: xe host-set-hostname-live host-uuid= host-name= The underlying control domain hostname changes dynamically to reflect the new hostname. DNS servers To add or remove DNS servers in the IP addressing configuration of a XenServer host, use the pif-reconfigure-ip command.
To change the IP address of the pool master 1. Use the pif-reconfigure-ip CLI command to set the IP address as desired. See Appendix A, Command Line Interface for details on the parameters of the pif-reconfigure-ip command: xe pif-reconfigure-ip uuid= mode=DHCP 2. When the IP address of the pool master host is changed, all member hosts will enter into an emergency mode when they fail to contact the master host. 3.
Diagnosing network corruption Some network card models require firmware upgrades from the vendor to work reliably under load, or when certain optimizations are turned on. If you are seeing corrupted traffic to VMs, then you should first try to obtain the latest recommended firmware from your vendor and apply a BIOS update. If the problem still persists, then you can use the CLI to disable receive / transmit offload optimizations on the physical interface.
Disaster Recovery and Backup The XenServer Disaster Recovery (DR) feature is designed to allow you to recover virtual machines (VMs) and vApps from a catastrophic failure of hardware which disables or destroys a whole pool or site. For protection against single server failures, see the section called “High Availability” Note: Disaster Recovery is only available for XenServer Platinum edition.
and Universal Unique Identifier (UUID), and its memory, virtual CPU and networking and storage configuration. It also includes the VM startup options – start order, delay interval and HA restart priority – which are used when restarting the VM in an HA or DR environment. For example, when recovering VMs during disaster recovery, the VMs within a vApp will be restarted in the DR pool in the order specified in the VM metadata, and with the specified delay intervals.
Deployment Considerations Please review the following steps before enabling Disaster Recovery. Steps to Take Before a Disaster The following section describes the steps to take before disaster. • Configure your VMs and vApps. • Note how your VMs and vApps are mapped to SRs, and the SRs to LUNs. Take particular care with the naming of the name_label and name_description fields.
Information for all VMs in the pool is stored, VMs do not need to be independently selected for protection. 3. Click OK. Your pool is now protected. Recovering VMs and vApps in the Event of Disaster (Failover) This section explains how to recover your VMs and vApps on the secondary (recovery) site. 1. In XenCenter select the secondary pool, and on the Pool menu, click Disaster Recovery to open the Disaster Recovery wizard. This wizard gives three recovery options: Failover, Failback, and Test Failover.
1. In XenCenter select the secondary pool, and on the Pool menu, click Disaster Recovery to open the Disaster Recovery wizard. This wizard gives three recovery options: Failover, Failback, and Test Failover. To restore VMs and vApps to your primary site, select Failback and then click Next.
If you use Fibre Channel shared storage with LUN mirroring to replicate the data to the secondary site, before you attempt to recover data, mirroring must be broken so that the secondary site has Read/Write access. 3. Select the storage repositories (SRs) containing the pool metadata for the VMs and vApps that you want to recover. By default, the list on this wizard page shows all SRs that are currently attached within the pool.
useful in the Disaster Recovery situation where an Administrator may choose to group all VMs which reside on the same Storage Repository, or which relate to the same Service Level Agreement (SLA). Creating vApps To group VMs together in a vApp follow the procedure: 1. Select the pool and, on the Pool menu, click Manage vApps. This displays the Manage vApps window. 2. Enter a name for the vApp, and optionally a description, and then click Next.
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. Run the command: xe pool-restore-database file-name= dry-run=true This command checks that the target machine has an appropriate number of appropriately named NICs, which is required for the backup to succeed.
Backing up single host installations Use the CLI to backup the pool database. To obtain a consistent pool metadata backup file, run pool-dumpdatabase on the XenServer host and archive the resulting file. The backup file will contain sensitive authentication information about the pool, so ensure it is securely stored. To restore the pool database, use the xe pool-restore-database command from a previous dump file.
section called “Backing up Virtual Machine metadata”). This backup method should always be considered complementary to backing up the pool metadata. Using the xe commands host-backup and host-restore is another approach that you can take. The xe host-backup command archives the active partition to a file you specify, and the xe host-restore command extracts an archive created by xe host-backup over the currently inactive disk partition of the host.
VM Snapshots XenServer provides a convenient snapshotting mechanism that can take a snapshot of a VM storage and metadata at a given time. Where necessary, IO is temporarily halted while the snapshot is being taken to ensure that a selfconsistent disk image can be captured. Snapshot operations result in a snapshot VM that is similar to a template. The VM snapshot contains all the storage information and VM configuration, including attached VIFs, allowing them to be exported and restored for backup purposes.
xe vm-snapshot vm= new-name-label= xe vm-snapshot-with-quiesce vm= new-name-label= 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.
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.
1. Use the command snapshot-export-to-template to create a new template file: xe snapshot-export-to template snapshot-uuid= \ filename= For example: xe snapshot-export-to-template snapshot-uuid=b3c0f369-59a1-dd16-ecd4-a1211df29886 \ filename=example_template_export The VM export/import feature can be used in a number of different ways: • As a convenient backup facility for your VMs. An exported VM file can be used to recover an entire VM in the event of disaster.
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. Note: Using EqualLogic or NetApp storage requires a Citrix XenServer Advanced Edition or higher license. To learn more about XenServer editions, and to find out how to upgrade, visit the Citrix website here.
Member failures In the absence of HA, master nodes detect the failures of members by receiving regular heartbeat messages. If no heartbeat has been received for 600 seconds, the master assumes the member is dead. There are two ways to recover from this problem: • Repair the dead host (e.g. by physically rebooting it). When the connection to the member is restored, the master will mark the member as alive again.
If the master is really dead, choose one of the members and run the command xe pool-emergency-transitionto-master on it. Once it has become the master, run the command xe pool-recover-slaves and the members will now point to the new master. 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.
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 with XenServer Advanced edition or above. To find out about XenServer editions and how to upgrade, visit the Citrix website here.
The following alerts appear on the performance graphs in XenCenter.
alarm_trigger_period number of seconds that values above or below the alarm threshold can be received before an alarm is sent (default 60) alarm_auto_inhibit_period number of seconds this alarm disabled after an alarm is sent (default 3600) consolidation_fn how to combine variables from rrd_updates into one value (default is sum - other choice is average) rrd_regex regular expression to match the names of variables returned by the xe vm-data-source-list uuid= command that should be used to compute t
The default priority level is 5. Note: Some SMTP servers only forward mails with addresses that use FQDNs. If you find that emails are not being forwarded it may be for this reason, in which case you can set the server hostname to the FQDN so this is used when connecting to your mail server. Custom Fields and Tags XenCenter supports the creation of tags and custom fields, which allows for organization and quick searching of VMs, storage and so on. See the XenCenter online help for more information.
Troubleshooting Citrix provides two forms of support: free, self-help support on the Citrix Support website and paid-for Support Services, which you can purchase from the Support site. With Citrix Technical Support, you can open a Support Case online or contact the support center by phone if you experience technical difficulties. The Citrix Knowledge Center hosts a number of resources that may be helpful to you if you experience odd behavior, crashes, or other problems.
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 standalone remote CLI is also available for Linux. On Windows, the xe.exe CLI executable is installed along with XenCenter.
-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.
• -param-get • -param-set • -param-list • -param-add • -param-remove • -param-clear where is one of: • bond • console • host • host-crashdump • host-cpu • network • patch • pbd • pif • pool • sm • sr • task • template • vbd • vdi • vif • vlan • vm Note that not every value of has the full set of -param- commands; some have just a subset.
platform (MRW): acpi: true; apic: true; pae: true; nx: false allowed-operations (SRO): pause; clean_shutdown; clean_reboot; \ hard_shutdown; hard_reboot; suspend The platform parameter has a list of items that represent key/value pairs. The key names are followed by a colon character (:). Each key/value pair is separated from the next by a semicolon character (;). The M preceding the RW indicates that this is a map parameter and is readable and writable.
xe vm-list params=all Note that some parameters that are expensive to calculate will not be shown by the list command. These parameters will be shown as, for example: allowed-VBD-devices (SRO): To obtain these fields, use either the command -param-list or -param-get To filter the list, the CLI will match parameter values with those specified on the command-line, only printing objects that match all of the specified constraints.
Creates an appliance/vApp. For example: xe appliance-create name-label=my_appliance Add VMs to the appliance: xe vm-param-set uuid= appliance= \ xe vm-param-set uuid= appliance= appliance-destroy appliance-destroy uuid= Destroys an appliance/vApp.
xe audit-log-get since=2009-09-24T17:56:20.530Z \ filename=/tmp/auditlog-pool-actions.out Bonding Commands Commands for working with network bonds, for resilience with physical interface failover. See the section called “Creating NIC Bonds on a Standalone Host” for details. The bond object is a reference object which glues together master and member PIFs. The master PIF is the bonding interface which must be used as the overall PIF to refer to the bond.
Parameter Name Description Type sr-uuid The unique identifier/object reference for the SR this CD is part of read only sr-name-label The name for the SR this CD is part of read only vbd-uuids A list of the unique identifiers for the VBDs on VMs that connect to this CD read only set parameter crashdump-uuids Not used on CDs since crashdumps cannot be written to them read only set parameter virtual-size Size of the CD as it appears to VMs (in bytes) read only physical-utilisation amount of
List the CDs and ISOs (CD image files) on the XenServer host or pool, filtering on the optional argument params. If the optional argument params is used, the value of params is a string containing a list of parameters of this object that you want to display. Alternatively, you can use the keyword all to show all parameters. If params is not used, the returned list shows a default subset of all available parameters.
sr-whitelist lists SR UUIDs, drtask-create will only introduce and connect to an SR which has one of the whitelisted UUIDs drtask-destroy drtask-destroy uuid= Destroys a disaster recovery task and forgets the introduced SR. vm-assert-can-be-recovered vm-assert-can-be-recovered uuid= database:vdi-uuid= Tests whether storage is available to recover this VM.
On the primary site, enable database replication: xe sr-database-replication uuid= In the event of disaster, on the secondary site, connect to the SR:(note device-config has the same fields as srprobe).
Class name Description pbd The physical block devices through which hosts access SRs event-wait event-wait class= [=] [=/=] 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.
Parameter Name Description Type gpu-group-name-label The name of the GPU group to which the pGPU is assigned Read only host-uuid The unique identifier/object reference for the XenServer host to which the pGPU is connected Read only host-name-label The name of the XenServer host to which the pGPU is connected Read only pci-id PCI identifier Read only dependencies Lists the dependent PCI devices passed-through to the same VM Read/write map parameter other-config A list of key/value pairs th
Parameter Name Description Type vm-uuid The unique identifier/object reference for the VM to which the vGPU is assigned Read only vm-name-label The name of the VM to which the vGPU is assigned Read only gpu-group-uuid The unique identifier/object reference for the GPU group in which the vGPU is contained Read only gpu-group-name-label The name of the GPU group in which the vGPU is contained Read only currently-attached True if a VM with GPU PassThrough is running, false otherwise Read only
Host Parameters XenServer hosts have the following parameters: Parameter Name Description Type uuid The unique identifier/object reference for the XenServer host read only name-label The name of the XenServer host read/write name-description The description string of the XenServer host read only 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-
Parameter Name Description Type license-server • A list of key/value pairs that specify information about the license server Read only map parameter • The default port for communications with Citrix products is 27000. For information on changing port numbers due to conflicts, see the Licensing Your Product section on Citrix eDocs.
Parameter Name Description Type external-auth-type Type of external authentication, for example, Active Directory. read only external-auth-service-name The name of the external authentication service read only external-auth-configuration Configuration information for the external authentication service. read only map parameter XenServer hosts contain some other objects that also have parameter lists.
Parameter Name Description Type size size of the crashdump, in bytes read only host-backup host-backup file-name= host= Download a backup of the control domain of the specified XenServer host to the machine that the command is invoked from, and save it there as a file with the name file-name. While the xe host-backup command will work if executed on the local host (that is, without a specific hostname specified), do not use it this way.
Get a Xen dmesg (the output of the kernel ring buffer) from specified XenServer hosts. The host(s) on which this operation should be performed are selected using the standard selection mechanism (see host selectors above). Optional arguments can be any number of the host parameters listed at the beginning of this section.
Download system status information into the specified file. The optional parameter entries is a commaseparated list of system status entries, taken from the capabilities XML fragment returned by the host-getsystem-status-capabilities command. See the section called “host-get-system-status-capabilities” for 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.
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.
Warning: Be extremely careful when using this CLI command off-host, since once it is run it will not be possible to connect to the control domain remotely over the network to re-enable it. host-management-reconfigure host-management-reconfigure [interface= ] | [pif-uuid= ] Reconfigures the XenServer host to use the specified network interface as its primary management interface, which is the interface that is used to connect to the XenCenter.
Reboot the specified XenServer hosts. The specified hosts must be disabled first using the xe host-disable command, otherwise a HOST_IN_USE error message is displayed. The host(s) on which this operation should be performed are selected using the standard selection mechanism (see host selectors above). Optional arguments can be any number of the host parameters listed at the beginning of this section.
The host(s) on which this operation should be performed are selected using the standard selection mechanism (see host selectors above). Optional arguments can be any number of the host parameters listed at the beginning of this section. host-data-source-list host-data-source-list [=...] List the data sources that can be recorded for a host. Select the host(s) on which to perform this operation by using the standard selection mechanism (see host selectors).
Log Commands Commands for working with logs. log-set-output log-set-output output=nil | stderr | file: | syslog: [key=] [level= debug | info | warning | error] 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=
message-destroy message-destroy {uuid=} Destroys an existing message. You can build a script to destroy all messages. For example: # Dismiss all alerts \ IFS=","; for m in $(xe message-list params=uuid --minimal); do xe message-destroy uuid=$m \ done \ message-list message-list Lists all messages, or messages that match the specified standard selectable parameters. Network Commands Commands for working with networks.
Parameter Name Description Type other-config:ethtoolautoneg set to no to disable autonegotiation of the physical interface or bridge. Default is yes.
Parameter Name Description Type name-label The name of the patch read only name-description The description string of the patch read only 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.
Parameter Name Description Type uuid The unique identifier/object reference for the PBD.
PIF Parameters PIFs have the following parameters: Parameter Name Description Type uuid the unique identifier/object reference for the PIF read only device machine-readable name of the interface (for example, eth0) read only MAC the MAC address of the PIF read only other-config Additional PIF configuration name:value pairs.
Parameter Name Description Type 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-configuration-mode is static; undefined if supplied by DHCP read only DNS DNS address of the PIF, defined here if IPconfiguration-mode is static; undefined if supplied by DHCP read only io_read_kbs average read rate in kB/s for the device read only io_write_kbs average write rate in kB/s for
Parameter Name Description Type other-config:ethtool-gso set to on to enable generic segmentation offload, off to disable read write other-config:domain comma-separated list used to set the DNS search path read write other-config:bondmiimon interval between link liveness checks, in milliseconds read write other-config:bonddowndelay number of milliseconds to wait after link is lost before really considering the link to have gone.
Using static IP addresses on physical network interfaces connected to a port on a switch using Spanning Tree Protocol with STP Fast Link turned off (or unsupported) results in a period during which there is no traffic. pif-scan pif-scan host-uuid= Scan for new physical interfaces on a XenServer host. pif-unplug pif-unplug uuid= Attempt to bring down the specified physical interface. Pool Commands Commands for working with pools.
Parameter Name Description Type other-config a list of key/value pairs that specify additional configuration parameters for the pool read/write map parameter supported-sr-types SR types that can be used by this pool read only ha-enabled True if HA is enabled for the pool, false otherwise read only ha-configuration reserved for future use.
pool-eject pool-eject host-uuid= Instruct the specified XenServer host to leave an existing pool. pool-emergency-reset-master pool-emergency-reset-master master-address= Instruct a slave member XenServer host to reset its master address to the new value and attempt to connect to it. This command should not be run on master hosts.
Force the pool database to be synchronized across all hosts in the resource pool. This is not necessary in normal operation since the database is regularly automatically replicated, but can be useful for ensuring changes are rapidly replicated after performing a significant set of CLI operations. Storage Manager Commands Commands for controlling Storage Manager plugins.
Parameter Name Description Type allowed-operations list of the operations allowed on the SR in this state read only set parameter current-operations list of the operations that are currently in progress on this SR read only set parameter VDIs unique identifier/object reference for the virtual disks in this SR read only set parameter PBDs unique identifier/object reference for the PBDs attached to this SR read only set parameter physical-utilisation physical space currently utilized on this S
The exact device-config parameters differ depending on the device type. See Storage for details of these parameters across the different storage backends. sr-destroy sr-destroy uuid= Destroys the specified SR on the XenServer host. sr-enable-database-replication sr-enable-database-replication uuid= Enables xapi database replication to the specified (shared) SR.
Force an SR scan, syncing the xapi database with VDIs present in the underlying storage substrate. Task Commands Commands for working with long-running asynchronous tasks. These are tasks such as starting, stopping, and suspending a Virtual Machine, which are typically made up of a set of other atomic subtasks that together accomplish the requested operation.
Parameter Name Description Type subtasks contains the UUID(s) of all the subtasks of this task read only task-cancel task-cancel [uuid=] Direct the specified Task to cancel and return. Template Commands Commands for working with VM templates. 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.
Parameter Name Description Type memory-dynamic-max dynamic maximum memory in bytes. Currently unused, but if changed the following constraint must be obeyed: memory_static_max >= memory_dynamic_max >= memory_dynamic_min >= memory_static_min. read/write 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.
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 template-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 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 available for use, represented by integers of the range 0-15. This list is informational only, and other devices may be used (but may not work).
Parameter Name Description Type 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 on this template has preference for running on; used by the xe vm-start command to decide where to run the VM read/write other-config list of key/value pairs that specify additional configuration parameters for the template read/write map parameter start-time timestamp of the da
Parameter Name Description Type PV-drivers-version the versions of the paravirtualized drivers for a VM based on this template; appears as for a template read only map parameter PV-drivers-up-to-date flag for latest version of the paravirtualized drivers for a VM based on this template; appears as for a template read only memory memory metrics reported by the agent on a VM based on this template; appears as for a template read only map paramet
Parameter Name Description Type recommendations XML specification of recommended values and ranges for properties of this VM read only xenstore-data data to be inserted into the xenstore tree (/local/domain/ /vm-data) after the VM is created.
update-upload update-upload file-name= Streams a new software image to a OEM edition XenServer host. You must then restart the host for this to take effect. User Commands user-password-change user-password-change old= new= Changes the password of the logged-in user. The old password field is not checked because you require supervisor privilege to make this call. VBD Commands Commands for working with VBDs (Virtual Block Devices).
Parameter Name Description Type mode the mode the VBD should be mounted with read/write type how the VBD appears to the VM, for example disk or CD read/write currently-attached True if the VBD is currently attached on this host, false otherwise read only 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
vdi-uuid= [bootable=true] [type=] [mode=] 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.
The VDI objects can be listed with the standard object listing command (xe vdi-list), and the parameters manipulated with the standard parameter commands. See the section called “Low-level Parameter Commands” for details.
Parameter Name Description Type 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.
SR types that support sparse allocation of disks (such as Local VHD and NFS) do not enforce virtual allocation of disks. Users should therefore take great care when over-allocating virtual disk space on an SR. If an over-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-snapshot vdi-snapshot uuid= [driver-params=] 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.
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.
vlan-create vlan-create pif-uuid= vlan= network-uuid= Create a new VLAN on a XenServer host. pool-vlan-create vlan-create pif-uuid= vlan= network-uuid= Create a new VLAN on all hosts on a pool, by determining which interface (for example, eth0) the specified network is on (on each host) and creating and plugging a new PIF object one each host accordingly.
Parameter Name Description Type version the number of times this VM has been recovered - if a user wishes to over write a new VM with an older version, then they must call vm-recover read only user-version string for creators of VMs and templates to put version information read/write is-a-template False unless this is a template; template VMs can never be started, they are used only for cloning other VMs read/write is-control-domain True if this is a control domain (domain 0 or a driver domain)
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 PV-kernel path to the kernel read/write PV-ramdisk path to the initrd read/write PV-args string of kernel command line arguments read/write PV-legacy-args string of arguments to make legacy VMs boot read/write 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 the VM was last booted read only resident-on the XenSe
Parameter Name Description Type VCPUs-number the number of virtual CPUs assigned to the VM read only For a paravirtualized Linux VM, this number can differ from VCPUS-max and can be changed without rebooting the VM using the vmvcpu-hotplug command. See the section called “vm-vcpuhotplug”. Windows VMs always run with the number of vCPUs set to VCPUs-max and must be rebooted to change this value.
Parameter Name Description Type 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 potential hosts of this VM read only dom-id domain ID (if available, -1 otherwise) read only recommendations XML specification of recommended values and ranges for properties of this VM read only xenstore-data data to be inserted into the xenstore tree (/local/ domain//vmdata) after the VM
vm-assert-can-be-recovered vm-assert-can-be-recovered [] Tests whether storage is available to recover this VM. vm-cd-add vm-cd-add cd-name= device= [=...] Add a new virtual CD to the selected VM. The device parameter should be selected from the value of the allowed-VBD-devices parameter of the 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-clone vm-clone new-name-label= [new-name-description=] [=...] Clone an existing VM, using storage-level fast disk clone operation where available.
List crashdumps associated with the specified VMs. If the optional argument params is used, the value of params is a string containing a list of parameters of this object that you want to display. Alternatively, you can use the keyword all to show all parameters. If params is not used, the returned list shows a default subset of all available parameters. The VM or VMs on which this operation should be performed are selected using the standard selection mechanism (see VM selectors).
Display the specified data source for a VM. Select the VM(s) on which to perform this operation by 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. If no parameters to select hosts are given, the operation will be performed on all VMs. vm-destroy vm-destroy uuid= Destroy the specified VM. This leaves the storage associated with the VM intact.
If the metadata parameter is true, then the disks are not exported, and only the VM metadata is written to the output file. This is intended to be used when the underlying storage is transferred through other mechanisms, and permits the VM information to be recreated (see the section called “vm-import”). The VM or VMs on which this operation should be performed are selected using the standard selection mechanism (see VM selectors).
vm-memory-shadow-multiplier-set vm-memory-shadow-multiplier-set [=...] [multiplier=] Set the shadow memory multiplier for the specified VM. This is an advanced option which modifies the amount of shadow memory assigned to a hardware-assisted VM. In some specialized application workloads, such as Citrix XenApp, extra shadow memory is required to achieve full performance. This memory is considered to be an overhead.
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. This is an advanced command only to be used when a member host in a pool goes down. You can use this command to force the pool master to reset the power-state of the VMs to be halted.
vm-uninstall vm-uninstall [=...] [force=] Uninstall a VM, destroying its disks (those VDIs that are marked RW and connected to this VM only) as well as its metadata record. To simply destroy the VM metadata, use xe vm-destroy. 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.
pool-retrieve-wlb-diagnostics Use the pool-retrieve-wlb-diagnostics command to return the full contents of the Workload Balancing Log file for the Workload Balancing server that the pool is currently using. This command also returns some version information. xe pool-retrieve-wlb-diagnostics \ host-retrieve-wlb-evacuate-recommendations host-retrieve-wlb-evacuate-recommendations uuid= Returns the evacuation recommendations for a host, and a reference to the UUID of the recommendations object.
pool-deconfigure-wlb Permanently deletes all workload balancing configuration. pool-retrieve-wlb-configuration Prints all Workload Balancing configuration information to standard out. pool-retrieve-wlb-recommendations Prints all Workload Balancing recommendations to standard out. pool-retrieve-wlb-report Gets a Workload Balancing report of the specified type and saves it to the specified file. XenCenter uses this command when executing Workload Balancing reports.
xe pool-retrieve-wlb-report report=pool_health_history \ LocaleCode= \ Start=<-3> \ End=<0> \ PoolID= \ UTCOffset=<-5> \ filename=.txt \ xe pool-retrieve-wlb-report report=vm_movement_history \ LocaleCode= \ Start=<-3> \ End=<0> \ PoolID= \ UTCOffset=<-5> \ filename=.
config:HostPifReadThresholdCritical=\ config:HostPifReadThresholdHigh=\ config:set_host_configuration= ...\ ] Use the pool-send-wlb-configuration command with the arguments and to configure Workload Balancing's Host Power Management feature.
Appendix B. Workload Balancing Service Commands Service Commands Run the following service commands on the Workload Balancing appliance. To do so, you must log in to the Workload Balancing virtual appliance. Logging in to the Workload Balancing Virtual Appliance Before you can run any service commands or edit the wlb.conf file, you must log in to the Workload Balancing virtual appliance. To do so, you must enter a user name and password.
Modifying the Workload Balancing configuration options Many Workload Balancing configurations, such as the database and web-service configuration options, are stored in the wlb.conf file, a configuration file on the Workload Balancing virtual appliance. To make it easier to modify the most commonly used options, Citrix provides a command, wlbconfig.
Double-check any values you enter in the wlb.conf file: Workload Balancing does not validate values in the wlb.conf file. Consequently, if the configuration parameters you specify are not within the required range, Workload Balancing does not generate an error log. Increasing the Detail in the Workload Balancing Log The Workload Balancing log provides a list of events on the Workload Balancing virtual appliance, including actions for the analysis engine, database, and audit log.
Logging Option Trace Flag Benefit or Purpose Data Save Trace DataSaveTrace Logs details about the pool being saved to the database. Score Host Trace ScoreHostTrace Logs details about how Workload Balancing is arriving at a score for a host. This trace shows the detailed scores generated by Workload Balancing when it calculates the star ratings for selecting optimal servers for VM placement. Audit Trace Log AuditLogTrace Shows the action of the audit log data being captured and written.
