document new XRDP configuration

docs/admin-guide/configuration/desktop/xrdp.md

@@ -58,33 +58,114 @@ _At the moment you can access the new features within puppet with_
 ```bash
 puppet agent -t --environment xrdp_ng
 ```
-_and to really activate it for a maybe already running XRDP server with a reboot or `systemctl restart xrdp`._
+_and to really activate it for a maybe already running XRDP server with a reboot or `systemctl restart xrdp` and `systemctl restart gdm` which kills all existing desktop sessions._
 
 The basic configuration in Hiera is:
 
 ```yaml
 xrdp::enable: true
 ```
-This allow to access the currently running desktop (primary screen only in multi-monitor setups) or, if none exists, creates automatically a virtual desktop. 
+
+which by default makes XRDP run in terminal server mode where only virtual desktop sessions are available.
+The explicit configuration would be:
+
+```yaml
+xrdp::mode: 'virtual_desktops_only'
+```
+### Access to Physical Desktop
+
+!!! warning
+    Accessing to your/a real physcial destop session causes a security risk with people having physical access to the workstation. They can see on the real monitor what you are doing and interfer with keyboard and mouse. It is similar as if you are away from the workstation and have the screen unlocked.
+
+Note that due to technical limitiations it is only possible to access the primary screen in multi-monitor setups.
+
+For accessing the physical desktop there are three different modes supported:
+
+```yaml
+xrdp::mode: 'access_users_physical_desktop_or_fallback_to_virtual_desktop'
+```
+
+This allow to access to currently running desktop of the accessing user or, if none exists, creates automatically a virtual desktop.
 Note that you should log out of the virtual desktop before logging in again on the physical desktop.
 But it is fine to have multiple different users running own virtual desktops as long as they are different to the one useing the physical desktop.
 
-
-Some more details could be ajusted when needed:
-
-To disallow access the physical desktop:
 ```yaml
-xrdp::shared_physical_desktop::enable: false
+xrdp::mode: 'access_physical_desktop_of_whatever_user_logged_in'
 ```
+This mode is for the case where a shared account (GAC-account or e-account) is used e.g. on a console. Whoever has permissions to log into this computer can see and interact with the physical desktop, independent of the actual user which logged into the desktop.
 
-whereas to disallow virtual desktop sessions there is
+In this and only this mode you can even access the login window of the session manager `gdm`. Note that you cannot login with your own account, you need to use another one, e.g. the GAC-account. After successful login you connection terminates as the `Xorg` session of `gdm` terminates too. But if you connect again you get access to the new desktop session.
+
+There are no virtual sessions possible in this mode.
 
 ```yaml
-xrdp::virtual_desktop::enable: false
+xrdp::mode: 'user_selects_physical_or_virtual_desktop'
+```
+If you or your users can make an informed decision if they want to use a virtual session or access the physical session then you can give offer them the selection using this mode.
+
+Note that in this and only this mode the virtual sessions do not survive a restart of the `xrdp` deamon, e.g. due to a software update.
+
+### Troubleshouting
+
+#### Session Already Running
+
+!["Session Already Running" dialog](xrdp/session_already_running.png)
+
+
+Systemd and Gnome do not really allow for more than one conncurrent session for the same user.
+
+Easiest solution: reboot/powercycle the machine.
+
+Or somehow connect to the other session and close it (using RDP from a colleagues machine, etc.).
+
+If you can log in with `ssh` you can also terminate the session from the shell:
+
+```
+[buchel_k@lxdev08 ~]$ loginctl 
+SESSION   UID USER     SEAT  TTY   STATE  IDLE SINCE
+     11 44951 buchel_k       pts/0 active no        
+     13 44951 buchel_k seat0 tty2  active no        
+
+2 sessions listed.
+[buchel_k@lxdev08 ~]$ loginctl kill-session 13
+[buchel_k@lxdev08 ~]$ 
+```
+As seen above, physical sessions have a "seat", whereas the `ssh` session has a `pts` (pseudo terminal).
+
+Virtual sessions do not have a "tty":
+
+```
+[buchel_k@lxdev08 ~]$ loginctl 
+SESSION   UID USER     SEAT  TTY   STATE  IDLE SINCE
+     11 44951 buchel_k       pts/0 active no        
+     15 44951 buchel_k       n/a   active no        
+     c3    42 gdm      seat0 tty1  active no        
+
+3 sessions listed.
+[buchel_k@lxdev08 ~]$
+[buchel_k@lxdev08 ~]$ loginctl  show-session 15
+Id=15
+User=44951
+Name=buchel_k
+Timestamp=Fri 2026-03-20 10:21:03 CET
+TimestampMonotonic=59919783992
+VTNr=0
+Display=:11
+Remote=yes
+RemoteHost=::ffff:129.129.175.98
+Service=xrdp-sesman
+Scope=session-15.scope
+Leader=95172
+Audit=15
+Type=x11
+Class=user
+Active=yes
+State=active
+IdleHint=no
+IdleSinceHint=0
+IdleSinceHintMonotonic=0
+LockedHint=no
+[buchel_k@lxdev08 ~]$ 
 ```
 
-Maybe your use case wants that everyone who can log into the machine can automatically view the physical desktop (e.g. GAC user on machine console):
-
-```yaml
-xrdp::shared_physical_desktop::owner_only: false
-```
+To kill a session of another user you need to be root.