vmtui 0.9.5
A text user interface (TUI) to control virtual machines on a per user basis
Keywords: libvirt, KVM, VM

# VMTUI

*a text user interface to control libvirt VMs on a per user basis.*

## libvirt polkit configuration

`VMTUI` is intended as a simple interface to allow unprivileged user accounts to control (i.e. (re)start, shutdown, install) their personal virtual machines.
To make use of this, libvirt must be configured to use polkit. The package provides a helper script `gen_libvirt_polkit_acl` that allows the generation of an ACL policy based on a yaml database.

The `libvirtd.conf` file must be modified [src](https://fedoraproject.org/wiki/QA:Testcase_Virt_ACLs) and `virtqemud.conf` as well:

`/etc/libvirt/libvirtd.conf` and `/etc/libvirt/virtqemud.conf`:

~~~conf
access_drivers = [ "polkit" ]
~~~

In this example, a user account must belong to the `adm_vmhost` group to get full priviliges.
User accounts with personal VMs must belong to the `user_vm` group.

`/etc/polkit-1/rules.d/100-libvirt-acl.rules`:

~~~javascript
polkit.addRule(function(action, subject) {
    if (
        subject.isInGroup("adm_vmhost") ||

        false // makes generation easier
       ) {
        if (action.id == "org.libvirt.unix.manage" || action.id.startsWith("org.libvirt.api")) {
            return polkit.Result.YES;
        }

        } else if ( subject.isInGroup("user_vm") ) {
            if (action.id == "org.libvirt.unix.manage" || action.id.startsWith("org.libvirt.api.connect")) {
                return polkit.Result.YES;
            } else if (action.id.startsWith("org.libvirt.api.domain") && action.lookup("connect_driver")=="QEMU") {
                var dom = action.lookup("domain_name");
                if((subject.user == "alice" && dom == "rocky9-2") ||
                   (subject.user == "bob" && dom == "rocky9-3") || // these are the "entry types that must be read from a file, either to grant access to a user or a group
                   false // makes generation easier
                ) {
                    return polkit.Result.YES;
                    } else {
                    return polkit.Result.NO;
                }
            } else if ( action.id.startsWith("org.libvirt.api.network") ) {
                if ( action.id.endsWith("getattr") ||
                     action.id.endsWith("read") ||
                     action.id.endsWith("create")
                    ) {
                    return polkit.Result.YES;
                } else {
                    return polkit.Result.NO;
                }
            }
    }
        return polkit.Result.NO;
}
);

~~~

> The example grants the user `alice` access to the domain `rocky9-2`, while `bob` is allowed to manage `rocky9-3`.

To simplify the generation of the polkit ACL use the `s` script and provide a `user_acl.yaml`:

~~~yaml
libvirt_acl:
  admin_groups: # configure groups that have full access
    - adm_vmhost
  domains: # domain specific ACL
    rocky9: # grant users alice and bob and members of the group mod_vmhost access to 'rocky9''
      users:
        - alice
        - bob
      groups:
        - mod_vmhost
    rocky9-2: # grant alice access to rocky9-2 
      users:
        - alice
    rocky9-3: # grant bob access to rocky9-3
      users:
        - bob
~~~

To generate the ACL (as root):

~~~bash
gen_libvirt_polkit_acl --acl /etc/libvirt_acl.yaml 
~~~

It might be necessary to restart libvirt and polkit.

~~~bash
systemctl restart polkit # usually automatically reloads files
systemctl restart libvirtd
~~~

## SSH configuration for vmtui

You can limit ssh access to vmtui with the following configuration (limits members of the `user_vm` group to `vmtui`).
It is recommended to use a virtual environment (here `/opt/vmtui`).

`/etc/ssh/sshd_config.d/10-vmtui-conf`

~~~conf
Match Group user_vm
    ForceCommand /opt/vmtui/bin/vmtui
~~~