1Ravada::Domain(3) User Contributed Perl Documentation Ravada::Domain(3)
2
6 Ravada::Domain - Domains ( Virtual Machines ) library for Ravada
7 pre_prepare_base
9 Run this before preparing the base. By default does nothing and may be
10 implemented in the object.
11 This is executed automatically so it shouldn't been called.
13 prepare_base
15 Prepares the virtual machine as a base:
16 · shuts it down
18 · creates read only volumes based on this base
20 · locks it so it won't get started
22 · stores the virtual machine template for the clones
24 post_prepare_base
26 Placeholder for optional method implemented in subclasses. This will
27 run after preparing the base files.
28 spinoff
30 Makes volumes indpendent from base
31 sub _check_disk_modified {
33 my $self = shift;
34 if ( !$self->is_base() ) {
36 return;
37 }
38 my $last_stat_base = 0;
40 for my $file_base ( $self->list_files_base ) {
41 my @stat_base = stat($file_base);
42 $last_stat_base = $stat_base[9] if$stat_base[9] > $last_stat_base;
43 # warn $last_stat_base;
44 }
45 my $files_updated = 0;
47 for my $file ( $self->disk_device ) {
48 my @stat = stat($file) or next;
49 $files_updated++ if $stat[9] > $last_stat_base;
50 # warn "\ncheck\t$file ".$stat[9]."\n vs \tfile_base $last_stat_base $files_updated\n";
51 }
52 die "Base already created and no disk images updated"
53 if !$files_updated;
54 }
55 id Returns the id of the domain my $id = $domain->id();
57 open
58 Open a domain
59 Argument: id Arguments: id => $id , [ readonly => {0|1} ]
61 Returns: Domain object
63 check_status
65 Checks if a virtual machine known status is in sync.
66 · Checks it is already started
68 · Performs shutdown cleaning procedures if down
70 is_known
72 Returns if the domain is known in Ravada.
73 is_known_extra
75 Returns if the domain has extra fields information known in Ravada.
76 start_time
78 Returns the last time (epoch format in seconds) the domain was started.
79 spice_password
81 Returns the password defined for the spice viewers
82 display_file
84 Returns a file with the display information. Defaults to spice.
85 display_file_tls
87 Returns a file with the display information in TLS connections.
88 Defaults to spice.
89 display
91 Returns the display information.
92 info
94 Return information about the domain.
95 pre_remove
97 Code to run before removing the domain. It can be implemented in each
98 domain. It is not expected to run by itself, the remove function calls
99 it before proceeding.
100 $domain->pre_remove(); # This isn't likely to be necessary
102 $domain->remove(); # Automatically calls the domain pre_remove method
103 restore
105 Returns the clone to an initial state.
106 Depending of the type of volumes added to the virtual machines all the
108 information stored there is removed. Only data volumes are kept
109 untouched.
110 · system : cleaned to the initial state
112 · tmp/swap : cleaned to the initial state
114 · data : nothing gets removed
116 is_base Returns true or false if the domain is a prepared base
118 is_locked Shows if the domain has running or pending requests. It could be
119 considered too as the domain is busy doing something like starting,
120 shutdown or prepare base. Returns true if locked.
121 id_owner Returns the id of the user that created this domain
122 id_base Returns the id from the base this domain is based on, if any.
123 vm Returns a string with the name of the VM ( Virtual Machine ) this domain
124 was created on
125 clones Returns a list of clones from this virtual machine my @clones =
126 $domain->clones
127 has_clones Returns the number of clones from this virtual machine my
128 $has_clones = $domain->has_clones
129 list_files_base Returns a list of the filenames of this base-type domain
130 list_files_base_target
131 Returns a list of the filenames and targets of this base-type domain
132 can_screenshot Returns wether this domain can take an screenshot.
134 remove_base Makes the domain a regular, non-base virtual machine and
135 removes the base files.
136 clone
137 Clones a domain
138 arguments
140 user => $user : The user that owns the clone
142 name => $name : Name of the new clone
143 can_hybernate
145 Returns wether a domain supports hybernation
146 can_hibernate
148 Returns wether a domain supports hibernation
149 add_volume_swap
151 Adds a swap volume to the virtual machine
152 Arguments:
154 size => $kb
156 name => $name (optional)
157 expose
159 Expose a TCP port from the domain
160 Arguments:
162 - number of the port
163 - optional name
164 Returns: public ip and port
166 exposed_port
168 Returns all the data from an exposed port.
169 Argument: number or name description of the port permission.
171 my $port_data = $domain->exposed_port(80);
173 my $port_data = $domain->exposed_port('web');
175 open_exposed_ports
177 Performs an iptables open of all the exposed ports of the domain
178 remove_expose
180 Remove exposed port
181 Argument: virtual machine exposed port [ optional ]
183 If no port is passed all the exposed ports are removed.
185 list_ports
187 List of exposed TCP ports
188 post_resume_aux
190 Method after resume
191 open_iptables
193 Open iptables for a remote client
194 user
196 remote_ip
197 is_public
199 Sets or get the domain public
200 $domain->is_public(1);
202 if ($domain->is_public()) {
204 ...
205 }
206 is_volatile
208 Returns if the domain is volatile, so it will be removed on shutdown
209 is_persistent
211 Returns true if the virtual machine is persistent. So it is not removed
212 after shut down.
213 run_timeout
215 Sets or get the domain run timeout. When it expires it is shut down.
216 $domain->run_timeout(60 * 60); # 60 minutes
218 clean_swap_volumes
220 Check if the domain has swap volumes defined, and clean them
221 $domain->clean_swap_volumes();
223 get_controller
225 Calls the method to get the specified controller info
226 Attributes:
228 name -> name of the controller type
229 get_controllers
231 Returns a hashref of the hardware controllers for this virtual machine
232 drivers
234 List the drivers available for a domain. It may filter for a given
235 type.
236 my @drivers = $domain->drivers();
238 my @video_drivers = $domain->drivers('video');
239 set_driver_id
241 Sets the driver of a domain given it id. The id must be one from the
242 table domain_drivers_options
243 $domain->set_driver_id($id_driver);
245 last_vm
247 Returns the last virtual machine manager on which this domain was
248 launched.
249 my $vm = $domain->last_vm();
251 list_requests
253 Returns a list of pending requests from the domain. It won't show those
254 requests scheduled for later.
255 list_all_requests
257 Returns a list of pending requests from the domain including those
258 scheduled for later
259 get_driver
261 Returns the driver from a domain
262 Argument: name of the device [ optional ] Returns all the drivers if
264 not passwed
265 my $driver = $domain->get_driver('video');
267 get_driver_id
269 Gets the value of a driver
270 Argument: name
272 my $driver = $domain->get_driver('video');
274 set_option
276 Sets a domain option:
277 · description
279 · run_timeout
281 $domain->set_option(description => 'Virtual Machine for ...');
283 type
285 Returns the virtual machine type as a string.
286 rsync
288 Synchronizes the volume data to a remote node.
289 Arguments: ( node => $node, request => $request, files => \@files )
291 · node => Ravada::VM
293 · request => Ravada::Request ( optional )
295 · files => listref of files ( optional )
297 When files is not specified it syncs the volumes and base volumes if
299 any
300 set_base_vm
302 Prepares or removes a base in a virtual manager.
303 $domain->set_base_vm(
305 id_vm => $id_vm # you can pass the id_vm
306 ,vm => $vm # or the vm
307 ,user => $user
308 ,value => $value # if it is 0, it removes the base
309 ,request => $req
310 );
311 migrate_base
313 Migrates a base to a virtual manager node.
314 Alias for set_base_vm.
316 remove_base_vm
318 Removes a base in a Virtual Machine Manager node.
319 $domain->remove_base_vm($vm, $user);
321 file_screenshot
323 Returns the file name where the domain screenshot has been stored
324 list_vms
326 Returns a list for virtual machine managers where this domain is base
327 base_in_vm
329 Returns if this domain has a base prepared in this virtual manager
330 if ($domain->base_in_vm($id_vm)) { ...
332 is_local
334 Returns wether this domain is in the local host
335 pools
337 Enables or disables pools of clones for this virtual machine
338 pool_clones
340 Number of clones of this virtual machine that belong to the pool
341 pool_start
343 Number of clones of this virtual machine that are pre-started
344 is_pool
346 Return if the virtual machine belongs to a pool of clones
347 internal_id
349 Returns the internal id of this domain as found in its Virtual Manager
350 connection
351 volatile_clones
353 Enables or disables a domain volatile clones feature. Volatile clones
354 are removed when shut down
355 status
357 Sets or gets the status of a virtual machine
358 $machine->status('active');
360 Valid values are:
362 · active
364 · down
366 · hibernated
368 client_status
370 Returns the status of the viewer connection. The virtual machine must
371 be active, and the remote ip must be known.
372 Possible results:
374 · connecting : set at the start of the virtual machine
376 · IP : known remote ip from the current connection
378 · disconnected : the remote client has been closed
380 This method is used from higher level commands, for example, you can
382 shut down or hibernate all the disconnected virtual machines like this:
383 # rvd_back --hibernate --disconnected
385 # rvd_back --shutdown --disconnected
386 You could also set this command on a cron entry to run nightly, hourly
388 or whenever you find suitable.
389 needs_restart
391 Returns true or false if the virtual machine needs to be restarted so
392 some hardware change can be applied.
393 Access restrictions
395 These methods implement access restrictions to clone a domain
396 allow_ldap_access
398 If specified, only the LDAP users with that attribute value can clone
399 these virtual machines.
400 $base->allow_ldap_attribute( attribute => 'value' );
402 Example:
404 $base->allow_ldap_attribute( tipology => 'student' );
406 default_access
408 Sets the default access value
409 grant_access
411 Grant access to a virtual machine
412 Arguments is a named list
414 · attribute
416 · value
418 · type
420 · allowed ( true / false ) defaults to true
422 · last : if this grant matches it stops looking
424 access_allowed
426 Returns if a client is granted access to a virtual machine
427 Arguments: expects a named vars list of client attributes retrieved
429 from the web connection.
430 list_access
432 Returns a list of access grants
433 Argument: optionally pass the type of grant.
435 delete_access
437 Deletes a list of access grants from the database
438 delete_ldap_access
440 Deletes a granted ldap access setting
441 Argument: id of the access from the table access_ldap_attribute
443 list_ldap_access
445 List granted ldap access settings
446 deny_ldap_access
448 If specified, only the LDAP users with that attribute value can clone
449 these virtual machines.
450 $base->deny_ldap_attribute( attribute => 'value' );
452 Example:
454 $base->deny_ldap_attribute( tipology => 'student' );
456 move_ldap_access
458 Moves an access access grant up or down
459 Arguments:
461 · id_ldap_access
463 · position: +1/-1
465 move_access
467 Moves an access access grant up or down
468 Arguments:
470 · id_access
472 · position: +1/-1
474 set_ldap_access
476 Changes access grant allowed and last states
477 Arguments:
479 · id_access
481 · allowed
483 · last
485 set_access
487 Changes access grant allowed and last states
488 · id_access
490 · allowed
492 · last
494 rebase
496 Rebases the virtual machine to another one
497 If it is a base it rebases all the clones.
499 list_instances
501 Returns a list of instances of the virtual machine in all the physical
502 nodes
503 has_non_shared_storage
505 Return wether this virtual machine has non shared storage volumes
506
508 Hey! The above document had some coding errors, which are explained
509 below:
510 Around line 812:
512 You forgot a '=back' before '=head2'
513 Around line 1963:
515 You forgot a '=back' before '=head2'
516 Around line 4785:
518 You forgot a '=back' before '=head2'
519perl v5.32.0 2020-12-26 Ravada::Domain(3)