Install XCP-ng

How to install XCP-ng.

ISO installation

If you want to use the netinstall ISO, see the Netinstall section.

Download and create media

You can download the latest installer for XCP-ng 8.3 LTS from here: https://mirrors.xcp-ng.org/isos/8.3/xcp-ng-8.3.0-20260806.iso?https=1.

SHA256 checksums, GPG signatures and net-install ISOs are available here.

Then, create the install media (e.g. a USB key 1GB or larger should work):

Download and create media

# example with XCP-ng 8.3
# dd if=xcp-ng-8.3.0-20260806.iso of=/dev/sdX bs=8M oflag=direct

Finally, boot on that media and go to the next section.

tip

On Windows, you can use Rufus to create the bootable USB stick.

Start the host

Start the host and boot on the USB media.

Follow instructions

1. UEFI vs BIOS

Boot screens are just slightly different on start between BIOS and UEFI mode:

BIOS splash screen:

UEFI splash screen:

warning

NEVER switch from UEFI to BIOS (or vice-versa) after you installed XCP-ng. Stick to the mode that you chose during the install.

2. Language selection

3. Welcome

4. EULA/license

5. Disk selection

This is the screen where you'll select where XCP-ng will be installed. XCP-ng is a specialized Linux distribution, so you need to dedicate a physical disk to it. Partitioning is done automatically.

Alternatively, if you have two identical disks, you can use Software RAID (mdadm) :

tip

If only one disk is deemed suitable for the installation, this step is skipped. The name of the device will be displayed in the "Confirm Installation" step, later in the process.

6. VM storage selection

This is the place where your VM disks will be stored. It's called a Storage Repository (SR). It can use the same disk you installed the system on. It will automatically use the free space after system partitions.

tip

EXT instead of LVM? We advise to use EXT to benefit from thin provisioning!

warning

When the installer skips step 5, users sometimes mistake this step with the selection of the system disk.

7. Installation source

If you use the default ISO, just select "Local media":

Then, you can verify your media or not:

8. Host password

This will be the root password, used to connect to the host with SSH and XAPI.

9. Networking

Here you can select between DHCP and static network, even using a VLAN:

10. Hostname and DNS

Configure the hostname of your server and the DNS resolvers.

11. Timezone and time

warning

ALWAYS use a NTP server. It's a critical component to manage your host(s). If you don't know any NTP server, you can use pool.ntp.org.

12. Installation

warning

After this step, data will be written on the disk(s)! Check the listed device(s) one last time.

13. Supplemental packs and end of install

Not relevant in almost all cases. Skip it:

tip

"Completing installation" is in fact installing the bootloader and building the initramfs. It can take time.

14. Reboot

After a reboot, you should see the GRUB menu:

It means the system is correctly installed! Enjoy XCP-ng 🚀

Netinstall

The netinstall image is a lightweight ISO (around 150MiB) that will only contain the installer, but no actual RPM packages. Sometimes, it's more convenient/faster when your ISO is on a slow connection (e.g. a virtual media using a server IPMI).

You can download it on this URL: https://mirrors.xcp-ng.org/isos/8.3/xcp-ng-8.3.0-20260806-netinstall.iso?https=1.

As with the regular installation ISO, write it on a USB media:

Netinstall

# dd if=xcp-ng-8.3.0-20260806-netinstall.iso of=/dev/sdX bs=8M oflag=direct

Everything else is like the regular install, except that it will not offer to install from local media, only from distant ones.

PXE boot install

Requirements

To get XCP-ng installed from PXE, you need:

• DHCP and TFTP configured servers
• Any NFS, FTP or HTTP server (your choice) to host XCP-ng installation files
• A PXE-boot compatible network card on your host

tip

PXE boot doesn't support tagged VLAN networks! Be sure to boot on a untagged network!

TFTP server configuration

TFTP server configuration - BIOS boot

1. In your TFTP root directory (eg /tftp), create a folder named xcp-ng.
2. Copy the mboot.c32 and pxelinux.0 files from the installation media to the TFTP root directory.
3. From the XCP-ng installation media, copy the files install.img (from the root directory), vmlinuz, and xen.gz (from the /boot directory) to the new xcp-ng directory on the TFTP server.
4. In the TFTP root directory, create a folder called pxelinux.cfg
5. In the pxelinux.cfg directory, create your configuration file called default.

