Network boot installations

Citrix Hypervisor supports booting hosts using the UEFI mode. UEFI mode provides a rich set of standardized facilities to the bootloader and operating systems. This feature allows Citrix Hypervisor to be more easily installed on hosts where UEFI is the default boot mode.

Note:

The legacy DOS partition layout is not supported with UEFI boot.

The following section contains information about setting up your TFTP and NFS, FTP, or HTTP servers to enable PXE and UEFI booting of Citrix Hypervisor server installations. It then describes how to create an XML answer file, which allows you to perform unattended installations.

Configure your PXE and UEFI environment for Citrix Hypervisor installation

Before you set up the Citrix Hypervisor installation media, configure your TFTP and DHCP servers. The following sections contain information on how to configure your TFTP server for PXE and UEFI booting. Consult your vendor documentation for general setup procedures.

Note:

Citrix Hypervisor 6.0 moved from MBR disk partitioning to GUID Partition Table (GPT). Some third-party PXE deployment systems might attempt to read the partition table on a machine’s hard disk before deploying the image to the host.

If the deployment system isn’t compatible with GPT partitioning scheme and the hard disk has previously been used for a version of Citrix Hypervisor that uses GPT, the PXE deployment system might fail. A workaround for this failure is to delete the partition table on the disk.

In addition to the TFTP and DHCP servers, you require an NFS, FTP, or HTTP server to house the Citrix Hypervisor installation files. These servers can co-exist on one, or be distributed across different servers on the network.

Note:

PXE boot is not supported over a tagged VLAN network. Ensure that the VLAN network you use for PXE boot is untagged.

Additionally, each Citrix Hypervisor server that you want to PXE boot must have a PXE boot-enabled Ethernet card.

The following steps assume that the Linux server you are using has RPM support.

Configure your TFTP server for PXE boot

  1. In your TFTP root directory (for example, /tftpboot), create a directory called xenserver

  2. Copy the mboot.c32 and pxelinux.0 files from the installation media to the TFTP root directory.

    Note:

    We strongly recommend using mboot.c32 and pxelinux.0 files from the same source (for example, from the same Citrix Hypervisor ISO).

  3. From the Citrix Hypervisor installation media, copy the files install.img (from the root directory), vmlinuz, and xen.gz (from the /boot directory) to the new xenserver directory on the TFTP server.

  4. In the TFTP root directory (for example, /tftpboot), create a directory called pxelinux.cfg.

  5. In the pxelinux.cfg directory, create your configuration file called default.

    The content of this file depends on how you want to configure your PXE boot environment. Two sample configurations are listed below. The first example configuration starts an installation on any machine that boots from the TFTP server. This installation requires manual responses. The second example configuration is for an unattended installation.

    Note:

    The following examples show how to configure the installer to run on the physical console, tty0. To use a different default, ensure that the console you want to use is the rightmost.

        default xenserver
        label xenserver
            kernel mboot.c32
            append xenserver/xen.gz dom0_max_vcpus=2 \
                dom0_mem=1024M,max:1024M com1=115200,8n1 \
            console=com1,vga ---  xenserver/vmlinuz \
            xencons=hvc console=hvc0 console=tty0 \
            ---  xenserver/install.img
    

    A sample configuration that performs an unattended installation using the answer file at the URL specified:

    Note:

    To specify which network adapter to use to retrieve the answer file, include the answerfile_device=ethX or answerfile_device=MAC parameter and specify either the Ethernet device number or the MAC address of the device.

        default xenserver-auto
        label xenserver-auto
            kernel mboot.c32
            append xenserver/xen.gz dom0_max_vcpus=2 \
                dom0_mem=1024M,max:1024M com1=115200,8n1 \
                console=com1,vga ---  xenserver/vmlinuz \
                xencons=hvc console=hvc0 console=tty0 \
                answerfile=http://pxehost.example.com/answerfile \
                install ---  xenserver/install.img
    

    For more information about PXE configuration file contents, see the SYSLINUX website.

Configure your TFTP server for UEFI boot

