diff --git a/webpages/auto-login.md b/webpages/auto-login.md index 8893bc5..c4b859d 100644 --- a/webpages/auto-login.md +++ b/webpages/auto-login.md @@ -7,33 +7,34 @@ layout: vm-operator *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. +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 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. +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 can be found +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` 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`. + * `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`. -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. +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 everything: +Enable the agent: ```console # systemctl daemon-reload @@ -44,17 +45,17 @@ Enable everything: ## 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. +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 only response code that -the runner evaluates are: +While this describes the general pattern, the [runner](runner.html) +only evaluates the following codes: | Code | Meaning | | ---- | ------- | @@ -62,17 +63,19 @@ the runner evaluates are: | 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. +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 can adapt to your needs. +starting point that you may need to adapt to your specific 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 +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 @@ -80,5 +83,5 @@ yet. The idea behind this is further explained in the 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 +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 5b587ea..b36397e 100644 --- a/webpages/pools.md +++ b/webpages/pools.md @@ -7,12 +7,17 @@ layout: vm-operator *Since 4.0.0* -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. +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 @@ -39,18 +44,18 @@ spec: ``` 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 +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 defines what a user can -do with a VM assigned to him. +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 -property `spec.pools` (an array of strings), e.g.: +the `spec.pools` array, as shown below: ```yaml apiVersion: "vmoperator.jdrupes.org/v1" @@ -69,26 +74,26 @@ 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 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. +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 it does when configured to access a specific VM. +as when configured for accessing a specific VM. -## Requirements on the guest +## Guest OS Requirements -Some provisions must be made on the guest to ensure that VMs from -pools work as expected. +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. 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). +the file system must support POSIX file access control lists (ACLs). ### User management