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..8893bc5
--- /dev/null
+++ b/webpages/auto-login.md
@@ -0,0 +1,84 @@
+---
+title: "VM-Operator: Auto login — Login users automatically on the guest"
+layout: vm-operator
+---
+
+# Auto Login
+
+*Since 4.0.0*
+
+When a user logs in on the web GUI, he has already authenticated with the
+VM-Operator. Depending on the environment, it may be tedious to log in again
+on the guest. The VM-Operator therefore supports automatic login on the guest
+operating system which can streamline the user experience by eliminating
+the need for multiple logins. This requires, however, some support from
+the guest OS.
+
+## Prepare the VM
+
+Automatic login requires an agent in the guest OS. Similar to QEMU's
+standard guest agent, the VM-Operator agent communicates with the host
+through a tty device (`/dev/virtio-ports/org.jdrupes.vmop_agent.0`). On a modern
+Linux system, the device is detected by `udev` which triggers the start
+of 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
+# 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`". 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
+"4" and "5" for errors. The second digit provides information about the
+category that the response relates to. The third digit is specific to
+the command.
+
+While this describes the general pattern, the only response code that
+the runner evaluates are:
+
+| Code | Meaning |
+| ---- | ------- |
+| 220 | Sent by the agent on startup |
+| 201 | Login command executed successfully |
+| 202 | Logout command executed successfully |
+
+The sample script is written for the gnome desktop environment. It assumes
+that gdm is running as a service by default. On receiving the login command,
+it stops gdm and starts a gnome-session for the given user. On 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 can adapt to your needs.
+
+The sample script also creates new user accounts if a user does not exist
+yet. The idea behind this 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
+change 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..5b587ea 100644
--- a/webpages/pools.md
+++ b/webpages/pools.md
@@ -7,67 +7,100 @@ layout: vm-operator
*Since 4.0.0*
-## Prepare the VM
+Not all VMs are replacements for carefully maintained individual PCs.
+In many workplaces, a standard configuration can be used where
+user-specific data is kept in each user's home directory on a shared
+file system. In such cases, an alternative to providing individual
+PCs is to offer a pool of VMs and allocate them from the pool to users
+as needed.
+
+## 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 is retained after the user closes the console. This allows a user
+to interrupt his work for this period of time without risking that
+another user takes 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 defines what a user can
+do with a VM assigned to him.
+
+VMs become members of one (or more) pools by adding the pool name to
+property `spec.pools` (an array of strings), e.g.:
+
+```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.
+
+{: width="500"}
+
+Assignment happens when the "start" icon is pushed. If the assigned VM
+is not running, it will also be started. The assigned VM's name is
+shown in the widget above the action icons.
+
+
+
+Apart from showing the assigned VM, the widget behaves in the same way
+as it does when configured to access a specific VM.
+
+## Requirements on the guest
+
+Some provisions must be made on the guest to ensure that VMs from
+pools work as expected.
### 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).
+When using the
+[sample agent](https://github.com/mnlipp/VM-Operator/tree/main/dev-example/vmop-agent),
+the filesystem 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/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.
-
+
The configuration options resulting from this seemingly simple
requirement are unexpectedly complex.