OCF_HEARTBEAT_VIRTUA(7)

💖 ocf_heartbeat_VirtualDomain(7) — the libvirt resource agent, explained 💖

okay so bestie, this is the man page for ocf_heartbeat_VirtualDomain, a.k.a. the VirtualDomain resource agent 🎀 — it lives in the OCF resource agents family and honestly it's kind of a big deal if you're running VMs in a cluster.

---

✨ NAME ✨

ocf_heartbeat_VirtualDomain — manages virtual domains through the libvirt virtualization framework 🦋

---

🌸 SYNOPSIS 🌸

VirtualDomain [start | stop | status | monitor | migrate_to |
              migrate_from | meta-data | validate-all]

---

💅 DESCRIPTION 💅

so this is a resource agent for a virtual domain — and like, "virtual domain" can mean a domU, a virtual machine, a virtual environment, whatever your fave terminology is depending on context — the point is, it's managed by libvirtd 💜

and here's the cute part: this resource agent may be configured for native migration if that's available in your cluster manager. For Pacemaker specifically, the allow-migrate="true" meta attribute is what enables native migration. no cap, that's the switch 🔥

---

👑 SUPPORTED PARAMETERS 👑

• config — absolute path to the libvirt configuration file for this virtual domain. It's unique, required, a string, and has no default — so like, you must give it 💅
• hypervisor — hypervisor URI to connect to. Check the libvirt documentation for deets on supported URI formats bestie. The default is system dependent — you can figure out your system's default uri by running virsh --quiet uri. Optional, string, no default.
• force_stop — always forcefully shut down ("destroy") the domain on stop. The default behavior is to resort to a forceful shutdown only after a graceful shutdown attempt has failed. Only set this to true if your virtual domain (or your virtualization backend) does not support graceful shutdown. Optional, boolean, default 0.
• migration_transport — the transport used to connect to the remote hypervisor while migrating. Refer to the libvirt documentation for details on which transports are available. If this parameter is omitted, the resource will use libvirt's default transport to connect to the remote hypervisor. Optional, string, no default.
• migration_user — the username will be used in the remote libvirt remoteuri/migrateuri. No user will be given (which means root) in the username if omitted.

heads up: if remoteuri is set, migration_user will be ignored 🙈

Optional, string, no default.

