Ravada::Domain(3)

✨ NAME ✨

Ravada::Domain — the Domains ( Virtual Machines ) library for Ravada 💖🦋

Okay so bestie, welcome to the Ravada::Domain manpage! This is where all the virtual machine domain magic happens. Let's get into it. Periodt. 💅

---

✨ allowed_booking ✨

Returns true if a user is allowed in a booking for this virtual machine or its base. Returns false otherwise. It's giving permission check energy. 🎀

$machine->allowed_booking($user);

✨ pre_prepare_base ✨

Run this before preparing the base. By default it does nothing, and it may be implemented in the object.

This is executed automatically, so it shouldn't be called. Like, don't call it, okay? It's not for you. 🙈

✨ prepare_base ✨

Prepares the virtual machine as a base. It's a whole vibe:

• shuts it down
• creates read only volumes based on this base
• locks it so it won't get started
• stores the virtual machine template for the clones

✨ post_prepare_base ✨

Placeholder for optional method implemented in subclasses. This will run after preparing the base files. It's like the afterparty for base prep. 🎉

✨ spinoff ✨

Makes volumes independent from base. It's giving freedom for the volumes. 🦋

sub _check_disk_modified {
    my $self = shift;

    if ( !$self->is_base() ) {
        return;
    }

    my $last_stat_base = 0;
    for my $file_base ( $self->list_files_base ) {
        my @stat_base = stat($file_base);
        $last_stat_base = $stat_base[9] if$stat_base[9] > $last_stat_base;
#        warn $last_stat_base;
    }

    my $files_updated = 0;
    for my $file ( $self->disk_device ) {
        my @stat = stat($file) or next;
        $files_updated++ if $stat[9] > $last_stat_base;
#        warn "\ncheck\t$file ".$stat[9]."\n vs \tfile_base $last_stat_base $files_updated\n";
    }
    die "Base already created and no disk images updated"
        if !$files_updated;
}

✨ id ✨

Returns the id of the domain. Literally just the id. 🆔

my $id = $domain->id();

✨ open ✨

Open a domain. It's giving access.

Argument: id

Arguments: id => $id, [ readonly => {0|1} ]

Returns: Domain object

✨ check_status ✨

Checks if a virtual machine known status is in sync. It's like a vibe check for your VM. ✨

• Checks it is already started
• Performs shutdown cleaning procedures if down

✨ is_known ✨

Returns if the domain is known in Ravada. Like, does Ravada know you? 👀

✨ is_known_extra ✨

Returns if the domain has extra fields information known in Ravada. Extra info, extra slay. 💅

✨ start_time ✨

Returns the last time (epoch format in seconds) the domain was started. Time stamps, bestie. ⏰

✨ spice_password ✨

Returns the password defined for the spice viewers. Spicy! 🌶️

✨ display_file ✨

Returns a file with the display information. Defaults to spice.

✨ display_file_tls ✨

Returns a file with the display information in TLS connections. Defaults to spice.

✨ display ✨

Returns the display information. That's it. 🖥️

✨ info ✨

Return information about the domain. Info dump, but make it cute. 📋

✨ pre_remove ✨

Code to run before removing the domain. It can be implemented in each domain. It is not expected to run by itself, the remove function calls it before proceeding.

$domain->pre_remove();  # This isn't likely to be necessary
$domain->remove();      # Automatically calls the domain pre_remove method

✨ restore ✨

Returns the clone to an initial state. It's giving factory reset but for your VM. 🔄

Depending of the type of volumes added to the virtual machines all the information stored there is removed. Only data volumes are kept untouched.

• system : cleaned to the initial state
• tmp/swap : cleaned to the initial state
• data : nothing gets removed

✨ is_base ✨

Returns true or false if the domain is a prepared base. Base or not base, that is the question. 🎭

✨ is_locked ✨

