diff --git a/dev-example/gen-pool-vm-crds b/dev-example/gen-pool-vm-crds index 264e3ba..f9cf692 100755 --- a/dev-example/gen-pool-vm-crds +++ b/dev-example/gen-pool-vm-crds @@ -41,7 +41,7 @@ for number in $(seq 1 $count); do if [ -z "$prefix" ]; then prefix=$(basename $template .tpl.yaml) fi - name="$prefix$number" + name="$prefix$(printf %03d $number)" index=$(($number - 1)) esh -o $destination/$name.yaml $template number=$number index=$index done diff --git a/webpages/ConfigAccess-preview.png b/webpages/ConfigAccess-preview.png new file mode 100644 index 0000000..e7523f9 Binary files /dev/null and b/webpages/ConfigAccess-preview.png differ diff --git a/webpages/PoolAccess-preview.png b/webpages/PoolAccess-preview.png new file mode 100644 index 0000000..34db8cd Binary files /dev/null and b/webpages/PoolAccess-preview.png differ diff --git a/webpages/_layouts/vm-operator.html b/webpages/_layouts/vm-operator.html index 590412a..88abf8d 100644 --- a/webpages/_layouts/vm-operator.html +++ b/webpages/_layouts/vm-operator.html @@ -68,6 +68,11 @@

  • For Admins

  • For Users

    • +

    Advanced

    +

    Upgrading

    Javadoc

    diff --git a/webpages/auto-login.md b/webpages/auto-login.md new file mode 100644 index 0000000..c4b859d --- /dev/null +++ b/webpages/auto-login.md @@ -0,0 +1,87 @@ +--- +title: "VM-Operator: Auto login — Login users automatically on the guest" +layout: vm-operator +--- + +# Auto Login + +*Since 4.0.0* + +When users log into the web GUI, they have already authenticated with the +VM-Operator. In some environments, requiring an additional login on the +guest OS can be cumbersome. To enhance the user experience, the VM-Operator +supports automatic login on the guest operating system, thus eliminating +the need for multiple logins. However, this feature requires specific +support from the guest OS. + +## Prepare the VM + +Automatic login requires an agent running inside the guest OS. Similar +to QEMU's standard guest agent, the VM-Operator agent communicates with +the host via a tty device (`/dev/virtio-ports/org.jdrupes.vmop_agent.0`). On +modern Linux systems, `udev` can detect this device and trigger the start +of an associated systemd service. + +Sample configuration files for a VM-Operator agent are available +[here](https://github.com/mnlipp/VM-Operator/tree/main/dev-example/vmop-agent). +Copy + + * `99-vmop-agent.rules` → `/usr/local/lib/udev/rules.d/99-vmop-agent.rules`, + * `vmop-agent` → `/usr/local/libexec/vmop-agent` and + * `vmop-agent.service` → `/usr/local/lib/systemd/system/vmop-agent.service`. + +Some of these target directories may not exist by default and must be +created manually. If your system uses SELinux, run `restorecon` to apply +the correct security contexts. + +Enable the agent: + +```console +# systemctl daemon-reload +# systemctl enable vmop-agent +# udevadm control --reload-rules +# udevadm trigger + ``` + +## The VM operator agent + +Communication with the VM-Operator agent follows the pattern established by +protocols such as SMTP and FTP. The agent must handle the commands +"`login `" and "`logout`" on its input. In response to +these commands, the agent sends back lines that start with a three +digit number. The first digit determines the type of message: "1" for +informational, "2" for success and "4" or "5" for errors. The second +digit provides information about the category that a response relates +to. The third digit is specific to the command. + +While this describes the general pattern, the [runner](runner.html) +only evaluates the following codes: + +| Code | Meaning | +| ---- | ------- | +| 220 | Sent by the agent on startup | +| 201 | Login command executed successfully | +| 202 | Logout command executed successfully | + +The provided sample script is written for the gnome desktop environment. +It assumes that GDM is running as a service by default. When the agent +receives a login command, it stops GDM and starts a gnome-session for +the specified user. Upon receiving the logout command, it terminates +the session and starts GDM again. + +No attempt has been made to make the script configurable. There are too +many possible options. The script should therefore be considered as a +starting point that you may need to adapt to your specific needs. + +In addition to starting the desktop for the logged in user, the sample +script automatically creates user accounts if they do not already exist. +The idea behind this behavior is further explained in the +[section about pools](pools.html#vm-pools). + +## Enable auto login for a VM + +To enable auto login for a VM, specify the user to be logged in in the VM's +definition with "`spec.vm.display.loggedInUser: user-name`". If everything has been +set up correctly, you should be able to open the console and observe the +transition from GDM's login screen to the user's desktop when updating the +VM's spec. diff --git a/webpages/pools.md b/webpages/pools.md index 6b1e75f..b36397e 100644 --- a/webpages/pools.md +++ b/webpages/pools.md @@ -7,67 +7,105 @@ layout: vm-operator *Since 4.0.0* -## Prepare the VM +Not all VMs are defined as replacements for carefully maintained +individual PCs. In many workplaces, a standardardized VM configuration +can be used where all user-specific data is stored in each user's home +directory. By using a shared file system for home directories, users +can login on any VM and find themselves in their personal +environment. + +If only a subset of users require access simultaneously, this makes it +possible to define a pool of standardardized VMs and dynamically assign +them to users as needed, eliminating the need to define a dedicated VM +for each user. + +## Pool definitions + +The VM-operator supports this use case with a CRD for pools. + +```yaml +apiVersion: "vmoperator.jdrupes.org/v1" +kind: VmPool +metadata: + namespace: vmop-dev + name: test-vms +spec: + retention: "PT4h" + loginOnAssignment: true + permissions: + - user: admin + may: + - accessConsole + - start + - role: user + may: + - accessConsole + - start +``` + +The `retention` specifies how long the assignment of a VM from the pool to +a user remains valid after the user closes the console. This ensures that +a user can resume work within this timeframe without the risk of another +user taking over the VM. The time is specified as +[ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations). + +Setting `loginOnAssignment` to `true` triggers automatic login of the +user (as described in [section auto login](auto-login.html)) when +the VM is assigned. The `permissions` property specifies the actions +that users or roles can perform on assigned VMs. + +VMs become members of one (or more) pools by adding the pool name to +the `spec.pools` array, as shown below: + +```yaml +apiVersion: "vmoperator.jdrupes.org/v1" +kind: VirtualMachine + +spec: + pools: + - test-vms +``` + +## Accessing a VM from the pool + +Users can access a VM from a pool using the widget described in +[user view](user-gui.html). The widget must be configured to +provide access to a pool instead of to a specific VM. + +![VM Access configuration](ConfigAccess-preview.png){: width="500"} + +Assignment happens when the "Start" icon is clicked. If the assigned VM +is not already running, it will be started automatically. The assigned +VM's name apears in the widget above the action icons. + +![VM Access via pool](PoolAccess-preview.png) + +Apart from showing the assigned VM, the widget behaves in the same way +as when configured for accessing a specific VM. + +## Guest OS Requirements + +To ensure proper functionality when using VM pools, certain requirements +must be met on the guest OS. ### Shared file system -Mount a shared file system as home file system on all VMs in the pool. -If you want to use the sample script for logging in a user, the filesystem -must support POSIX file access control lists (ACLs). +All VMs in the pool must mount a shared file system as the home directory. +When using the +[sample agent](https://github.com/mnlipp/VM-Operator/tree/main/dev-example/vmop-agent), +the file system must support POSIX file access control lists (ACLs). -### Restrict access +### User management -The VMs should only be accessible via a desktop started by the VM-Operator. +All VMs in the pool must map a given user name to the same user +id. This is typically accomplished by using a central user management, +such as LDAP. The drawback of such a solution is that it is rather +complicated to configure. - * Disable the display manager. +As an alternative, the sample auto login agent provides a very simple +approach that uses the shared home directory for managing the user ids. +Simplified, the script searches for a home directory with the given user +name and derives the user id from it. It then checks if the user id is +known by the guest operating system. If not, the user is added. - ```console - # systemctl disable gdm - # systemctl stop gdm - ``` - - * Disable `getty` on tty1. - - ```console - # systemctl mask getty@tty1 - # systemctl stop getty@tty1 - ``` - -You can, of course, disable `getty` completely. If you do this, make sure -that you can still access your master VM through `ssh`, else you have -locked yourself out. - -Strictly speaking, it is not necessary to disable these services, because -the sample script includes a `Conflicts=` directive in the systemd service -that starts the desktop for the user. However, this is mainly intended for -development purposes and not for production. - -The following should actually be configured for any VM. - - * Prevent suspend/hibernate, because it will lock the VM. - - ```console - # systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target - ``` - -### Install the VM-Operator agent - -The VM-Operator agent runs as a systemd service. Sample configuration -files can be found -[here](https://github.com/mnlipp/VM-Operator/tree/main/dev-example/vmop-agent). -Copy - - * `99-vmop-agent.rules` to `/usr/local/lib/udev/rules.d/99-vmop-agent.rules`, - * `vmop-agent` to `/usr/local/libexec/vmop-agent` and - * `vmop-agent.service` to `/usr/local/lib/systemd/system/vmop-agent.service`. - -Note that some of the target directories do not exist by default and have to -be created first. Don't forget to run `restorecon` on systems with SELinux. - -Enable everything: - -```console -# udevadm control --reload-rules -# systemctl enable vmop-agent -# udevadm trigger - ``` +Details can be found in the comments of the sample script. diff --git a/webpages/upgrading.md b/webpages/upgrading.md index c1331e5..12ff096 100644 --- a/webpages/upgrading.md +++ b/webpages/upgrading.md @@ -10,7 +10,7 @@ layout: vm-operator ## To version 4.0.0 * The VmViewer conlet has been renamed to VmAccess. This affects the - [configuration](https://jdrupes.org/vm-operator/user-gui.html). + [configuration](https://vm-operator.jdrupes.org/user-gui.html). Configuration information using the old path `/Manager/GuiHttpServer/ConsoleWeblet/WebConsole/ComponentCollector/VmViewer` is still accepted for backward compatibility until the next major version, diff --git a/webpages/user-gui.md b/webpages/user-gui.md index 828eb98..be7b6a2 100644 --- a/webpages/user-gui.md +++ b/webpages/user-gui.md @@ -15,7 +15,7 @@ The idea of the user view is to provide an intuitive widget that allows the users to access their own VMs and to optionally start and stop them. -![VM-Viewer](VmAccess-preview.png) +![VM Access](VmAccess-preview.png) The configuration options resulting from this seemingly simple requirement are unexpectedly complex.