1Ravada::Domain(3)     User Contributed Perl Documentation    Ravada::Domain(3)
2
3
4

NAME

6       Ravada::Domain - Domains ( Virtual Machines ) library for Ravada
7
8   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
12          $machine->allowed_booking($user);
13
14   pre_prepare_base
15       Run this before preparing the base. By default does nothing and may be
16       implemented in the object.
17
18       This is executed automatically so it shouldn't been called.
19
20   prepare_base
21       Prepares the virtual machine as a base:
22
23       •   shuts it down
24
25       •   creates read only volumes based on this base
26
27       •   locks it so it won't get started
28
29       •   stores the virtual machine template for the clones
30
31   post_prepare_base
32       Placeholder for optional method implemented in subclasses. This will
33       run after preparing the base files.
34
35   spinoff
36       Makes volumes indpendent from base
37
38       sub _check_disk_modified {
39           my $self = shift;
40
41           if ( !$self->is_base() ) {
42               return;
43           }
44
45           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
52           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
62   id Returns the id of  the domain my $id = $domain->id();
63   open
64       Open a domain
65
66       Argument: id Arguments: id => $id , [ readonly => {0|1} ]
67
68       Returns: Domain object
69
70   check_status
71       Checks if a virtual machine known status is in sync.
72
73       •   Checks it is already started
74
75       •   Performs shutdown cleaning procedures if down
76
77   is_known
78       Returns if the domain is known in Ravada.
79
80   is_known_extra
81       Returns if the domain has extra fields information known in Ravada.
82
83   start_time
84       Returns the last time (epoch format in seconds) the domain was started.
85
86   spice_password
87       Returns the password defined for the spice viewers
88
89   display_file
90       Returns a file with the display information. Defaults to spice.
91
92   display_file_tls
93       Returns a file with the display information in TLS connections.
94       Defaults to spice.
95
96   display
97       Returns the display information.
98
99   info
100       Return information about the domain.
101
102   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
107           $domain->pre_remove();  # This isn't likely to be necessary
108           $domain->remove();      # Automatically calls the domain pre_remove method
109
110   restore
111       Returns the clone to an initial state.
112
113       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
117       •   system : cleaned to the initial state
118
119       •   tmp/swap : cleaned to the initial state
120
121       •   data : nothing gets removed
122
123   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
139   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
145       arguments
146
147       user => $user : The user that owns the clone
148       name => $name : Name of the new clone
149
150   can_hybernate
151       Returns wether a domain supports hybernation
152
153   can_hibernate
154       Returns wether a domain supports hibernation
155
156   add_volume_swap
157       Adds a swap volume to the virtual machine
158
159       Arguments:
160
161           size => $kb
162           name => $name (optional)
163
164   expose
165       Expose a TCP port from the domain
166
167       Arguments:
168        - number of the port
169        - optional name
170
171       Returns: public ip and port
172
173   exposed_port
174       Returns all the data from an exposed port.
175
176       Argument: number or name description of the port permission.
177
178           my $port_data = $domain->exposed_port(80);
179
180           my $port_data = $domain->exposed_port('web');
181
182   open_exposed_ports
183       Performs an iptables open of all the exposed ports of the domain
184
185   remove_expose
186       Remove exposed port
187
188       Argument: virtual machine exposed port [ optional ]
189
190       If no port is passed all the exposed ports are removed.
191
192   list_ports
193       List of exposed TCP ports
194
195   post_resume_aux
196       Method after resume
197
198   open_iptables
199       Open iptables for a remote client
200
201       user
202       remote_ip
203
204   is_public
205       Sets or get the domain public
206
207           $domain->is_public(1);
208
209           if ($domain->is_public()) {
210               ...
211           }
212
213   is_volatile
214       Returns if the domain is volatile, so it will be removed on shutdown
215
216   is_persistent
217       Returns true if the virtual machine is persistent. So it is not removed
218       after shut down.
219
220   run_timeout
221       Sets or get the domain run timeout. When it expires it is shut down.
222
223           $domain->run_timeout(60 * 60); # 60 minutes
224
225   clean_swap_volumes
226       Check if the domain has swap volumes defined, and clean them
227
228           $domain->clean_swap_volumes();
229
230   get_controller
231       Calls the method to get the specified controller info
232
233       Attributes:
234           name -> name of the controller type
235
236   get_controllers
237       Returns a hashref of the hardware controllers for this virtual machine
238
239   drivers
240       List the drivers available for a domain. It may filter for a given
241       type.
242
243           my @drivers = $domain->drivers();
244           my @video_drivers = $domain->drivers('video');
245
246   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
250           $domain->set_driver_id($id_driver);
251
252   last_vm
253       Returns the last virtual machine manager on which this domain was
254       launched.
255
256           my $vm = $domain->last_vm();
257
258   list_requests
259       Returns a list of pending requests from the domain. It won't show those
260       requests scheduled for later.
261
262   list_all_requests
263       Returns a list of pending requests from the domain including those
264       scheduled for later
265
266   get_driver
267       Returns the driver from a domain
268
269       Argument: name of the device [ optional ] Returns all the drivers if
270       not passwed
271
272           my $driver = $domain->get_driver('video');
273
274   get_driver_id
275       Gets the value of a driver
276
277       Argument: name
278
279           my $driver = $domain->get_driver('video');
280
281   set_option
282       Sets a domain option:
283
284       •   description
285
286       •   run_timeout
287
288           $domain->set_option(description => 'Virtual Machine for ...');
289
290   type
291       Returns the virtual machine type as a string.
292
293   rsync
294       Synchronizes the volume data to a remote node.
295
296       Arguments: ( node => $node, request => $request, files => \@files )
297
298       •   node => Ravada::VM
299
300       •   request => Ravada::Request ( optional )
301
302       •   files => listref of files ( optional )
303
304       When files is not specified it syncs the volumes and base volumes if
305       any
306
307   set_base_vm
308           Prepares or removes a base in a virtual manager.
309
310           $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
318   migrate_base
319       Migrates a base to a virtual manager node.
320
321       Alias for set_base_vm.
322
323   remove_base_vm
324       Removes a base in a Virtual Machine Manager node.
325
326         $domain->remove_base_vm($vm, $user);
327
328   file_screenshot
329       Returns the file name where the domain screenshot has been stored
330
331   list_vms
332       Returns a list for virtual machine managers where this domain is base
333
334   base_in_vm
335       Returns if this domain has a base prepared in this virtual manager
336
337           if ($domain->base_in_vm($id_vm)) { ...
338
339   is_local
340       Returns wether this domain is in the local host
341
342   pools
343       Enables or disables pools of clones for this virtual machine
344
345   pool_clones
346       Number of clones of this virtual machine that belong to the pool
347
348   pool_start
349       Number of clones of this virtual machine that are pre-started
350
351   is_pool
352       Return if the virtual machine belongs to a pool of clones
353
354   internal_id
355       Returns the internal id of this domain as found in its Virtual Manager
356       connection
357
358   volatile_clones
359       Enables or disables a domain volatile clones feature. Volatile clones
360       are removed when shut down
361
362   status
363       Sets or gets the status of a virtual machine
364
365         $machine->status('active');
366
367       Valid values are:
368
369       •   active
370
371       •   down
372
373       •   hibernated
374
375   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
379       Possible results:
380
381       •   connecting : set at the start of the virtual machine
382
383       •   IP : known remote ip from the current connection
384
385       •   disconnected : the remote client has been closed
386
387       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
390         # rvd_back --hibernate --disconnected
391         # rvd_back --shutdown --disconnected
392
393       You could also set this command on a cron entry to run nightly, hourly
394       or whenever you find suitable.
395
396   needs_restart
397       Returns true or false if the virtual machine needs to be restarted so
398       some hardware change can be applied.
399
400   Access restrictions
401       These methods implement access restrictions to clone a domain
402
403   allow_ldap_access
404       If specified, only the LDAP users with that attribute value can clone
405       these virtual machines.
406
407           $base->allow_ldap_attribute( attribute => 'value' );
408
409       Example:
410
411           $base->allow_ldap_attribute( tipology => 'student' );
412
413   default_access
414       Sets the default access value
415
416   grant_access
417       Grant access to a virtual machine
418
419       Arguments is a named list
420
421       •   attribute
422
423       •   value
424
425       •   type
426
427       •   allowed ( true / false ) defaults to true
428
429       •   last : if this grant matches it stops looking
430
431   list_access_groups
432       Returns the list of groups who can access this virtual machine
433
434   access_allowed
435       Returns if a client is granted access to a virtual machine
436
437       Arguments: expects a named vars list of client attributes retrieved
438       from the web connection.
439
440   list_access
441       Returns a list of access grants
442
443       Argument: optionally pass the type of grant.
444
445   delete_access
446       Deletes a list of access grants from the database
447
448   delete_ldap_access
449       Deletes a granted ldap access setting
450
451       Argument: id of the access from the table access_ldap_attribute
452
453   list_ldap_access
454       List granted ldap access settings
455
456   deny_ldap_access
457       If specified, only the LDAP users with that attribute value can clone
458       these virtual machines.
459
460           $base->deny_ldap_attribute( attribute => 'value' );
461
462       Example:
463
464           $base->deny_ldap_attribute( tipology => 'student' );
465
466   move_ldap_access
467       Moves an access access grant up or down
468
469       Arguments:
470
471       •   id_ldap_access
472
473       •   position: +1/-1
474
475   move_access
476       Moves an access access grant up or down
477
478       Arguments:
479
480       •   id_access
481
482       •   position: +1/-1
483
484   set_ldap_access
485       Changes access grant allowed and last states
486
487       Arguments:
488
489       •   id_access
490
491       •   allowed
492
493       •   last
494
495   set_access
496       Changes access grant allowed and last states
497
498       •   id_access
499
500       •   allowed
501
502       •   last
503
504   rebase
505       Rebases the virtual machine to another one
506
507       If it is a base it rebases all the clones.
508
509   list_instances
510       Returns a list of instances of the virtual machine in all the physical
511       nodes
512
513   has_non_shared_storage
514       Return wether this virtual machine has non shared storage volumes
515
516   compact
517       Compact volumes of a virtual machine. It creates a backup copy unless
518       specified in the request.
519
520           $domain->compact();
521
522           $comain->compact($request);
523
524       Usually called through Ravada::Request->compact();
525
526   purge
527       Purges old backup volumes of a virtual machine
528
529   refresh_ports
530       Refresh the status of the exposed ports
531

POD ERRORS

533       Hey! The above document had some coding errors, which are explained
534       below:
535
536       Around line 866:
537           You forgot a '=back' before '=head2'
538
539       Around line 2456:
540           You forgot a '=back' before '=head2'
541
542       Around line 6193:
543           You forgot a '=back' before '=head2'
544
545
546
547perl v5.36.0                      2023-03-19                 Ravada::Domain(3)
Impressum