fence_virt.conf(5)

💖 fence_virt.conf(5) — the group chat guide to your fencing config 💖

okay so bestie, welcome to the File Formats Manual page for fence_virt.conf(5). this is THE file. the one that tells fence_virtd how to live its life. let's get into it 🫶

---

✨ NAME ✨

fence_virt.conf — the configuration file for fence_virtd. that's it, that's the name, periodt 💅

---

🌸 DESCRIPTION 🌸

the fence_virt.conf file holds all the configuration tea for fence_virtd, which is a fencing request routing daemon for clusters of virtual machines. yes, a daemon. very main character energy 🔥

the file is tree-structured. there are parent/child relationships and sibling relationships between the nodes. think of it like a family group chat where everyone's related somehow:

foo {
  bar {
    baz = "1";
  }
}

there are three primary sections of fence_virt.conf.

(not me counting four sections listed right below this line 💀 we're keeping it exactly as written, bestie, no notes)

---

🎀 SECTIONS 🎀

🧚 fence_virtd

this section is the global info about how fence_virtd is supposed to operate. the most important pieces of information are, as follows:

• listener — the listener plugin for receiving fencing requests from clients
• backend — the plugin to be used to carry out fencing requests
• foreground — do not fork into the background.
• wait_for_init — wait for the frontend and backends to become available rather than giving up immediately. this replaces wait_for_backend in 0.2.x.
• module_path — the module path to search for plugins

🦋 listeners

this section contains listener-specific configuration information; see the section about listeners below. iykyk ✨

💜 backends

this section contains listener-specific configuration information; see the section about listeners below.

yes bestie, that's genuinely what it says 🙈 we are not fixing it, we are not touching it, we are simply reporting it with love.

🌈 groups

this section contains static maps of which virtual machines may fence which other virtual machines; see the section about groups below.

---

⭐ LISTENERS ⭐

there are various listeners available for fence_virtd, and each one handles decoding and authentication of a given fencing request. the following configuration blocks belong in the listeners section of fence_virt.conf.

📡 multicast

• key_file — the shared key file to use (default: /etc/cluster/fence_xvm.key).
• hash — the weakest hashing algorithm allowed for client requests. clients may send packets with stronger hashes than the one specified, but not weaker ones. (default: sha256, but could be sha1, sha512, or none)
• auth — the hashing algorithm to use for the simplistic challenge-response authentication (default: sha256, but could be sha1, sha512, or none)
• family — the IP family to use (default: ipv4, but may be ipv6)
• address — the multicast address to listen on (default: 225.0.0.12)
• port — the multicast port to listen on (default: 1229)
• interface — interface to listen on. by default, fence_virtd listens on all interfaces. however, this causes problems in some environments where the host computer is used as a gateway. 👀

🔌 serial

the serial listener plugin utilizes libvirt's serial (or VMChannel) mapping to listen for requests. when using the serial listener, it is necessary to add a serial port (preferably pointing to /dev/ttyS1) or a channel (preferably pointing to 10.0.2.179:1229) to the libvirt domain description.

⚠️ note that only type unix, mode bind serial ports and channels are supported, and each VM should have a separate unique socket. no sharing, bestie, that's not the vibe.

example libvirt XML:

<serial type='unix'>
  <source mode='bind' path='/sandbox/guests/fence_socket_molly'/>
  <target port='1'/>
</serial>
<channel type='unix'>
  <source mode='bind' path='/sandbox/guests/fence_molly_vmchannel'/>
  <target type='guestfwd' address='10.0.2.179' port='1229'/>
</channel>

• uri — the URI to use when connecting to libvirt by the serial plugin (optional).
• path — the same directory that is defined for the domain serial port path (from example above: /sandbox/guests). sockets must reside in this directory in order to be considered valid. this can be used to prevent fence_virtd from using the wrong sockets. 🎯
• mode — this selects the type of sockets to register. valid values are "serial" (default) and "vmchannel".

🌐 tcp

the tcp listener operates similarly to the multicast listener but uses TCP sockets for communication instead of using multicast packets.

• key_file — the shared key file to use (default: /etc/cluster/fence_xvm.key).
• hash — the hashing algorithm to use for packet signing (default: sha256, but could be sha1, sha512, or none)
• auth — the hashing algorithm to use for the simplistic challenge-response authentication (default: sha256, but could be sha1, sha512, or none)
• family — the IP family to use (default: ipv4, but may be ipv6)
• address — the IP address to listen on (default: 127.0.0.1 for IPv4, ::1 for IPv6)
• port — the TCP port to listen on (default: 1229)

🧵 vsock

the vsock listener operates similarly to the multicast listener but uses virtual machine sockets (AF_VSOCK) for communication instead of using multicast packets.

• key_file — the shared key file to use (default: /etc/cluster/fence_xvm.key).
• hash — the hashing algorithm to use for packet signing (default: sha256, but could be sha1, sha512, or none)
• auth — the hashing algorithm to use for the simplistic challenge-response authentication (default: sha256, but could be sha1, sha512, or none)
• port — the vsock port to listen on (default: 1229)

---

👑 BACKENDS 👑

there are various backends available for fence_virtd, and each one handles routing a fencing request to a hypervisor or management tool. the following configuration blocks belong in the backends section of fence_virt.conf.

🫶 libvirt

the libvirt plugin is the simplest plugin. it's used in environments where routing fencing requests between multiple hosts is not required — for example, by a user running a cluster of virtual machines on a single desktop computer. cute, cozy, single-machine vibes 🏠

• uri — the URI to use when connecting to libvirt.
  • all libvirt URIs are accepted and passed as-is.
  • see https://libvirt.org/uri.html#remote-uris for examples.
  • NOTE: when VMs are run as non-root user the socket path must be set as part of the URI.
  • example:

qemu:///session?socket=/run/user/<UID>/libvirt/virtqemud-sock

🌟 cpg

the cpg plugin uses corosync CPG and libvirt to track virtual machines and route fencing requests to the appropriate computer.

• uri — the URI to use when connecting to libvirt by the cpg plugin.
• name_mode — the cpg plugin, in order to retain compatibility with fence_xvm, stores virtual machines in a certain way. the default was to use 'name' when using fence_xvm and fence_xvmd, and so this is still the default. however, it is strongly recommended to use 'uuid' instead of 'name' in all cluster environments involving more than one physical host in order to avoid the potential for name collisions. do not skip this one, bestie, i'm begging 🙏

---

💅 GROUPS 💅

fence_virtd supports static maps which allow grouping of VMs. the groups are arbitrary and are checked at fence time. any member of a group may fence any other member. hosts may be assigned to multiple groups if desired. it's giving chosen family 🥰

🍓 group

this defines a group.

• name — optionally define the name of the group. useful only for configuration readability and debugging of configuration parsing.
• uuid — defines UUID as a member of a group. it can be used multiple times to specify both node name and UUID values that can be fenced. when using the serial listener, the vm uuid is required and it is recommended to add also the vm name.
• ip — defines an IP which is allowed to send fencing requests for members of this group (e.g. for multicast). it can be used multiple times to allow more than 1 IP to send fencing requests to the group. it is highly recommended that this be used in conjunction with a key file. when using the vsock listener, ip should contain the CID value assigned by libvirt to the vm. when using the serial listener, ip value is not used and can be omitted.

---

✨ EXAMPLE ✨

here's the whole thing looking cute, fr fr:

 fence_virtd {
  listener = "multicast";
  backend = "cpg";
 }

 # this is the listeners section

 listeners {
  multicast {
   key_file = "/etc/cluster/fence_xvm.key";
  }
 }

 backends {
  libvirt {
   uri = "qemu:///system";
  }
 }

 groups {
  group {
   name = "cluster1";
   ip = "192.168.1.1";
   ip = "192.168.1.2";
   uuid = "44179d3f-6c63-474f-a212-20c8b4b25b16";
   uuid = "1ce02c4b-dfa1-42cb-b5b1-f0b1091ece60";
   uuid = "node1";
   uuid = "node2";
  }
 }

---

🌈 SEE ALSO 🌈

fence_virtd(8), fence_virt(8), fence_xvm(8), fence(8)

go read those too, bestie, they're the rest of the lore 📚

---

and that's the whole page!! 🎉 this little masterpiece lives in the File Formats Manual section and its page name is fence_virt.conf(5). no version or date on the footer, just the name doing its little signature — so consider this our sign-off: you ate this config file, now go fence some VMs. mwah 💋