The file itself will contain the way to install XCP-ng: manually (with answer to provide on the host console/screen) or fully automated (see Automated install below).

Here is an example of a manual installation:

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

How TFTP folder looks like when configured

TFTP server configuration - BIOS boot

# tree -L 1 /srv/tftp/
srv/tftp
├── mboot.c32
├── pxelinux.0
├── pxelinux.cfg
│   └── default
└── xcp-ng
  ├── install.img
  ├── vmlinuz
  └── xen.gz

TFTP server configuration - UEFI boot

If you want to make an installation in UEFI mode, you need to have a slightly different TFTP server configuration:

1. In your TFTP root folder, create a directory called EFI/xcp-ng
2. Configure your DHCP server to provide /EFI/xcp-ng/grubx64.efi as the boot file
3. Create a grub.cfg as follows:

 menuentry "XCP-ng Install (serial)" {
    multiboot2 /EFI/xcp-ng/xen.gz dom0_mem=2048M,max:2048M watchdog \
    dom0_max_vcpus=4 com1=115200,8n1 console=com1,vga
    module2 /EFI/xcp-ng/vmlinuz console=hvc0 console=tty0 install
    module2 /EFI/xcp-ng/install.img
 }

4. Copy this grub.cfg file to the EFI/xenserver folder on the TFTP server
5. Copy the following files from the XCP-ng ISO: grubx64.efi, install.img (from the root directory), vmlinuz, and xen.gz (from the /boot directory) to the new EFI/xcp-ng directory on the TFTP server.

How TFTP folder looks like when configured

TFTP server configuration - UEFI boot

# tree -L 1 /srv/tftp/
srv/tftp
└── EFI
  ├── xcp-ng
  │   ├── grubx64.efi
  │   ├── install.img
  │   ├── vmlinuz
  │   └── xen.gz
  └── xenserver
      └── grub.cfg

On the FTP, NFS or HTTP server, get all the installation media content in there.

For a layout example check the official repository.

tip

When you do copy the installation files, DO NOT FORGET the .treeinfo file. Double check your webserver isn't blocking it (like Microsoft IIS does).

On the host

1. Start your host
2. Enter the boot menu (usually F12)
3. Select boot from the Ethernet card
4. You should see the PXE menu you created before!

iPXE over HTTP install

This guide is for UEFI boot, using iPXE over an HTTP server to serve files needed for installation.

Requirements

To get XCP-ng installed from iPXE over HTTP, you need:

• An HTTP server to host the XCP-ng installation files
• An iPXE-compatible network card and firmware on your host

1. In your HTTP root directory copy the contents of the net install ISO.

The top-level should look like this:

Requirements

# tree -L 1 /path/to/http-directory/
.
├── EFI
├── EULA
├── LICENSES
├── RPM-GPG-KEY-CH-8
├── RPM-GPG-KEY-CH-8-LCM
├── RPM-GPG-KEY-Platform-V1
├── boot
└── install.img

2. Boot the target machine.
3. Press Ctrl-B to catch the iPXE menu. Use the chainload command to load grub.

chain http://SERVER_IP/EFI/xenserver/grubx64.efi

tip

Sometimes grub takes a very long time to load after displaying "Welcome to Grub". This can be fixed by compiling a new version of Grub with grub-mkstandalone.

4. Once the grub prompt loads, set the root to http and load the config file.

# Replace with your server's IP
set root=(http,SERVER_IP)
configfile /EFI/xenserver/grub.cfg

5. Select the "Install" menu entry.
6. Wait for grub to load the necessary binaries. This may take a minute. If you look at your http server log you should see something like:

# (from python3 -m http.server path-to-directory 80)

192.168.0.10 - - [11/Mar/2021 03:25:58] "GET /boot/xen.gz HTTP/1.1" 200 -
192.168.0.10 - - [11/Mar/2021 03:25:58] "GET /boot/vmlinuz HTTP/1.1" 200 -
192.168.0.10 - - [11/Mar/2021 03:26:03] "GET /install.img HTTP/1.1" 200 -

7. Continue with installation as normal.

Automated install

XCP-ng's installation can be automated by using network boot (PXE) or a custom installation image.

