XAPI Pool Join

From Xen

XAPI Pool Join

This page partly describes the internal mechanism behind the pool join process. The ultimate source of truth is in the [source code]: this page simply gives a flavour of the kind of thing that goes on.

The term "candidate host" is used to refer to the host which is attempting to join the pool.


  1. Check that the candidate host does not have HA enabled.
  2. Read the non-shared SRs from the local database.
  3. Log in to the pool's master.
  4. Check that HA isn't enabled in the pool.

Pre-join assertions

  1. Check that the candidate host is not attempting to join itself (assert_not_joining_myself).
  2. Check that there are no other hosts in the local database (assert_i_know_of_no_other_hosts).
  3. Check that there are no running or suspended VMs on the candidate host (assert_no_running_or_suspended_vms_on_me).
  4. Check that there are no VMs with current operations (assert_no_vms_with_current_ops).
  5. Check that hosts are homogeneous in terms of software version and CPU (unless the "force" option is used on the pool join operation) (assert_hosts_homogeneous).
  6. Check that the candidate host has no shared SRs (assert_no_shared_srs_on_me).
  7. Check that the management interface is (or contains) a physical NIC (assert_management_interface_is_physical).
  8. Check that the external authentication type and service name matches the master (assert_external_auth_matches).

Set up

  1. Obtain the pool's "cluster secret" (Client.Pool.initial_auth).
  2. Fetch a backup of the master's database (Pool_db_backup.fetch_database_backup).

Synchronise state with the master

This is done in a best-effort fashion; errors are suppressed. As much state as possible is synchronised.

  1. Get the record for the candidate host (or create one none already exists) (create_or_get_host_on_master).
  2. Create records for SR and PBD on master (SR.introduce; copy other-config over; PBD.create) (create_sr_and_pbd_on_master).
  3. Create records for VMs on master (create_vm_on_master).
  4. Remap VDIs to have SR fields matching the newly created SR records (remap_vdi).
  5. Create records for VDIs on master (create_vdi_on_master).
  6. Remap VBDs to have VDI/VM fields matching the newly created VDI records (remap_vbd).
  7. Create records for VBDs on master (create_vbd_on_master).
  8. Create physical PIFs (create_pif_and_maybe_network). Re-use the corresponding network if the master has a corresponding PIF. Otherwise create a new network.
  9. Remap VIFs to have network fields matching the newly created Network records (remap_vif).
  10. Create records for VIFs on master (create_vif_on_master).
  11. Set the default crashdump SR and default suspend-image SR on the candidate host's host record.


  1. Write the cluster secret to the Xapi_globs.pool_secret_path file.
  2. Set the candidate host's pool role to be a slave (Pool_role.set_role).
  3. Restart xapi (Xapi_fuse.light_fuse_and_run).