Merge branch 'feature/auto-login'

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

webpages/_layouts/vm-operator.html

@@ -68,6 +68,11 @@
         <li><p class="part-entry"><a href="admin-gui.html">For Admins</a></p></li>
         <li><p class="part-entry"><a href="user-gui.html">For Users</a></p></li>
         </ul>
+        <p class="part-list-title">Advanced</p>
+        <ul style="margin-bottom: 0;" class="no-bullets">
+        <li><p class="part-entry"><a href="auto-login.html">Auto Login</a></p></li>
+        <li><p class="part-entry"><a href="pools.html">Pools</a></p></li>
+        </ul>
         <p class="part-list-title"><a href="upgrading.html">Upgrading</a></p>
         <p class="part-list-title"><a href="https://vm-operator.jdrupes.org/javadoc/index.html">Javadoc</a></p>
 

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 <username>`" 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.

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.
+All VMs in the pool must mount a shared file system as the home directory.
-If you want to use the sample script for logging in a user, the filesystem
+When using the
-must support POSIX file access control lists (ACLs).
+[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
+Details can be found in the comments of the sample script.
-    # 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
- ```

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,

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.