Answerfile

Unattended installation requires what is called an answer file, often spelled answerfile.

It is an XML file that contains the answers to questions the installer would ask during a manual installation.

Here is an example:

<?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/xcp-ng/</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/Paris</timezone>
    </installation>

tip

Check the full answerfile reference.

Via PXE

Follow the previous section on Network boot (PXE) and add options to that will fetch and use an answer file.

PXE unattended install - BIOS boot

Add answerfile=http://your_server/path/to/answerfile.xml install to the parameters passed to vmlinuz (the linux kernel of the installer).

Example:

default xcp-ng-auto
label xcp-ng-auto
    kernel mboot.c32
    append xcp-ng/xen.gz dom0_max_vcpus=2 dom0_mem=2048M,max:2048M com1=115200,8n1 console=com1,vga --- xcp-ng/vmlinuz xencons=hvc console=hvc0 console=tty0 answerfile=http://your_server/path/to/answerfile.xml install --- xcp-ng/install.img

tip

Any SYSLINUX configuration style file will be valid. Find more on the syslinux website.

PXE unattended install - UEFI boot

Add answerfile=http://your_server/path/to/answerfile.xml install to the parameters passed to vmlinuz (the Linux kernel of the installer).

Example:

menuentry "XCP-ng Install (serial)" {
    multiboot2 /EFI/xcp-ng/xen.gz dom0_mem=2048M,max:2048M watchdog dom0_max_vcpus=4 com1=115200,8n1 console=com1,vga
    module2 /EFI/xcp-ng/vmlinuz console=hvc0 console=tty0 answerfile_device=eth0 answerfile=http://your_server/path/to/answerfile.xml install
    module2 /EFI/xcp-ng/install.img
}

Unattended installation with a custom ISO image

You may build a custom installation image that will automatically install XCP-ng. The answerfile can either be downloaded by the installer or embedded in the image itself.

Unattended installation ISO with remote config

If you can't or don't want to setup PXE but can still serve a file (the answerfile) from a server that will be available to the hosts during installation, you can create an automated installation image that will fetch its configuration from the network.

1. Prepare an answerfile and make it available from a local HTTP server
2. Extract the XCP-NG ISO file
3. Modify the boot configuration to use the remote answerfile

• For BIOS boot, edit /boot/isolinux/isolinux.cfg.
  • Locate the install boot entry, which should look like this:

  LABEL install
      KERNEL mboot.c32
      APPEND /boot/xen.gz dom0_max_vcpus=1-16 dom0_mem=max:8192M com1=115200,8n1 console=com1,vga --- /boot/vmlinuz console=hvc0 console=tty0 --- /install.img

  • Append answerfile=http://your_server/path/to/answerfile.xml install to the parameters passed to vmlinuz, before the last ---:

  LABEL install
      KERNEL mboot.c32
      APPEND /boot/xen.gz dom0_max_vcpus=1-16 dom0_mem=max:8192M com1=115200,8n1 console=com1,vga --- /boot/vmlinuz console=hvc0 console=tty0 answerfile=http://your_server/path/to/answerfile.xml install --- /install.img

• For UEFI boot edit /EFI/xenserver/grub.cfg (and /EFI/xenserver/grub-usb.cfg for USB installation).
  • Locate the install menuentry, which should look like this:

  menuentry "install" {
      multiboot2 /boot/xen.gz dom0_max_vcpus=1-16 dom0_mem=max:8192M com1=115200,8n1 console=com1,vga
      module2 /boot/vmlinuz console=hvc0 console=tty0
      module2 /install.img
  }

  • Append answerfile=http://your_server/path/to/answerfile.xml install to the parameters passed to vmlinuz, in the line that starts with module2 /boot/vmlinuz:

  menuentry "install" {
      multiboot2 /boot/xen.gz dom0_max_vcpus=1-16 dom0_mem=max:8192M com1=115200,8n1 console=com1,vga
      module2 /boot/vmlinuz console=hvc0 console=tty0 answerfile=http://your_server/path/to/answerfile.xml install
      module2 /install.img
  }

4. Build a new ISO with your changes

Your ISO is ready for installation.

Unattended installation ISO with embedded config

