1Ravada::Domain(3) User Contributed Perl Documentation Ravada::Domain(3)
2
6 Ravada::Domain - Domains ( Virtual Machines ) library for Ravada
7 allowed_booking
9 Returns true if an user is allowed in a booking for this virtual
10 machine or its base. Returns false otherwise.
11 $machine->allowed_booking($user);
13 pre_prepare_base
15 Run this before preparing the base. By default does nothing and may be
16 implemented in the object.
17 This is executed automatically so it shouldn't been called.
19 prepare_base
21 Prepares the virtual machine as a base:
22 • shuts it down
24 • creates read only volumes based on this base
26 • locks it so it won't get started
28 • stores the virtual machine template for the clones
30 post_prepare_base
32 Placeholder for optional method implemented in subclasses. This will
33 run after preparing the base files.
34 spinoff
36 Makes volumes indpendent from base
37 sub _check_disk_modified {
39 my $self = shift;
40 if ( !$self->is_base() ) {
42 return;
43 }
44 my $last_stat_base = 0;
46 for my $file_base ( $self->list_files_base ) {
47 my @stat_base = stat($file_base);
48 $last_stat_base = $stat_base[9] if$stat_base[9] > $last_stat_base;
49 # warn $last_stat_base;
50 }
51 my $files_updated = 0;
53 for my $file ( $self->disk_device ) {
54 my @stat = stat($file) or next;
55 $files_updated++ if $stat[9] > $last_stat_base;
56 # warn "\ncheck\t$file ".$stat[9]."\n vs \tfile_base $last_stat_base $files_updated\n";
57 }
58 die "Base already created and no disk images updated"
59 if !$files_updated;
60 }
61 id Returns the id of the domain my $id = $domain->id();
63 open
64 Open a domain
65 Argument: id Arguments: id => $id , [ readonly => {0|1} ]
67 Returns: Domain object
69 check_status
71 Checks if a virtual machine known status is in sync.
72 • Checks it is already started
74 • Performs shutdown cleaning procedures if down
76 is_known
78 Returns if the domain is known in Ravada.
79 is_known_extra
81 Returns if the domain has extra fields information known in Ravada.
82 start_time
84 Returns the last time (epoch format in seconds) the domain was started.
85 spice_password
87 Returns the password defined for the spice viewers
88 display_file
90 Returns a file with the display information. Defaults to spice.
91 display_file_tls
93 Returns a file with the display information in TLS connections.
94 Defaults to spice.
95 display
97 Returns the display information.
98 info
100 Return information about the domain.
101 pre_remove
103 Code to run before removing the domain. It can be implemented in each
104 domain. It is not expected to run by itself, the remove function calls
105 it before proceeding.
106 $domain->pre_remove(); # This isn't likely to be necessary
108 $domain->remove(); # Automatically calls the domain pre_remove method
109 restore
111 Returns the clone to an initial state.
112 Depending of the type of volumes added to the virtual machines all the
114 information stored there is removed. Only data volumes are kept
115 untouched.
116 • system : cleaned to the initial state
118 • tmp/swap : cleaned to the initial state
120 • data : nothing gets removed
122 is_base Returns true or false if the domain is a prepared base
124 is_locked Shows if the domain has running or pending requests. It could be
125 considered too as the domain is busy doing something like starting,
126 shutdown or prepare base. Returns true if locked.
127 id_owner Returns the id of the user that created this domain
128 id_base Returns the id from the base this domain is based on, if any.
129 vm Returns a string with the name of the VM ( Virtual Machine ) this domain
130 was created on
131 clones Returns a list of clones from this virtual machine my @clones =
132 $domain->clones
133 has_clones Returns the number of clones from this virtual machine my
134 $has_clones = $domain->has_clones
135 list_files_base Returns a list of the filenames of this base-type domain
136 list_files_base_target
137 Returns a list of the filenames and targets of this base-type domain
138 can_screenshot Returns wether this domain can take an screenshot.
140 remove_base Makes the domain a regular, non-base virtual machine and
141 removes the base files.
142 clone
143 Clones a domain
144 arguments
146 user => $user : The user that owns the clone
148 name => $name : Name of the new clone
149 can_hybernate
151 Returns wether a domain supports hybernation
152 can_hibernate
154 Returns wether a domain supports hibernation
155 add_volume_swap
157 Adds a swap volume to the virtual machine
158 Arguments:
160 size => $kb
162 name => $name (optional)
163 expose
165 Expose a TCP port from the domain
166 Arguments:
168 - number of the port
169 - optional name
170 Returns: public ip and port
172 exposed_port
174 Returns all the data from an exposed port.
175 Argument: number or name description of the port permission.
177 my $port_data = $domain->exposed_port(80);
179 my $port_data = $domain->exposed_port('web');
181 open_exposed_ports
183 Performs an iptables open of all the exposed ports of the domain
184 remove_expose
186 Remove exposed port
187 Argument: virtual machine exposed port [ optional ]
189 If no port is passed all the exposed ports are removed.
191 list_ports
193 List of exposed TCP ports
194 post_resume_aux
196 Method after resume
197 open_iptables
199 Open iptables for a remote client
200 user
202 remote_ip
203 is_public
205 Sets or get the domain public
206 $domain->is_public(1);
208 if ($domain->is_public()) {
210 ...
211 }
212 is_volatile
214 Returns if the domain is volatile, so it will be removed on shutdown
215 is_persistent
217 Returns true if the virtual machine is persistent. So it is not removed
218 after shut down.
219 run_timeout
221 Sets or get the domain run timeout. When it expires it is shut down.
222 $domain->run_timeout(60 * 60); # 60 minutes
224 clean_swap_volumes
226 Check if the domain has swap volumes defined, and clean them
227 $domain->clean_swap_volumes();
229 get_controller
231 Calls the method to get the specified controller info
232 Attributes:
234 name -> name of the controller type
235 get_controllers
237 Returns a hashref of the hardware controllers for this virtual machine
238 drivers
240 List the drivers available for a domain. It may filter for a given
241 type.
242 my @drivers = $domain->drivers();
244 my @video_drivers = $domain->drivers('video');
245 set_driver_id
247 Sets the driver of a domain given it id. The id must be one from the
248 table domain_drivers_options
249 $domain->set_driver_id($id_driver);
251 last_vm
253 Returns the last virtual machine manager on which this domain was
254 launched.
255 my $vm = $domain->last_vm();
257 list_requests
259 Returns a list of pending requests from the domain. It won't show those
260 requests scheduled for later.
261 list_all_requests
263 Returns a list of pending requests from the domain including those
264 scheduled for later
265 get_driver
267 Returns the driver from a domain
268 Argument: name of the device [ optional ] Returns all the drivers if
270 not passwed
271 my $driver = $domain->get_driver('video');
273 get_driver_id
275 Gets the value of a driver
276 Argument: name
278 my $driver = $domain->get_driver('video');
280 set_option
282 Sets a domain option:
283 • description
285 • run_timeout
287 $domain->set_option(description => 'Virtual Machine for ...');
289 type
291 Returns the virtual machine type as a string.
292 rsync
294 Synchronizes the volume data to a remote node.
295 Arguments: ( node => $node, request => $request, files => \@files )
297 • node => Ravada::VM
299 • request => Ravada::Request ( optional )
301 • files => listref of files ( optional )
303 When files is not specified it syncs the volumes and base volumes if
305 any
306 set_base_vm
308 Prepares or removes a base in a virtual manager.
309 $domain->set_base_vm(
311 id_vm => $id_vm # you can pass the id_vm
312 ,vm => $vm # or the vm
313 ,user => $user
314 ,value => $value # if it is 0, it removes the base
315 ,request => $req
316 );
317 migrate_base
319 Migrates a base to a virtual manager node.
320 Alias for set_base_vm.
322 remove_base_vm
324 Removes a base in a Virtual Machine Manager node.
325 $domain->remove_base_vm($vm, $user);
327 file_screenshot
329 Returns the file name where the domain screenshot has been stored
330 list_vms
332 Returns a list for virtual machine managers where this domain is base
333 base_in_vm
335 Returns if this domain has a base prepared in this virtual manager
336 if ($domain->base_in_vm($id_vm)) { ...
338 is_local
340 Returns wether this domain is in the local host
341 pools
343 Enables or disables pools of clones for this virtual machine
344 pool_clones
346 Number of clones of this virtual machine that belong to the pool
347 pool_start
349 Number of clones of this virtual machine that are pre-started
350 is_pool
352 Return if the virtual machine belongs to a pool of clones
353 internal_id
355 Returns the internal id of this domain as found in its Virtual Manager
356 connection
357 volatile_clones
359 Enables or disables a domain volatile clones feature. Volatile clones
360 are removed when shut down
361 status
363 Sets or gets the status of a virtual machine
364 $machine->status('active');
366 Valid values are:
368 • active
370 • down
372 • hibernated
374 client_status
376 Returns the status of the viewer connection. The virtual machine must
377 be active, and the remote ip must be known.
378 Possible results:
380 • connecting : set at the start of the virtual machine
382 • IP : known remote ip from the current connection
384 • disconnected : the remote client has been closed
386 This method is used from higher level commands, for example, you can
388 shut down or hibernate all the disconnected virtual machines like this:
389 # rvd_back --hibernate --disconnected
391 # rvd_back --shutdown --disconnected
392 You could also set this command on a cron entry to run nightly, hourly
394 or whenever you find suitable.
395 needs_restart
397 Returns true or false if the virtual machine needs to be restarted so
398 some hardware change can be applied.
399 Access restrictions
401 These methods implement access restrictions to clone a domain
402 allow_ldap_access
404 If specified, only the LDAP users with that attribute value can clone
405 these virtual machines.
406 $base->allow_ldap_attribute( attribute => 'value' );
408 Example:
410 $base->allow_ldap_attribute( tipology => 'student' );
412 default_access
414 Sets the default access value
415 grant_access
417 Grant access to a virtual machine
418 Arguments is a named list
420 • attribute
422 • value
424 • type
426 • allowed ( true / false ) defaults to true
428 • last : if this grant matches it stops looking
430 list_access_groups
432 Returns the list of groups who can access this virtual machine
433 access_allowed
435 Returns if a client is granted access to a virtual machine
436 Arguments: expects a named vars list of client attributes retrieved
438 from the web connection.
439 list_access
441 Returns a list of access grants
442 Argument: optionally pass the type of grant.
444 delete_access
446 Deletes a list of access grants from the database
447 delete_ldap_access
449 Deletes a granted ldap access setting
450 Argument: id of the access from the table access_ldap_attribute
452 list_ldap_access
454 List granted ldap access settings
455 deny_ldap_access
457 If specified, only the LDAP users with that attribute value can clone
458 these virtual machines.
459 $base->deny_ldap_attribute( attribute => 'value' );
461 Example:
463 $base->deny_ldap_attribute( tipology => 'student' );
465 move_ldap_access
467 Moves an access access grant up or down
468 Arguments:
470 • id_ldap_access
472 • position: +1/-1
474 move_access
476 Moves an access access grant up or down
477 Arguments:
479 • id_access
481 • position: +1/-1
483 set_ldap_access
485 Changes access grant allowed and last states
486 Arguments:
488 • id_access
490 • allowed
492 • last
494 set_access
496 Changes access grant allowed and last states
497 • id_access
499 • allowed
501 • last
503 rebase
505 Rebases the virtual machine to another one
506 If it is a base it rebases all the clones.
508 list_instances
510 Returns a list of instances of the virtual machine in all the physical
511 nodes
512 has_non_shared_storage
514 Return wether this virtual machine has non shared storage volumes
515 compact
517 Compact volumes of a virtual machine. It creates a backup copy unless
518 specified in the request.
519 $domain->compact();
521 $comain->compact($request);
523 Usually called through Ravada::Request->compact();
525 purge
527 Purges old backup volumes of a virtual machine
528 refresh_ports
530 Refresh the status of the exposed ports
531
533 Hey! The above document had some coding errors, which are explained
534 below:
535 Around line 866:
537 You forgot a '=back' before '=head2'
538 Around line 2456:
540 You forgot a '=back' before '=head2'
541 Around line 6193:
543 You forgot a '=back' before '=head2'
544perl v5.36.0 2023-03-19 Ravada::Domain(3)