Add documentation.
This commit is contained in:
parent
5ae162445c
commit
7dc68b5ac7
6 changed files with 179 additions and 57 deletions
BIN
webpages/ConfigAccess-preview.png
Normal file
BIN
webpages/ConfigAccess-preview.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
BIN
webpages/PoolAccess-preview.png
Normal file
BIN
webpages/PoolAccess-preview.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 6.9 KiB |
|
|
@ -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>
|
||||
|
||||
|
|
|
|||
84
webpages/auto-login.md
Normal file
84
webpages/auto-login.md
Normal file
|
|
@ -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 <username>`" 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.
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue