1OCF_HEARTBEAT_VIRTUA(7)       OCF resource agents      OCF_HEARTBEAT_VIRTUA(7)
2
3
4

NAME

6       ocf_heartbeat_VirtualDomain - Manages virtual domains through the
7       libvirt virtualization framework
8

SYNOPSIS

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

DESCRIPTION

14       Resource agent for a virtual domain (a.k.a. domU, virtual machine,
15       virtual environment etc., depending on context) managed by libvirtd.
16
17       This resource agent may be configured for native migration if available
18       in the cluster manager. For Pacemaker, the allow-migrate="true" meta
19       attribute enables native migration.
20

SUPPORTED PARAMETERS

22       config
23           Absolute path to the libvirt configuration file, for this virtual
24           domain.
25
26           (unique, required, string, no default)
27
28       hypervisor
29           Hypervisor URI to connect to. See the libvirt documentation for
30           details on supported URI formats. The default is system dependent.
31           Determine the system's default uri by running 'virsh --quiet uri'.
32
33           (optional, string, no default)
34
35       force_stop
36           Always forcefully shut down ("destroy") the domain on stop. The
37           default behavior is to resort to a forceful shutdown only after a
38           graceful shutdown attempt has failed. You should only set this to
39           true if your virtual domain (or your virtualization backend) does
40           not support graceful shutdown.
41
42           (optional, boolean, default 0)
43
44       migration_transport
45           Transport used to connect to the remote hypervisor while migrating.
46           Please refer to the libvirt documentation for details on transports
47           available. If this parameter is omitted, the resource will use
48           libvirt's default transport to connect to the remote hypervisor.
49
50           (optional, string, no default)
51
52       migration_user
53           The username will be used in the remote libvirt
54           remoteuri/migrateuri. No user will be given (which means root) in
55           the username if omitted
56
57           If remoteuri is set, migration_user will be ignored.
58
59           (optional, string, no default)
60
61       migration_downtime
62           Define max downtime during live migration in milliseconds
63
64           (optional, integer, default 0)
65
66       migration_speed
67           Define live migration speed per resource in MiB/s
68
69           (optional, integer, default 0)
70
71       migration_network_suffix
72           Use a dedicated migration network. The migration URI is composed by
73           adding this parameters value to the end of the node name. If the
74           node name happens to be an FQDN (as opposed to an unqualified host
75           name), insert the suffix immediately prior to the first period (.)
76           in the FQDN. At the moment Qemu/KVM and Xen migration via a
77           dedicated network is supported.
78
79           Note: Be sure this composed host name is locally resolvable and the
80           associated IP is reachable through the favored network. This suffix
81           will be added to the remoteuri and migrateuri parameters.
82
83           See also the migrate_options parameter below.
84
85           (optional, string, no default)
86
87       migrateuri
88           You can also specify here if the calculated migrate URI is
89           unsuitable for your environment.
90
91           If migrateuri is set then migration_network_suffix, migrateport and
92
93           --migrateuri in migrate_options are effectively ignored. Use "%n"
94           as the placeholder for the target node name.
95
96           Please refer to the libvirt documentation for details on guest
97           migration.
98
99           (optional, string, no default)
100
101       migrate_options
102           Extra virsh options for the guest live migration. You can also
103           specify here --migrateuri if the calculated migrate URI is
104           unsuitable for your environment. If --migrateuri is set then
105           migration_network_suffix and migrateport are effectively ignored.
106           Use "%n" as the placeholder for the target node name.
107
108           Please refer to the libvirt documentation for details on guest
109           migration.
110
111           (optional, string, no default)
112
113       monitor_scripts
114           To additionally monitor services within the virtual domain, add
115           this parameter with a list of scripts to monitor.
116
117           Note: when monitor scripts are used, the start and migrate_from
118           operations will complete only when all monitor scripts have
119           completed successfully. Be sure to set the timeout of these
120           operations to accommodate this delay.
121
122           (optional, string, no default)
123
124       autoset_utilization_cpu
125           If set true, the agent will detect the number of domainU's vCPUs
126           from virsh, and put it into the CPU utilization of the resource
127           when the monitor is executed.
128
129           (optional, boolean, default true)
130
131       autoset_utilization_host_memory
132           If set true, the agent will detect the number of *Max memory* from
133           virsh, and put it into the host_memory utilization of the resource
134           when the monitor is executed.
135
136           (optional, boolean, default true)
137
138       autoset_utilization_hv_memory
139           If set true, the agent will detect the number of *Max memory* from
140           virsh, and put it into the hv_memory utilization of the resource
141           when the monitor is executed.
142
143           (optional, boolean, default true)
144
145       unset_utilization_cpu
146           If set true then the agent will remove the cpu utilization resource
147           when the monitor is executed.
148
149           (optional, boolean, default false)
150
151       unset_utilization_host_memory
152           If set true then the agent will remove the host_memory utilization
153           resource when the monitor is executed.
154
155           (optional, boolean, default false)
156
157       unset_utilization_hv_memory
158           If set true then the agent will remove the hv_memory utilization
159           resource when the monitor is executed.
160
161           (optional, boolean, default false)
162
163       migrateport
164           This port will be used in the qemu migrateuri. If unset, the port
165           will be a random highport.
166
167           (optional, integer, no default)
168
169       remoteuri
170           Use this URI as virsh connection URI to commuicate with a remote
171           hypervisor.
172
173           If remoteuri is set then migration_user and
174           migration_network_suffix are effectively ignored. Use "%n" as the
175           placeholder for the target node name.
176
177           Please refer to the libvirt documentation for details on guest
178           migration.
179
180           (optional, string, no default)
181
182       save_config_on_stop
183           Changes to a running VM's config are normally lost on stop. This
184           parameter instructs the RA to save the configuration back to the
185           xml file provided in the "config" parameter.
186
187           (optional, boolean, no default)
188
189       sync_config_on_stop
190           Setting this automatically enables save_config_on_stop. When
191           enabled this parameter instructs the RA to call csync2 -x to
192           synchronize the file to all nodes. csync2 must be properly set up
193           for this to work.
194
195           (optional, boolean, no default)
196
197       snapshot
198           Path to the snapshot directory where the virtual machine image will
199           be stored. When this parameter is set, the virtual machine's RAM
200           state will be saved to a file in the snapshot directory when
201           stopped. If on start a state file is present for the domain, the
202           domain will be restored to the same state it was in right before it
203           stopped last. This option is incompatible with the 'force_stop'
204           option.
205
206           (optional, string, no default)
207
208       backingfile
209           When the VM is used in Copy-On-Write mode, this is the backing file
210           to use (with its full path). The VMs image will be created based on
211           this backing file. This backing file will never be changed during
212           the life of the VM.
213
214           (optional, string, no default)
215
216       stateless
217           If set to true and backingfile is defined, the start of the VM will
218           systematically create a new qcow2 based on the backing file,
219           therefore the VM will always be stateless. If set to false, the
220           start of the VM will use the COW (<vmname>.qcow2) file if it
221           exists, otherwise the first start will create a new qcow2 based on
222           the backing file given as backingfile.
223
224           (optional, boolean, default false)
225
226       copyindirs
227           List of directories for the virt-copy-in before booting the VM.
228           Used only in stateless mode.
229
230           (optional, string, no default)
231
232       shutdown_mode
233           virsh shutdown method to use. Please verify that it is supported by
234           your virsh toolsed with 'virsh help shutdown' When this parameter
235           is set --mode shutdown_mode is passed as an additional argument to
236           the 'virsh shutdown' command. One can use this option in case
237           default acpi method does not work. Verify that this mode is
238           supported by your VM. By default --mode is not passed.
239
240           (optional, string, no default)
241
242       start_resources
243           Start the virtual storage pools and networks used by the virtual
244           machine before starting it or before live migrating it.
245
246           (optional, boolean, default false)
247

SUPPORTED ACTIONS

249       This resource agent supports the following actions (operations):
250
251       start
252           Starts the resource. Suggested minimum timeout: 90s.
253
254       stop
255           Stops the resource. Suggested minimum timeout: 90s.
256
257       status
258           Performs a status check. Suggested minimum timeout: 30s. Suggested
259           interval: 10s.
260
261       monitor
262           Performs a detailed status check. Suggested minimum timeout: 30s.
263           Suggested interval: 10s.
264
265       migrate_from
266           Executes steps necessary for migrating the resource away from the
267           node. Suggested minimum timeout: 60s.
268
269       migrate_to
270           Executes steps necessary for migrating the resource to the node.
271           Suggested minimum timeout: 120s.
272
273       meta-data
274           Retrieves resource agent metadata (internal use only). Suggested
275           minimum timeout: 5s.
276
277       validate-all
278           Performs a validation of the resource configuration. Suggested
279           minimum timeout: 5s.
280

EXAMPLE CRM SHELL

282       The following is an example configuration for a VirtualDomain resource
283       using the crm(8) shell:
284
285           primitive p_VirtualDomain ocf:heartbeat:VirtualDomain \
286             params \
287               config=string \
288             meta allow-migrate="true" \
289             op monitor depth="0" timeout="30s" interval="10s"
290

EXAMPLE PCS

292       The following is an example configuration for a VirtualDomain resource
293       using pcs(8)
294
295           pcs resource create p_VirtualDomain ocf:heartbeat:VirtualDomain \
296             config=string \
297             op monitor OCF_CHECK_LEVEL="0" timeout="30s" interval="10s"
298

SEE ALSO

300       http://clusterlabs.org/
301

AUTHOR

303       ClusterLabs contributors (see the resource agent source for information
304       about individual authors)
305
306
307
308resource-agents UNKNOWN           10/11/2023           OCF_HEARTBEAT_VIRTUA(7)
Impressum