mnl/VM-Operator
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages 4 Wiki Activity Actions

Editorial changes.

Browse source
This commit is contained in:
Michael Lipp 2025-03-06 11:43:32 +01:00
parent 7dc68b5ac7
commit c51da8650a
2 changed files with 65 additions and 57 deletions
Download patch file Download diff file Expand all files Collapse all files

75
webpages/auto-login.md
View file

@ -7,33 +7,34 @@ layout: vm-operator
*Since 4.0.0* *Since 4.0.0*
When a user logs in on the web GUI, he has already authenticated with the When users log into the web GUI, they have already authenticated with the
VM-Operator. Depending on the environment, it may be tedious to log in again VM-Operator. In some environments, requiring an additional login on the
on the guest. The VM-Operator therefore supports automatic login on the guest guest OS can be cumbersome. To enhance the user experience, the VM-Operator
operating system which can streamline the user experience by eliminating supports automatic login on the guest operating system, thus eliminating
the need for multiple logins. This requires, however, some support from the need for multiple logins. However, this feature requires specific
the guest OS. support from the guest OS.
## Prepare the VM ## Prepare the VM
Automatic login requires an agent in the guest OS. Similar to QEMU's Automatic login requires an agent running inside the guest OS. Similar
standard guest agent, the VM-Operator agent communicates with the host to QEMU's standard guest agent, the VM-Operator agent communicates with
through a tty device (`/dev/virtio-ports/org.jdrupes.vmop_agent.0`). On a modern the host via a tty device (`/dev/virtio-ports/org.jdrupes.vmop_agent.0`). On
Linux system, the device is detected by `udev` which triggers the start modern Linux systems, `udev` can detect this device and trigger the start
of a systemd service. 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). [here](https://github.com/mnlipp/VM-Operator/tree/main/dev-example/vmop-agent).
Copy Copy
* `99-vmop-agent.rules` to `/usr/local/lib/udev/rules.d/99-vmop-agent.rules`, * `99-vmop-agent.rules` → `/usr/local/lib/udev/rules.d/99-vmop-agent.rules`,
* `vmop-agent` to `/usr/local/libexec/vmop-agent` and * `vmop-agent` → `/usr/local/libexec/vmop-agent` and
* `vmop-agent.service` to `/usr/local/lib/systemd/system/vmop-agent.service`. * `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 Some of these target directories may not exist by default and must be
be created first. Don't forget to run `restorecon` on systems with SELinux. created manually. If your system uses SELinux, run `restorecon` to apply
the correct security contexts.
Enable everything: Enable the agent:
```console ```console
# systemctl daemon-reload # systemctl daemon-reload
@ -44,17 +45,17 @@ Enable everything:
## The VM operator agent ## The VM operator agent
Communication with the VM-Operator agent follows the pattern established Communication with the VM-Operator agent follows the pattern established by
by protocols such as SMTP and FTP. The agent must handle the commands protocols such as SMTP and FTP. The agent must handle the commands
"`login <username>`" and "`logout`". In response to these commands, the agent "`login <username>`" and "`logout`" on its input. In response to
sends back lines that start with a three digit number. The first digit these commands, the agent sends back lines that start with a three
determines the type of message: "1" for informational, "2" for success digit number. The first digit determines the type of message: "1" for
"4" and "5" for errors. The second digit provides information about the informational, "2" for success and "4" or "5" for errors. The second
category that the response relates to. The third digit is specific to digit provides information about the category that a response relates
the command. to. The third digit is specific to the command.
While this describes the general pattern, the only response code that While this describes the general pattern, the [runner](runner.html)
the runner evaluates are: only evaluates the following codes:
| Code | Meaning | | Code | Meaning |
| ---- | ------- | | ---- | ------- |
@ -62,17 +63,19 @@ the runner evaluates are:
| 201 | Login command executed successfully | | 201 | Login command executed successfully |
| 202 | Logout command executed successfully | | 202 | Logout command executed successfully |
The sample script is written for the gnome desktop environment. It assumes The provided sample script is written for the gnome desktop environment.
that gdm is running as a service by default. On receiving the login command, It assumes that GDM is running as a service by default. When the agent
it stops gdm and starts a gnome-session for the given user. On receiving the receives a login command, it stops GDM and starts a gnome-session for
logout command, it terminates the session and starts gdm again. 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 No attempt has been made to make the script configurable. There are too
many possible options. The script should therefore be considered as a 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 In addition to starting the desktop for the logged in user, the sample
yet. The idea behind this is further explained in the 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). [section about pools](pools.html#vm-pools).
## Enable auto login for a VM ## 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 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 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 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. VM's spec.

45
webpages/pools.md
View file

@ -7,12 +7,17 @@ layout: vm-operator
*Since 4.0.0* *Since 4.0.0*
Not all VMs are replacements for carefully maintained individual PCs. Not all VMs are defined as replacements for carefully maintained
In many workplaces, a standard configuration can be used where individual PCs. In many workplaces, a standardardized VM configuration
user-specific data is kept in each user's home directory on a shared can be used where all user-specific data is stored in each user's home
file system. In such cases, an alternative to providing individual directory. By using a shared file system for home directories, users
PCs is to offer a pool of VMs and allocate them from the pool to users can login on any VM and find themselves in their personal
as needed. 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 ## Pool definitions
@ -39,18 +44,18 @@ spec:
``` ```
The `retention` specifies how long the assignment of a VM from the pool to 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 a user remains valid after the user closes the console. This ensures that
to interrupt his work for this period of time without risking that a user can resume work within this timeframe without the risk of another
another user takes over the VM. The time is specified as user taking over the VM. The time is specified as
[ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations). [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations).
Setting `loginOnAssignment` to `true` triggers automatic login of the Setting `loginOnAssignment` to `true` triggers automatic login of the
user (as described in [section auto login](auto-login.html)) when user (as described in [section auto login](auto-login.html)) when
the VM is assigned. The `permissions` property defines what a user can the VM is assigned. The `permissions` property specifies the actions
do with a VM assigned to him. that users or roles can perform on assigned VMs.
VMs become members of one (or more) pools by adding the pool name to 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 ```yaml
apiVersion: "vmoperator.jdrupes.org/v1" apiVersion: "vmoperator.jdrupes.org/v1"
@ -69,23 +74,23 @@ provide access to a pool instead of to a specific VM.
![VM Access configuration](ConfigAccess-preview.png){: width="500"} ![VM Access configuration](ConfigAccess-preview.png){: width="500"}
Assignment happens when the "start" icon is pushed. If the assigned VM Assignment happens when the "Start" icon is clicked. If the assigned VM
is not running, it will also be started. The assigned VM's name is is not already running, it will be started automatically. The assigned
shown in the widget above the action icons. VM's name apears in the widget above the action icons.
![VM Access via pool](PoolAccess-preview.png) ![VM Access via pool](PoolAccess-preview.png)
Apart from showing the assigned VM, the widget behaves in the same way 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 To ensure proper functionality when using VM pools, certain requirements
pools work as expected. must be met on the guest OS.
### Shared file system ### 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 When using the
[sample agent](https://github.com/mnlipp/VM-Operator/tree/main/dev-example/vmop-agent), [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). the file system must support POSIX file access control lists (ACLs).