Hosts and pools operations

Day-to-day operations on your XCP-ng hosts and resource pools: creating a pool, adding and removing hosts, maintenance mode, passwords, time synchronization, remote power-on and pool-wide settings.

tip

Almost everything on this page can be done in a few clicks from Xen Orchestra, which is the recommended way to operate XCP-ng at scale. The xe commands are given so you can also work directly on a host, script operations, or troubleshoot when the orchestrator is not available.

🎓 Concepts

A resource pool is a group of up to 64 XCP-ng hosts managed as a single entity. One host is the pool coordinator (formerly called "pool master"): it exposes the XAPI endpoint for the whole pool, holds the pool database and forwards operations to the other members. All members keep a replicated copy of that database, which is why another host can take over the coordinator role if needed.

Why create a pool rather than managing standalone hosts?

• Live migration of VMs between hosts of the pool.
• Shared storage: an SR created on the pool is visible to all members, so VMs can start anywhere.
• Single point of management: one connection, one inventory, pool-wide networks and settings.
• High availability and VM load balancing both operate at the pool level.

A resource pool · one XAPI endpoint, a replicated database, shared storageXAPIreplicated pool DB

The requirements for pooling hosts (hardware, CPU vendor, versions…) are described in the pool requirements section.

info

A standalone host is simply a pool of one: there's no special "pool creation" step. You create a pool by joining a second host to the first one.

🏗️ Create a pool

Name the pool

A freshly installed host belongs to its own unnamed pool. Give it a name, which will be the pool's name once you add more hosts:

root@xcp-ng-host — Name the pool

# xe pool-param-set uuid=<pool-uuid> name-label="My pool"

From Xen Orchestra, simply edit the pool name from the pool view.

Add a host to the pool

From Xen Orchestra: open the pool and use the Add hosts action, then pick the standalone host(s) to include.

With xe, run this on the host that should join the pool:

root@xcp-ng-host — Add a host to the pool

# xe pool-join master-address=<coordinator-ip-or-fqdn> master-username=root master-password=<password>

What happens on join:

• The host fetches the pool database and becomes a member: from now on, you manage it through the pool coordinator.
• Its local SRs remain available, as local storage of that member.
• Pool-wide settings (networks, TLS verification, update channels…) are inherited from the pool.

warning

The joining host must be "clean": no running or suspended VMs, and its version must match the rest of the pool. VMs should be exported/moved before the join, or shut down.

Heterogeneous pools

Hosts with different CPUs (same vendor!) can be pooled: XAPI automatically levels the CPU feature set exposed to VMs down to the common denominator, so live migration stays safe across all members. Mixing Intel and AMD hosts in the same pool is not possible.

If the hosts differ in a way that blocks a regular join, you can force it, and take responsibility for the consequences:

root@xcp-ng-host — Heterogeneous pools

# xe pool-join master-address=<coordinator> master-username=root master-password=<password> force=true

🚪 Remove a host from a pool

From Xen Orchestra, use the host's Detach action. With xe:

root@xcp-ng-host — Remove a host from a pool

# xe pool-eject host-uuid=<host-uuid>

warning

Ejecting a host reinstalls its XAPI state: the host reboots and comes back as a fresh standalone host. The contents of its local SRs are destroyed in the process. Move or export any VM disk you care about beforehand. Shared SR contents are not affected.

If the host to remove is dead and cannot be ejected cleanly, you can remove its record from the pool database instead:

root@xcp-ng-host — Remove a host from a pool

# xe host-forget uuid=<host-uuid>

host-forget doesn't touch the (dead) host itself: if it ever comes back online, it will still believe it belongs to the pool, so reinstall it before reuse.

👑 Change the pool coordinator

Planned change

With all hosts up and reachable, you can hand the coordinator role to another member at any time. This is transparent for running VMs:

root@xcp-ng-host — Planned change

# xe pool-designate-new-master host-uuid=<new-coordinator-uuid>

Coordinator is down

If the coordinator is lost and you don't use HA (which handles this automatically), promote a surviving member. Run these on that member:

root@xcp-ng-host — Coordinator is down

# xe pool-emergency-transition-to-master
# xe pool-recover-slaves

The first command makes the local host the new coordinator; the second tells the remaining members to point at it. See also HA troubleshooting when high availability is involved.

🔧 Maintenance mode

Before rebooting a host or working on its hardware, put it in maintenance mode: it stops accepting new VMs and evacuates the running ones (live migrating them to the other members).