To configure your TFTP server for UEFI boot:

  1. In the TFPT root directory (for example, /tftpboot), create a directory called EFI/xenserver.

  2. Configure your DHCP server to provide /EFI/xenserver/grubx64.efi as the boot file.

  3. Create grub.cfg file. For example:

    • For an installation that requires manual responses to installation prompts:

       menuentry "Citrix Hypervisor Install (serial)" {
           multiboot2 /EFI/xenserver/xen.gz dom0_mem=1024M,max:1024M watchdog \
           dom0_max_vcpus=4 com1=115200,8n1 console=com1,vga
           module2 /EFI/xenserver/vmlinuz console=hvc0
           module2 /EFI/xenserver/install.img
       }
      
    • For an unattended installation that uses an answer file:

       menuentry "Citrix Hypervisor Install (serial)" {
           multiboot2 /EFI/xenserver/xen.gz dom0_mem=1024M,max:1024M watchdog \
           dom0_max_vcpus=4 com1=115200,8n1 console=com1,vga
           module2 /EFI/xenserver/vmlinuz console=hvc0 console=tty0 answerfile_device=eth0 answerfile=ftp://ip_address/path_to_answerfile install
           module2 /EFI/xenserver/install.img
       }
      

    For more information about using an answer file, see Creating an answer file for unattended PXE and UEFI installation.

  4. Copy grub.cfg file to EFI/xenserver directory on the TFTP server.

  5. From the Citrix Hypervisor installation media, copy the files grubx64.efi, install.img (from the root directory), vmlinuz, and xen.gz (from the /boot directory) to the new EFI/xenserver directory on the TFTP server.

For details for your specific operating system, see your server operating system manual. The information here is a guide that can be used for Red Hat, Fedora, and some other RPM-based distributions.

To set up the Citrix Hypervisor installation media on an HTTP, FTP or NFS server:

  1. On the server, create a directory from which the Citrix Hypervisor installation media can be exported via HTTP, FTP, or NFS.

  2. Copy the entire contents of the Citrix Hypervisor installation media to the newly created directory on the HTTP, FTP, or NFS server. This directory is your installation repository.

    Note:

    When copying the Citrix Hypervisor installation media, ensure that you copy the file .treeinfo to the newly created directory.

To prepare the destination system:

  1. Start the system and enter the Boot menu (F12 in most BIOS programs).

  2. Select to boot from your Ethernet card.

  3. The system then PXE boots from the installation source you set up, and the installation script starts. If you have set up an answer file, the installation can proceed unattended.

Install Supplemental Packs during Citrix Hypervisor installation

Supplemental Packs are used to modify and extend the capabilities of Citrix Hypervisor by installing software into the control domain (Dom0). For example, an OEM partner might want to ship Citrix Hypervisor with a set of management tools that require SNMP agents to be installed. Users can add supplemental packs either during initial Citrix Hypervisor installation, or at any time afterwards.

When installing supplemental packs during Citrix Hypervisor installation, unpack each supplemental pack into a separate directory.

Facilities also exist for OEM partners to add their supplemental packs to the Citrix Hypervisor installation repositories to allow automated factory installations.

Create an answer file for unattended PXE and UEFI installation

To perform installations in an unattended fashion, create an XML answer file. Here is an example answer file:

<?xml version="1.0"?>
    <installation srtype="ext">
        <primary-disk>sda</primary-disk>
        <guest-disk>sdb</guest-disk>
        <guest-disk>sdc</guest-disk>
        <keymap>us</keymap>
        <root-password>mypassword</root-password>
        <source type="url">http://pxehost.example.com/citrix-hypervisor/</source>
        <post-install-script type="url">
          http://pxehost.example.com/myscripts/post-install-script
        </post-install-script>
        <admin-interface name="eth0" proto="dhcp" />
        <timezone>Europe/London</timezone>
    </installation>

Contain all nodes within a root node named installation.

Note:

To enable thin provisioning, specify an srtype attribute as ext. If this attribute is not specified, the default local storage type is LVM. Thin provisioning sets the local storage type to EXT4 and enables local caching for Citrix Virtual Desktops to work properly. For more information, see Storage.

The following is a summary of the elements. All node values are text, unless otherwise stated. Required elements are indicated.

<primary-disk>

Required? Yes

Description: The name of the storage device where the control domain is installed. This element is equivalent to the choice made on the Select Primary Disk step of the manual installation process.

Attributes: You can specify a guest-storage attribute with possible values yes and no. For example: <primary-disk guest-storage="no">sda</primary-disk>

The default value is yes. If you specify no, you can automate an installation scenario where no storage repository is created. In this case, specify no guest-disk keys.

<guest-disk>

Required? No