If you can neither setup PXE nor serve the answerfile from a server that will be available to the hosts during installation, you can create an automated installation image that will embed its own configuration. It's a bit more work and will need to be done again every time you want to modify the answerfile.

1. Prepare an answerfile
2. Extract the XCP-NG ISO file
3. Modify the boot configuration to use a local (= embedded in the ISO) answerfile

• For BIOS boot, edit /boot/isolinux/isolinux.cfg.
  • Locate the install boot entry, which should look like this:

  LABEL install
      KERNEL mboot.c32
      APPEND /boot/xen.gz dom0_max_vcpus=1-16 dom0_mem=max:8192M com1=115200,8n1 console=com1,vga --- /boot/vmlinuz console=hvc0 console=tty0 --- /install.img

  • Append answerfile=file:///answerfile.xml install to the parameters passed to vmlinuz, before the last ---:

  LABEL install
      KERNEL mboot.c32
      APPEND /boot/xen.gz dom0_max_vcpus=1-16 dom0_mem=max:8192M com1=115200,8n1 console=com1,vga --- /boot/vmlinuz console=hvc0 console=tty0 answerfile=file:///answerfile.xml install --- /install.img

• For UEFI boot edit /EFI/xenserver/grub.cfg (and /EFI/xenserver/grub-usb.cfg for USB installation).
  • Locate the install menuentry, which should look like this:

  menuentry "install" {
      multiboot2 /boot/xen.gz dom0_max_vcpus=1-16 dom0_mem=max:8192M com1=115200,8n1 console=com1,vga
      module2 /boot/vmlinuz console=hvc0 console=tty0
      module2 /install.img
  }

  • Append answerfile=file:///answerfile.xml install to the parameters passed to vmlinuz, in the line that starts with module2 /boot/vmlinuz:

  menuentry "install" {
      multiboot2 /boot/xen.gz dom0_max_vcpus=1-16 dom0_mem=max:8192M com1=115200,8n1 console=com1,vga
      module2 /boot/vmlinuz console=hvc0 console=tty0 answerfile=file:///answerfile.xml install
      module2 /install.img
  }

4. Extract install.img

5. Add your answerfile

   cp answerfile.xml "$WORK_DIR/install/answerfile.xml"

6. Build a new install.img with your changes

7. Build a new ISO with your changes

Your ISO is ready for installation.

Software RAID in answerfile

For an automated install using an answer file, software raid can be enabled as follows:

<?xml version="1.0"?>
<installation mode="fresh" srtype="lvm">
    <raid device="md127">
        <disk>sda</disk>
        <disk>sdb</disk>
    </raid>
    <primary-disk>md127</primary-disk>
    <keymap>us</keymap>
    <source type="url">https://xcp-ng.org/install/</source>
    <admin-interface name="eth0" proto="dhcp" />
    <timezone>Europe/London</timezone>
    <root-password>secret</root-password>
</installation>

As an improvement and to delay the md resync (increasing install speed by about 500% on certain drives), we can use the following in the answer file:

<script stage="installation-start" type="url">http://your-server/noresync.sh</script>

The noresync.sh script would do something like this:

Software RAID in answerfile

#!/bin/sh
# echo 0 > /proc/sys/dev/raid/speed_limit_max
# echo 0 > /proc/sys/dev/raid/speed_limit_min

Upon server reboot, normal md resync will take place.

Boot from SAN

Instead of local disks, a host can be installed on (and boot from) a SAN LUN. Facts verified against the XCP-ng installer:

• Hardware HBA (Fibre Channel, FCoE HBA, SAS, hardware iSCSI): the HBA presents the LUN like a local disk, so the installer simply shows it in the disk selection step. Configure the HBA's boot BIOS so the server firmware boots from it.
• Software iSCSI boot (iBFT): on NICs whose firmware supports iSCSI boot (iBFT), boot the installer with the use_ibft parameter: it reads the iSCSI target configuration from the firmware, connects to the LUN and offers it as an installation target. The NIC used for iSCSI is then reserved for storage traffic.
• Multipath: if the LUN is reachable over several paths, also boot the installer with device_mapper_multipath=enabled so the installation lands on the multipath device and the host boots with multipathing active from the start. Without it, installing on one bare path makes the "redundant" boot disk a single point of failure.