• migration_downtime — define max downtime during live migration in milliseconds. Optional, integer, default 0.
• migration_speed — define live migration speed per resource in MiB/s. Optional, integer, default 0.
• migration_network_suffix — use a dedicated migration network 🧚. The migration URI is composed by adding this parameter's value to the end of the node name. If the node name happens to be an FQDN (as opposed to an unqualified host name), insert the suffix immediately prior to the first period (.) in the FQDN. At the moment Qemu/KVM and Xen migration via a dedicated network is supported. Note: be sure this composed host name is locally resolvable and the associated IP is reachable through the favored network. This suffix will be added to the remoteuri and migrateuri parameters. See also the migrate_options parameter below ⭐ Optional, string, no default.
• migrateuri — you can also specify here if the calculated migrate URI is unsuitable for your environment. If migrateuri is set then migration_network_suffix, migrateport and --migrateuri in migrate_options are effectively ignored. Use "%n" as the placeholder for the target node name. Please refer to the libvirt documentation for details on guest migration. Optional, string, no default.
• migrate_options — extra virsh options for the guest live migration. You can also specify here --migrateuri if the calculated migrate URI is unsuitable for your environment. If --migrateuri is set then migration_network_suffix and migrateport are effectively ignored. Use "%n" as the placeholder for the target node name. Please refer to the libvirt documentation for details on guest migration. Optional, string, no default.
• monitor_scripts — to additionally monitor services within the virtual domain, add this parameter with a list of scripts to monitor. Note: when monitor scripts are used, the start and migrate_from operations will complete only when all monitor scripts have completed successfully. Be sure to set the timeout of these operations to accommodate this delay 😭⏳ Optional, string, no default.
• autoset_utilization_cpu — if set true, the agent will detect the number of domainU's vCPUs from virsh, and put it into the CPU utilization of the resource when the monitor is executed. Optional, boolean, default true.
• autoset_utilization_host_memory — if set true, the agent will detect the number of Max memory from virsh, and put it into the host_memory utilization of the resource when the monitor is executed. Optional, boolean, default true.
• autoset_utilization_hv_memory — if set true, the agent will detect the number of Max memory from virsh, and put it into the hv_memory utilization of the resource when the monitor is executed. Optional, boolean, default true.
• unset_utilization_cpu — if set true then the agent will remove the cpu utilization resource when the monitor is executed. Optional, boolean, default false.
• unset_utilization_host_memory — if set true then the agent will remove the host_memory utilization resource when the monitor is executed. Optional, boolean, default false.
• unset_utilization_hv_memory — if set true then the agent will remove the hv_memory utilization resource when the monitor is executed. Optional, boolean, default false.
• migrateport — this port will be used in the qemu migrateuri. If unset, the port will be a random highport. Optional, integer, no default.
• remoteuri — use this URI as virsh connection URI to commuicate with a remote hypervisor. (yes, that's the original spelling, we keep it exactly 💅) If remoteuri is set then migration_user and migration_network_suffix are effectively ignored. Use "%n" as the placeholder for the target node name. Please refer to the libvirt documentation for details on guest migration. Optional, string, no default.
• save_config_on_stop — changes to a running VM's config are normally lost on stop 😭. This parameter instructs the RA to save the configuration back to the xml file provided in the "config" parameter. Optional, boolean, no default.
• sync_config_on_stop — setting this automatically enables save_config_on_stop. When enabled this parameter instructs the RA to call csync2 -x to synchronize the file to all nodes. csync2 must be properly set up for this to work. Optional, boolean, no default.
• snapshot — path to the snapshot directory where the virtual machine image will be stored. When this parameter is set, the virtual machine's RAM state will be saved to a file in the snapshot directory when stopped. If on start a state file is present for the domain, the domain will be restored to the same state it was in right before it stopped last. This option is incompatible with the 'force_stop' option ⚠️. Optional, string, no default.
• backingfile — when the VM is used in Copy-On-Write mode, this is the backing file to use (with its full path). The VM's image will be created based on this backing file. This backing file will never be changed during the life of the VM. Optional, string, no default.
• stateless — if set to true and backingfile is defined, the start of the VM will systematically create a new qcow2 based on the backing file, therefore the VM will always be stateless. If set to false, the start of the VM will use the COW (<vmname>.qcow2) file if it exists, otherwise the first start will create a new qcow2 based on the backing file given as backingfile. Optional, boolean, default false.
• copyindirs — list of directories for the virt-copy-in before booting the VM. Used only in stateless mode. Optional, string, no default.
• shutdown_mode — virsh shutdown method to use. Please verify that it is supported by your virsh toolsed with 'virsh help shutdown'. When this parameter is set --mode shutdown_mode is passed as an additional argument to the 'virsh shutdown' command. One can use this option in case default acpi method does not work. Verify that this mode is supported by your VM. By default --mode is not passed. Optional, string, no default.
• start_resources — start the virtual storage pools and networks used by the virtual machine before starting it or before live migrating it. Optional, boolean, default false.

---

🦋 SUPPORTED ACTIONS 🦋

this resource agent supports the following actions (operations), periodt:

• start — starts the resource. Suggested minimum timeout: 90s.
• stop — stops the resource. Suggested minimum timeout: 90s.
• status — performs a status check. Suggested minimum timeout: 30s. Suggested interval: 10s.
• monitor — performs a detailed status check. Suggested minimum timeout: 30s. Suggested interval: 10s.
• migrate_from — executes steps necessary for migrating the resource away from the node. Suggested minimum timeout: 60s.
• migrate_to — executes steps necessary for migrating the resource to the node. Suggested minimum timeout: 120s.
• meta-data — retrieves resource agent metadata (internal use only). Suggested minimum timeout: 5s.
• validate-all — performs a validation of the resource configuration. Suggested minimum timeout: 5s.

---

🎀 EXAMPLE CRM SHELL 🎀

here's an example config for a VirtualDomain resource using the crm(8) shell — iconic:

primitive p_VirtualDomain ocf:heartbeat:VirtualDomain \
  params \
    config=string \
  meta allow-migrate="true" \
  op monitor depth="0" timeout="30s" interval="10s"

---

🌈 EXAMPLE PCS 🌈

and here's the same vibe but for pcs(8):

pcs resource create p_VirtualDomain ocf:heartbeat:VirtualDomain \
  config=string \
  op monitor OCF_CHECK_LEVEL="0" timeout="30s" interval="10s"

---

⭐ SEE ALSO ⭐

• http://clusterlabs.org/

---

💜 AUTHOR 💜

ClusterLabs contributors (see the resource agent source for information about individual authors) 🫶

---

so that's the whole thing bestie, slay 💅✨ — this page came from resource-agents UNKNOWN, dated 10/01/2026, and yeah, that's the tea 🍓👑