Description: The name of a storage device to be used for storing guests. Use one of these elements for each extra disk.

Attributes: None

<keymap>

Required? Yes

Description: The name of the key map to use during installation. <keymap>us</keymap> The default value, us is considered if you do not specify a value for this element.

Attributes: None

You can also perform automated upgrades by changing the answer file appropriately. Set the mode attribute of the installation element to upgrade, specify the disk on which the existing installation lives with the existing-installation element. Leave the primary-disk and guest-disk elements unspecified. For example:

<?xml version="1.0"?>
<installation mode="upgrade">
    <existing-installation>sda</existing-installation>
    <source type="url">http://pxehost.example.com/citrix-hypervisor/</source>
    <post-install-script type="url">
        http://pxehost.example.com/myscripts/post-install-script
    </post-install-script>
</installation>

<root-password>

Required: No

Description: The desired root password for the Citrix Hypervisor server. If a password is not provided, a prompt is displayed when the server is first booted.

Attributes: You can specify a type that is either hash or plaintext

For example:

<root-password type="hash">hashedpassword</root-password>

The hashed value can use any hash type supported by crypt(3) in glibc. The default hash type is SHA-512.

You can use the following Python code to generate a hashed password string to include in the answer file:

python -c 'import crypt; print(crypt.crypt("mypasswordhere", crypt.mksalt(crypt.METHOD_SHA512)))'

<source>

Required: Yes

Description: The location of the uploaded Citrix Hypervisor installation media or a Supplemental Pack. This element can occur multiple times.

Attributes: The attribute type can have one of the following values: url, nfs, or local.

If the value is local, leave the element empty. For example,

<source type="url">http://server/packages</source>
<source type="local" />
<source type="nfs">server:/packages</source>

<script>

Required: No

Description: Where the post-install-script is located.

Attributes:

The attribute stage can have one of the following values: filesystem-populated, installation-start, or installation-complete

  • When the value filesystem-populated is used, the script runs just before root file system is unmounted (for example, after installation/upgrade, initrds already built, etc.). The script receives an argument that is the mount point of the root file system.

  • When the value installation-complete is used, the script runs after the installer has finished all operations (and hence the root file system is unmounted). The script receives an argument that has a value of zero if the installation completed successfully, and is non-zero if the installation failed for any reason.

The attribute type can have one of the following values: url, nfs, or local.

If the value is url or nfs, put the URL or NFS path in the PCDATA. If the value is local, leave the PCDATA empty. For example,

<script stage="filesystem-populated" type="url">
    http://prehost.example.com/post-install-script
</script>
<script stage="installation-start" type="local">
    file:///scripts/run.sh
</script>
<script stage="installation-complete" type="nfs">
    server:/scripts/installation-pass-fail-script
</script>

Note:

If a local file is used, ensure that the path is absolute. This generally means that the file:// prefix is followed by another forward slash, and then the complete path to the script.

<admin-interface>

Required: No

Description: The single network interface to be used as the host administration interface.

Attributes:

Specify one of the following attributes:

  • name - The name of your network interface, for example eth0.
  • hwaddr - The MAC address of your network interface, for example 00:00:11:aa:bb:cc.

The attribute proto can have one of the following values: dhcp or static.

If you specify proto="static", you must also specify all of these child elements:

Child elements

  • <ipaddr>: The IP address
  • <subnet>: The subnet mask
  • <gateway>: The gateway

<timezone>

Required: Yes

Description: The timezone in the format used by the TZ variable, for example Europe/London, or America/Los_Angeles.

<name-server>

Required: No

Description: The IP address of a nameserver. Use one of these elements for each nameserver you want to use.

<hostname>

Required: No

Description: Specify this element if you want to manually set a hostname.

<ntp-server>

Required: No

Description: Specify one or more NTP servers.

Automated upgrades with an answer file

You can also perform automated upgrades by changing the answer file appropriately.

  1. Set the mode attribute of the installation element to upgrade.
  2. Specify the disk on which the existing installation lives with the existing-installation element.
  3. Leave the primary-disk and guest-disk elements unspecified.

For example:

<?xml version="1.0"?>
<installation mode="upgrade">
    <existing-installation>sda</existing-installation>
    <source type="url">http://pxehost.example.com/xenserver/</source>
    <post-install-script type="url">
        http://pxehost.example.com/myscripts/post-install-script
    </post-install-script>
</installation>
Network boot installations