To pass these parameters, edit the boot entry at the installer's boot menu (or add them to your PXE configuration, next to the other installer parameters), for example:

device_mapper_multipath=enabled use_ibft

The same applies to automated installs: these are installer boot parameters, they go on the kernel command line, not in the answer file.

Advanced installation options (installer command-line parameters)

The XCP-ng installer can be further parameterized to support advanced installation environments. The command line options are passed as parameters to the vmlinuz kernel of the installer.

Definitions

"scriptlocation"

An URL pointing at a script. All URLs except for file:// trigger initialization of networking during the installer execution.

• file:/// - file inside the filesystem of the installer environment (i.e. install.img)
• ftp:// - file on an FTP server, fetched with urllib2
• http:// - file on an HTTP server, fetched with urllib2
• https:// - file on an HTTPS server, fetched with urllib2
• nfs:// - file on an NFS server, the directory is mounted and the file accessed

A script is either XML (for answerfile= or rt_answerfile=) or an executable script expected to begin with a shebang. The following interpreters are recognized.

• /bin/sh
• /bin/bash
• /usr/bin/python
• /usr/bin/env python

Environment

sshpassword="password"

Start an ssh server during installation allowing root to log-on interactively with the given password.

Behaviour

device_mapper_multipath=disabled|enabled

Run the installation on top of multipath devices, for boot from SAN setups. Default: disabled.

use_ibft

Read the NIC firmware's iBFT to determine the iSCSI boot configuration, for software boot from SAN.

atexit=reboot|poweroff|shell

Action to perform when the installer is finished.

• poweroff - power off the system
• reboot (default) - reboot the sytem
• shell - drop to shell after running the installer. NB: The installation target is already unmounted.

bash-shell

See shell.

console="devicename"

Use the named console device for the installer. Can be given multiple times.
E.g. console=hvc0 console=tty0

reboot

See atexit=reboot.

shell

Start a shell before running the installer.

Networking

If networking is required (e.g. to fetch an answerfile or access a repository) the installer will configure the detected network cards.

network_config=dhcp[:vlan="id"]

configure interface using DHCP optionally using a VLAN.

• vlan="id" - create a virtual interface tagging with vlan id backed by the underlying interfance.

network_config=static:"network configuration"

configure interface with provided static information. The configuration is a ; separated list of stanzas.

• ip (mandatory)="IP address"
• netmask (mandatory)="netmask"
• vlan="id" - create a virtual interface tagging with vlan id backed by the underlying interfance.
• gateway="gateway address" - use specified address as default route
• dns="DNS resolver address"[,"additional DNS resolver address"] -- use specified address(es) as resolvers
• domain="domain name" - use specified domain name as search domain

network_device="eth"|"mac"|all

Bring up networking on the given interface(s) to allow installer to fetch network resources.

• "eth" - the name of a network interface
• "mac"- the MAC address of a network interface
• all (default) - all network interfaces available to the installer's kernel environment

Automation

answerfile="scriptlocation"

Read the scriptlocation and perform non-interactive installation reporting status using screens interface. Cannot be used together with answerfile_generator=.

rt_answerfile="scriptlocation"

Read the scriptlocation and perform non-interactive installation reporting status using simple text to the console. Cannot be used together with answerfile_generator=.

answerfile_generator="scriptlocation"

Read the scriptlocation execute it and use its standard output as an answerfile to perform non-interactive installation. Cannot be used together with answerfile= or rt_answerfile=.

answerfile_device=

See network_device=.

Troubleshooting

See the Troubleshooting page.

Misc

Installation on USB drives

danger

We strongly discourage the installation of XCP-ng on USB drives. The frequent writing actions required by XCP-ng can rapidly degrade a USB drive due to:

• XAPI: This is the XenServer API database, which undergoes constant changes. This results in significant write operations, which are detrimental to the longevity of USB drives. Note: The XAPI database maintains the state of all XCP-ng operations and is replicated across each host (from the slave).
• Logs: XCP-ng generates a substantial amount of debug logs. A possible solution is to use a remote syslog.

Installation on SD cards

danger

For similar reasons as USB drives, we highly recommend against installing XCP-ng on SD cards. Opting for even a basic SSD would be vastly more effective in managing the XCP-ng system.