Shows if the domain has running or pending requests. It could be considered too as the domain is busy doing something like starting, shutdown or prepare base. Returns true if locked. Busy bee energy. 🐝

✨ id_owner ✨

Returns the id of the user that created this domain. The OG creator. 👑

✨ id_base ✨

Returns the id from the base this domain is based on, if any. If it's a clone, this is its parent. 👯

✨ vm ✨

Returns a string with the name of the VM ( Virtual Machine ) this domain was created on. VM name drop. 💁

✨ clones ✨

Returns a list of clones from this virtual machine.

my @clones = $domain->clones

✨ has_clones ✨

Returns the number of clones from this virtual machine.

my $has_clones = $domain->has_clones

✨ list_files_base ✨

Returns a list of the filenames of this base-type domain. File names, bestie. 📁

✨ list_files_base_target ✨

Returns a list of the filenames and targets of this base-type domain. More file details. 🎯

✨ can_screenshot ✨

Returns whether this domain can take a screenshot. Say cheese! 📸

✨ remove_base ✨

Makes the domain a regular, non-base virtual machine and removes the base files. It's giving demotion but for a good reason. 🫡

✨ clone ✨

Clones a domain. Clone army, assemble! 🧬

arguments

• user => $user : The user that owns the clone
• name => $name : Name of the new clone

✨ can_hybernate ✨