From Xen Orchestra: Maintenance mode toggle on the host view. With xe:

root@xcp-ng-host — Maintenance mode

# xe host-disable uuid=<host-uuid>
# xe host-evacuate uuid=<host-uuid>

If some VMs cannot be moved (e.g. a disk on that host's local SR, or not enough memory elsewhere), the evacuation tells you why; you can also ask beforehand:

root@xcp-ng-host — Maintenance mode

# xe host-get-vms-which-prevent-evacuation uuid=<host-uuid>

When you're done, bring the host back into service:

root@xcp-ng-host — Maintenance mode

# xe host-enable uuid=<host-uuid>

See also the dedicated guide about rebooting or shutting down a host, and the updates documentation for the recommended way to patch a whole pool (Rolling Pool Update in Xen Orchestra).

🔑 Root password

The root password of the hosts is what XAPI clients (Xen Orchestra, XO Lite, xe…) use to authenticate. All members of a pool are meant to share the same root password (a joining host adopts the pool's credentials).

To change it, from the pool coordinator:

root@xcp-ng-host — Root password

# xe user-password-change old=<current-password> new=<new-password>

You can also use xsconsole (the text console you get on the host's physical/serial display), in Authentication → Change Password.

Lost the root password? See the reset procedure in the troubleshooting section.

⏰ Time synchronization (NTP)

Correct and consistent clocks across the pool matter more than on ordinary servers: XAPI coordination, live migration, HA heartbeats, logs correlation and Windows guests (which get their initial time from the host) all rely on it. NTP servers are normally configured at installation time.

To change them afterwards on XCP-ng 8.3, edit /etc/chrony.conf, then:

Time synchronization (NTP)

# systemctl restart chronyd
# chronyc sources

On XCP-ng 8.2, the NTP daemon is ntpd: edit /etc/ntp.conf, then systemctl restart ntpd and check with ntpq -p. In both cases, xsconsole also offers an NTP configuration menu under Network and Management Interface.

🔌 Remote host power-on

XCP-ng can power hosts back on remotely, using either Wake-on-LAN or the server's out-of-band controller. Configure the method per host:

root@xcp-ng-host — Remote host power-on

# xe host-set-power-on-mode host=<host-uuid> power-on-mode=wake-on-lan

power-on-mode also accepts iLO, DRAC or custom (with power-on-config: parameters for the controller's IP and credentials), or an empty string to disable the feature. Then, to power on a host from anywhere in the pool:

root@xcp-ng-host — Remote host power-on

# xe host-power-on host=<host-uuid>

This capability is also what allows VM load balancing density plans to power hosts off and on according to the load.

🤝 Pool-wide settings

Rotate the pool secret

Members of a pool authenticate each other with a shared secret. Rotate it if you suspect it leaked, or after removing hosts you don't fully trust anymore:

root@xcp-ng-host — Rotate the pool secret

# xe pool-secret-rotate

IGMP snooping

If your VMs use multicast, enabling IGMP snooping avoids flooding every VIF of a network with multicast traffic:

root@xcp-ng-host — IGMP snooping

# xe pool-param-set uuid=<pool-uuid> igmp-snooping-enabled=true

Restrict port 80 (HTTPS only)

Starting with XCP-ng 8.3, plain HTTP on port 80 is restricted by default. You can control it explicitly:

root@xcp-ng-host — Restrict port 80 (HTTPS only)

# xe pool-param-set uuid=<pool-uuid> https-only=true

Leave it to true unless something in your tooling still requires port 80.

Certificate verification

XCP-ng 8.3 pools can verify TLS certificates for pool-internal communication:

root@xcp-ng-host — Certificate verification

# xe pool-enable-tls-verification

See the TLS certificates guide for certificate management (custom certificates, renewal, resets).

Migration compression

Starting with XCP-ng 8.3, the live migration memory stream can be compressed. Very useful when the migration network is the bottleneck, at the cost of some dom0 CPU:

root@xcp-ng-host — Migration compression

# xe pool-param-set uuid=<pool-uuid> migration-compression=true

The setting applies pool-wide to subsequent migrations; Xen Orchestra also exposes it in the pool's advanced settings.

🩺 Pool database backup

The pool database (all your XAPI objects: VMs, SRs, networks…) is replicated on every member, and can also be exported and restored: see the backup page for pool metadata backup and restore procedures.