diff options
Diffstat (limited to '')
| -rw-r--r-- | agents/virt/man/.gitignore | 2 | ||||
| -rw-r--r-- | agents/virt/man/Makefile.am | 28 | ||||
| -rw-r--r-- | agents/virt/man/fence_virt.conf.5 | 335 | ||||
| -rw-r--r-- | agents/virt/man/fence_virtd.8 | 53 | ||||
| -rw-r--r-- | agents/virt/man/fence_xvm.8 | 1 |
5 files changed, 419 insertions, 0 deletions
diff --git a/agents/virt/man/.gitignore b/agents/virt/man/.gitignore new file mode 100644 index 0000000..4a80f6e --- /dev/null +++ b/agents/virt/man/.gitignore @@ -0,0 +1,2 @@ +fence_virt.8 +fence_virt.wiki diff --git a/agents/virt/man/Makefile.am b/agents/virt/man/Makefile.am new file mode 100644 index 0000000..5b8ae36 --- /dev/null +++ b/agents/virt/man/Makefile.am @@ -0,0 +1,28 @@ +############################################################################### +############################################################################### +## +## Copyright (C) 2009-2021 Red Hat, Inc. +## +## This copyrighted material is made available to anyone wishing to use, +## modify, copy, or redistribute it subject to the terms and conditions +## of the GNU General Public License v.2. +## +############################################################################### +############################################################################### + +MAINTAINERCLEANFILES = Makefile.in + +dist_man8_MANS = fence_xvm.8 fence_virtd.8 +dist_man5_MANS = fence_virt.conf.5 +man8_MANS = fence_virt.8 + +fence_virt.8: $(top_builddir)/agents/virt/client/fence_virt $(top_srcdir)/lib/fence2man.xsl + set -e && \ + ../client/$(@:%.8=%) -o metadata > .$(@F).tmp && \ + xmllint --noout --relaxng $(top_srcdir)/lib/metadata.rng .$(@F).tmp && \ + xsltproc $(top_srcdir)/lib/fence2man.xsl .$(@F).tmp > $@ + xsltproc $(top_srcdir)/lib/fence2wiki.xsl .$(@F).tmp | grep -v '<?xml' > $(@F:%.8=%.wiki) + + +clean-local: + rm -f fence_virt.8* .*.8.tmp *.wiki diff --git a/agents/virt/man/fence_virt.conf.5 b/agents/virt/man/fence_virt.conf.5 new file mode 100644 index 0000000..f920a66 --- /dev/null +++ b/agents/virt/man/fence_virt.conf.5 @@ -0,0 +1,335 @@ +.TH fence_virt.conf 5 + +.SH NAME +fence_virt.conf - configuration file for fence_virtd + +.SH DESCRIPTION + +The fence_virt.conf file contains configuration information for fence_virtd, +a fencing request routing daemon for clusters of virtual machines. + +The file is tree-structured. There are parent/child relationships and sibling +relationships between the nodes. + + foo { + bar { + baz = "1"; + } + } + +There are three primary sections of fence_virt.conf. + +.SH SECTIONS +.SS fence_virtd + +This section contains global information about how fence_virtd is to operate. +The most important pieces of information are as follows: + +.TP +.B listener +. +the listener plugin for receiving fencing requests from clients + +.TP +.B backend +. +the plugin to be used to carry out fencing requests + +.TP +.B foreground +. +do not fork into the background. + +.TP +.B 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. + +.TP +.B module_path +. +the module path to search for plugins + +.SS listeners + +This section contains listener-specific configuration information; see the +section about listeners below. + +.SS backends + +This section contains listener-specific configuration information; see the +section about listeners below. + +.SS groups + +This section contains static maps of which virtual machines +may fence which other virtual machines; see the section +about groups below. + + +.SH LISTENERS + +There are various listeners available for fence_virtd, each one handles +decoding and authentication of a given fencing request. The following +configuration blocks belong in the \fBlisteners\fP section of fence_virt.conf + +.SS multicast +.TP +.B key_file +. +the shared key file to use (default: /etc/cluster/fence_xvm.key). + +.TP +.B 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) + +.TP +.B auth +. +the hashing algorithm to use for the simplistic challenge-response authentication +(default: sha256, but could be sha1, sha512, or none) + +.TP +.B family +. +the IP family to use (default: ipv4, but may be ipv6) + +.TP +.B address +. +the multicast address to listen on (default: 225.0.0.12) + +.TP +.B port +. +the multicast port to listen on (default: 1229) + +.TP +.B 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. + +.SS 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 +.B unix +, mode +.B bind +serial ports and channels are supported and each VM should have a +separate unique socket. Example libvirt XML: + +.in 8 + <\fBserial\fP type='unix'> + <source mode='bind' path='/sandbox/guests/fence_socket_molly'/> + <target port='1'/> + </serial> + <\fBchannel\fP type='unix'> + <source mode='bind' path='/sandbox/guests/fence_molly_vmchannel'/> + <target type='guestfwd' address='10.0.2.179' port='1229'/> + </channel> +.in 0 + +.TP +.B uri +. +the URI to use when connecting to libvirt by the serial plugin (optional). + +.TP +.B 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. + +.TP +.B mode +. +This selects the type of sockets to register. Valid values are "serial" +(default) and "vmchannel". + +.SS tcp +The tcp listener operates similarly to the multicast listener but uses TCP sockets for communication instead of using multicast packets. + +.TP +.B key_file +. +the shared key file to use (default: /etc/cluster/fence_xvm.key). + +.TP +.B hash +. +the hashing algorithm to use for packet signing (default: sha256, but could +be sha1, sha512, or none) + +.TP +.B auth +. +the hashing algorithm to use for the simplistic challenge-response authentication +(default: sha256, but could be sha1, sha512, or none) + +.TP +.B family +. +the IP family to use (default: ipv4, but may be ipv6) + +.TP +.B address +. +the IP address to listen on (default: 127.0.0.1 for IPv4, ::1 for IPv6) + +.TP +.B port +. +the TCP port to listen on (default: 1229) + +.SS vsock +The vsock listener operates similarly to the multicast listener but uses virtual machine sockets (AF_VSOCK) for communication instead of using multicast packets. + +.TP +.B key_file +. +the shared key file to use (default: /etc/cluster/fence_xvm.key). + +.TP +.B hash +. +the hashing algorithm to use for packet signing (default: sha256, but could +be sha1, sha512, or none) + +.TP +.B auth +. +the hashing algorithm to use for the simplistic challenge-response authentication +(default: sha256, but could be sha1, sha512, or none) + +.TP +.B port +. +the vsock port to listen on (default: 1229) + +.SH BACKENDS + +There are various backends available for fence_virtd, each one handles +routing a fencing request to a hypervisor or management tool. The following +configuration blocks belong in the \fBbackends\fP section of fence_virt.conf + +.SS libvirt + +The libvirt plugin is the simplest plugin. It is 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. + +.TP +.B 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 + +.SS cpg + +The cpg plugin uses corosync CPG and libvirt to track virtual +machines and route fencing requests to the appropriate computer. + +.TP +.B uri +. +the URI to use when connecting to libvirt by the cpg plugin. + +.TP +.B 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. + +.SH 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. + +.SS group + +This defines a group. + +.TP +.B name +. +Optionally define the name of the group. Useful only for configuration +readability and debugging of configuration parsing. + +.TP +.B 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. + +.TP +.B 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. + + +.SH EXAMPLE + + 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"; + } + } + +.SH SEE ALSO +fence_virtd(8), fence_virt(8), fence_xvm(8), fence(8) diff --git a/agents/virt/man/fence_virtd.8 b/agents/virt/man/fence_virtd.8 new file mode 100644 index 0000000..56f6938 --- /dev/null +++ b/agents/virt/man/fence_virtd.8 @@ -0,0 +1,53 @@ +.TH FENCE_AGENT 8 2010-01-05 "fence_virtd (Fence Agent)" +.SH NAME +fence_virtd - Fencing host for virtual machines + +.SH DESCRIPTION +.P +fence_virtd is a host daemon designed to route fencing requests for +virtual machines. + +Fence_virt and fence_xvm talk to fence_virtd, which supports multiple backend plugins, including: + - libvirt for single-node operation + - Corosync CPG and libvirt when using Linux-cluster release 3.0.0 or later + - libvirt-qpid for multi-node, non-cluster operation + +For compatibility, fence_xvm from linux-cluster release 2 may talk to fence_virtd. + +.P +fence_virtd accepts a few options on the command line, but most options +are read from fence_virt.conf. + +.SH PARAMETERS +.TP +.B -d +. +Specify debug level, e.g. "-d99" + +.TP +.B -c +. +Interactively prompt user for configuration information + +.TP +.B -f +. +Specify an alternate configuration file instead of /etc/fence_virt.conf + +.TP +.B -F +. +Do not fork into background after starting (overrides any setting in fence_virt.conf) + +.TP +.B -w +. +Wait for backend to be available (overrides any setting in fence_virt.conf) + +.TP +.B -p +. +Specify the full path to the pid file used to record the active process pid. + +.SH SEE ALSO +fence_virt(8), fence_xvm(8), fence(8), fence_virt.conf(5) diff --git a/agents/virt/man/fence_xvm.8 b/agents/virt/man/fence_xvm.8 new file mode 100644 index 0000000..5d0cfdd --- /dev/null +++ b/agents/virt/man/fence_xvm.8 @@ -0,0 +1 @@ +.so man8/fence_virt.8 |