Returns whether a domain supports hybernation. (Yes, it's spelled "hybernate" here, we keep it real.) 💤

✨ can_hibernate ✨

Returns whether a domain supports hibernation. Same vibe, different spelling. 😴

✨ add_volume_swap ✨

Adds a swap volume to the virtual machine. Swap it like it's hot. 🔥

Arguments:

size => $kb
name => $name (optional)

✨ expose ✨

Expose a TCP port from the domain. It's giving public access. 🌐

Arguments:

• number of the port
• optional name

Returns: public ip and port

✨ exposed_port ✨

Returns all the data from an exposed port. Data reveal. 🔍

Argument: number or name description of the port permission.

my $port_data = $domain->exposed_port(80);

my $port_data = $domain->exposed_port('web');

✨ open_exposed_ports ✨

Performs an iptables open of all the exposed ports of the domain. Opening the floodgates. 🚪

✨ remove_expose ✨

Remove exposed port. Closing the door. 🚪

Argument: virtual machine exposed port [ optional ]

If no port is passed all the exposed ports are removed. So if you're lazy, it removes all. 💅

✨ list_ports ✨

List of exposed TCP ports. Port inventory. 📋

✨ post_resume_aux ✨

Method after resume. Like a post-resume snack. 🍓

✨ open_iptables ✨

Open iptables for a remote client. Firewall says welcome. 🔥

• user
• remote_ip

✨ is_public ✨

Sets or get the domain public. Public or private, you decide. 🤳

$domain->is_public(1);

if ($domain->is_public()) {
    ...
}

✨ is_volatile ✨

Returns if the domain is volatile, so it will be removed on shutdown. Here for a good time, not a long time. 💀

✨ is_persistent ✨

Returns true if the virtual machine is persistent. So it is not removed after shut down. It's a keeper. 💖

✨ run_timeout ✨

Sets or get the domain run timeout. When it expires it is shut down. Tick tock. ⏳

$domain->run_timeout(60 * 60); # 60 minutes

✨ clean_swap_volumes ✨

Check if the domain has swap volumes defined, and clean them. Tidy up, bestie. 🧹

$domain->clean_swap_volumes();

✨ get_controller ✨

Calls the method to get the specified controller info. Controller, like a video game. 🎮

Attributes:

name -> name of the controller type

✨ get_controllers ✨

Returns a hashref of the hardware controllers for this virtual machine. Hashref realness. 🗂️

✨ drivers ✨

List the drivers available for a domain. It may filter for a given type. Vroom vroom. 🏎️

my @drivers = $domain->drivers();
my @video_drivers = $domain->drivers('video');

✨ set_driver_id ✨

Sets the driver of a domain given it id. The id must be one from the table domain_drivers_options. Table realness. 📊

$domain->set_driver_id($id_driver);

✨ last_vm ✨

Returns the last virtual machine manager on which this domain was launched. Where it last hung out. 🏠

my $vm = $domain->last_vm();

✨ list_requests ✨

Returns a list of pending requests from the domain. It won't show those requests scheduled for later. Only the now-now. ⏱️

✨ list_all_requests ✨

Returns a list of pending requests from the domain including those scheduled for later. The whole future. 🔮

✨ get_driver ✨

Returns the driver from a domain. Driver's license, please. 🚗

Argument: name of the device [ optional ] Returns all the drivers if not passwed

my $driver = $domain->get_driver('video');

✨ get_driver_id ✨

Gets the value of a driver. Driver value. 📈

Argument: name

my $driver = $domain->get_driver('video');

✨ set_option ✨

Sets a domain option:

• description
• run_timeout

$domain->set_option(description => 'Virtual Machine for ...');

✨ type ✨

Returns the virtual machine type as a string. Type, like a personality. 💁

✨ rsync ✨

Synchronizes the volume data to a remote node. Sync up, bestie. 🔄

Arguments: ( node => $node, request => $request, files => \@files )

• node => Ravada::VM
• request => Ravada::Request ( optional )
• files => listref of files ( optional )

When files is not specified it syncs the volumes and base volumes if any.

✨ set_base_vm ✨

Prepares or removes a base in a virtual manager. Base management, periodt. 🛠️

$domain->set_base_vm(
    id_vm => $id_vm         # you can pass the id_vm
      ,vm => $vm            #    or the vm
    ,user => $user
   ,value => $value  # if it is 0, it removes the base
 ,request => $req
);

✨ migrate_base ✨

Migrates a base to a virtual manager node. Moving day for your base. 🚚

Alias for set_base_vm.

✨ remove_base_vm ✨

Removes a base in a Virtual Machine Manager node. Bye-bye base. 👋

$domain->remove_base_vm($vm, $user);

✨ file_screenshot ✨

Returns the file name where the domain screenshot has been stored. Where the selfies live. 📸

✨ list_vms ✨

Returns a list for virtual machine managers where this domain is base. Where it's the base. 🏠

✨ base_in_vm ✨

Returns if this domain has a base prepared in this virtual manager. Base check. ✅

if ($domain->base_in_vm($id_vm)) { ...

✨ is_local ✨

Returns whether this domain is in the local host. Local or remote? 📍

✨ pools ✨

Enables or disables pools of clones for this virtual machine. Pool party! 🏊

✨ pool_clones ✨

Number of clones of this virtual machine that belong to the pool. How many in the pool. 🔢

✨ pool_start ✨

Number of clones of this virtual machine that are pre-started. Pre-started and ready. 🚀

✨ is_pool ✨

Return if the virtual machine belongs to a pool of clones. Are you in the pool? 🤔

✨ internal_id ✨

Returns the internal id of this domain as found in its Virtual Manager connection. Internal ID, like a secret identity. 🕵️

✨ volatile_clones ✨

Enables or disables a domain volatile clones feature. Volatile clones are removed when shut down. Here for a good time, not a long time (again). 💀

✨ status ✨

Sets or gets the status of a virtual machine. Status update. 📢

$machine->status('active');

Valid values are:

• active
• down
• hibernated

✨ client_status ✨

Returns the status of the viewer connection. The virtual machine must be active, and the remote ip must be known. Viewer status check. 👀

Possible results:

• connecting : set at the start of the virtual machine
• IP : known remote ip from the current connection
• disconnected : the remote client has been closed

This method is used from higher level commands, for example, you can shut down or hibernate all the disconnected virtual machines like this:

# rvd_back --hibernate --disconnected
# rvd_back --shutdown --disconnected

You could also set this command on a cron entry to run nightly, hourly or whenever you find suitable.

my $time_checked = time - $self->_data('client_status_time_checked');
if ( $time_checked < $TIME_CACHE_NETSTAT && !$force ) {
    return $self->_data('client_status');
}

✨ needs_restart ✨

Returns true or false if the virtual machine needs to be restarted so some hardware change can be applied. Restart for the glow-up. 🔄

✨ Access restrictions ✨

These methods implement access restrictions to clone a domain. Gatekeeping, but make it secure. 🔐

✨ allow_ldap_access ✨

If specified, only the LDAP users with that attribute value can clone these virtual machines. LDAP gatekeeping. 🛡️

$base->allow_ldap_attribute( attribute => 'value' );

Example:

$base->allow_ldap_attribute( tipology => 'student' );

✨ default_access ✨

Sets the default access value. Default access, like a default setting. ⚙️

✨ grant_access ✨

Grant access to a virtual machine. Access granted. 🎟️

Arguments is a named list:

• attribute
• value
• type
• allowed (true / false) — defaults to true 💖
• last — if this grant matches, it stops looking 👀

---

✨ list_access_groups ✨

Returns the list of groups who can access this virtual machine 🫶

✨ access_allowed ✨

Returns if a client is granted access to a virtual machine.

Arguments: expects a named vars list of client attributes retrieved from the web connection. 🌐

✨ list_access ✨

Returns a list of access grants.

Argument: optionally pass the type of grant. 🔍

✨ delete_access ✨

Deletes a list of access grants from the database. 🗑️

✨ delete_ldap_access ✨

Deletes a granted ldap access setting.

Argument: id of the access from the table access_ldap_attribute. 🆔

✨ list_ldap_access ✨

List granted ldap access settings. 📋

✨ deny_ldap_access ✨

If specified, only the LDAP users with that attribute value can clone these virtual machines. 🚫

$base->deny_ldap_attribute( attribute => 'value' );

Example:

$base->deny_ldap_attribute( tipology => 'student' );

✨ move_ldap_access ✨

Moves an access access grant up or down. ⬆️⬇️

Arguments:

• id_ldap_access
• position: +1/-1

✨ move_access ✨

Moves an access access grant up or down. ⬆️⬇️

Arguments:

• id_access
• position: +1/-1

✨ set_ldap_access ✨

Changes access grant allowed and last states. 🔄

Arguments:

• id_access
• allowed
• last

✨ set_access ✨

Changes access grant allowed and last states. 🔄

• id_access
• allowed
• last

✨ rebase ✨

Rebases the virtual machine to another one. 🧬

If it is a base it rebases all the clones. 👯

✨ list_instances ✨

Returns a list of instances of the virtual machine in all the physical nodes. 🖥️

✨ has_non_shared_storage ✨

Return wether this virtual machine has non shared storage volumes. 💾

✨ compact ✨

Compact volumes of a virtual machine. It creates a backup copy unless specified in the request. 📦

$domain->compact();

$comain->compact($request);

Usually called through Ravada::Request->compact(); 🫡

✨ purge ✨

Purges old backup volumes of a virtual machine. 🧹

✨ refresh_ports ✨

Refresh the status of the exposed ports. 🔌

Argument: type of grace to check

Returns:

• 1 if we reached the end of grace time ⏰
• 0 if dont 🚫

---

🚨 POD ERRORS 🚨

Hey! The above document had some coding errors, which are explained below:

• Around line 1038:

You forgot a '=back' before '=head2'

• Around line 2782:

You forgot a '=back' before '=head2'

• Around line 6813:

You forgot a '=back' before '=head2'

---

okay bestie that's a wrap! 💅 this page was served up by perl v5.42.0 on 2025-09-20 and it's literally Ravada::Domain(3) — no cap, go forth and slay those virtual machines ✨🦋💖