Merge pull request #23 from microsoft/paullizer-host-settings-management

Make Linux host settings configurable from the portal

Author: paullizer

README.md

@@ -19,14 +19,15 @@ The solution consists of the following components:
 
 - **Linux Hosts Cluster**: A set of Linux VMs that users connect to. Each Linux host has managed identity enabled and runs a Session Release Agent.
 
-- **Session Release Agent**: A host-side reconciliation service that keeps the one-minute poll as a safety net, uses XRDP/Xorg session inspection as the source of truth, and can wake early from `systemd-logind` signals to shorten disconnect detection time. It still enforces the same 20-minute reconnect window before final logoff and cleanup.
+- **Session Release Agent**: A host-side reconciliation service that keeps the periodic poll as a safety net, uses XRDP/Xorg session inspection as the source of truth, and can wake early from `systemd-logind` signals to shorten disconnect detection time. It enforces the configured reconnect window before final logoff and cleanup, and also fetches the fleet-wide host settings profile on each run.
 
 - **Broker API**: A RESTful API running on Azure App Service that handles interactions between the Broker Agent, Session Release Agent, and the Broker Database. It uses managed identities and Azure Key Vault for secure access to resources.
 
 - **Broker Database**: An Azure SQL Database that stores information about virtual machines, scaling rules, and scaling activity. It includes the following tables:
   - `virtual_machines`: Stores information about Linux VMs, including hostname, IP address, power state, network status, VM status, connected username, AVD host, and VM ID.
   - `vm_scaling_rules`: Stores scaling rules for the Linux host cluster.
   - `vm_scaling_activity`: Logs scaling activities such as VMs being turned on or off.
+  - `LinuxHostSettings`: Stores the fleet-wide Linux host settings profile that administrators manage from the portal.
 
 - **Azure Function for Scaling Tasks**: An Azure Function that runs on a schedule to manage scaling of Linux hosts based on the scaling rules. It updates VM network statuses, turns VMs on or off, and performs health checks on the Linux hosts.
 
@@ -65,9 +66,9 @@ The architecture ensures secure, efficient, and scalable management of Linux hos
    - The user is added to appropriate user groups on the Linux host for RDP or xpra access.
 4. **User Connects to Linux Host**: The user is connected to the Linux host via RDP or xpra and can work as needed.
 5. **Session Management**:
-   - If the user disconnects or logs off, the Session Release Agent on the Linux host reconciles the XRDP/Xorg session state immediately when possible and otherwise on the next one-minute safety-net poll.
-   - A 20-minute timer is initiated to allow the user to reconnect.
-   - If the user reconnects within 20 minutes, they resume their session.
+   - If the user disconnects or logs off, the Session Release Agent on the Linux host reconciles the XRDP/Xorg session state immediately when possible and otherwise on the next safety-net poll.
+   - A reconnect timer is initiated, 20 minutes by default and configurable from the portal.
+   - If the user reconnects within that window, they resume their session.
    - If not, the user's account is removed from the Linux host, and the VM is made available for other users.
 
 ## Admin Workflow
@@ -79,7 +80,10 @@ The architecture ensures secure, efficient, and scalable management of Linux hos
    - **Update VM Attributes**: Modify VM statuses (e.g., set to maintenance).
 3. **Manage Scaling Rules**:
    - **Create/Update/Delete Scaling Rules**: Adjust scaling rules to control the minimum and maximum number of VMs, scale-up/down ratios, and increments.
-4. **Monitor System**:
+4. **Manage Linux Host Settings**:
+   - **Edit the fleet-wide profile**: Change the reconnect grace period, reconcile interval, watcher timings, idle session timeout, and screen lock policy without editing or redeploying any script.   - **Apply Now**: Optionally push the profile to hosts immediately instead of waiting for them to pick it up.
+   - **Review drift**: See which hosts have applied the current settings version.
+5. **Monitor System**:
    - **View VM Details**: Access detailed information about VMs.
    - **View Scaling Activity Logs**: Monitor scaling activities and history.
    - **View VM History**: Track the usage and status changes of VMs.
@@ -90,14 +94,14 @@ The solution uses Role-Based Access Control (RBAC) to secure access:
 
 - **Management Portal Admins**:
   - **Roles**: `User` and `FullAccess` on the Broker API.
-  - **Permissions**: Access to the management portal and ability to manage VMs and scaling rules.
+  - **Permissions**: Access to the management portal and ability to manage VMs, scaling rules, and Linux host settings.
 - **Broker Agent (AVD Hosts)**:
   - **Role**: `AVDHost` on the Broker API.
   - **Permissions**: Access to the `checkout` API endpoint.
   - **Requirements**: Must be using managed identity and be a member of the `LinuxBroker-AVDHost-VMs` security group.
 - **Session Release Agent (Linux Hosts)**:
   - **Role**: `LinuxHost` on the Broker API.
-  - **Permissions**: Access to release VMs and update statuses.
+  - **Permissions**: Access to release VMs, update statuses, read the host settings profile, and acknowledge the settings version applied.
   - **Requirements**: Managed identity and membership in `LinuxBroker-LinuxHost-VMs` security group.
 - **Azure Function (Scaling Tasks)**:
   - **Role**: `ScheduledTask` on the Broker API.
@@ -137,7 +141,8 @@ These scripts:
 
 - **Install XRDP and xpra**: Set up XRDP for full desktop access (RDP) and xpra for application virtualization, enabling users to connect via AVD.
 - **Configure Authentication**: Sets up authentication mechanisms for secure user access.
-- **Deploy the Linux Session Release Agent**: Installs the minute-based reconciliation service plus a `systemd-logind` watcher that can trigger early reconciliations. The minute timer remains the fallback path so the system still converges even if event delivery is delayed or unavailable.
+- **Deploy the Linux Session Release Agent**: Installs the timer-based reconciliation service plus a `systemd-logind` watcher that can trigger early reconciliations. The timer remains the fallback path so the system still converges even if event delivery is delayed or unavailable.
+- **Install the Host Settings Agent**: Installs `apply-host-settings.sh` and seeds the settings profile, so screen lock policy and session timings are applied consistently on every supported distribution rather than only on RHEL 8. `LINUXBROKER_DISABLE_SCREEN_LOCK` still chooses the screen lock posture that is seeded; from then on the values are managed from the portal.
 
 ## Additional Details
 
@@ -152,9 +157,43 @@ These scripts:
 
 ### Session Release Mechanism
 
-- **Session Monitoring**: The Session Release Agent reconciles XRDP/Xorg session state on a one-minute timer and can also wake early from `systemd-logind` session signals.
-- **Release State**: When a session is disconnected, the VM enters a 'released' state, allowing the user to reconnect within 20 minutes.
-- **Session Termination**: If the user does not reconnect within the 20-minute window, their account is removed from the Linux host, and the VM becomes available for other users.
+- **Session Monitoring**: The Session Release Agent reconciles XRDP/Xorg session state on a timer (60 seconds by default) and can also wake early from `systemd-logind` session signals.
+- **Release State**: When a session is disconnected, the VM enters a 'released' state, allowing the user to reconnect within the configured grace period (20 minutes by default).
+- **Session Termination**: If the user does not reconnect within that window, their account is removed from the Linux host, and the VM becomes available for other users.
+- **Idle Sessions**: When an idle timeout is configured, a user who stays connected but inactive is disconnected, which starts the same grace period. They can reconnect and resume; if they do not, the VM is reclaimed. This is disabled by default.
+
+### Linux Host Settings
+
+Administrators manage host behavior from the **Host Settings** page in the Service Management Portal instead of editing scripts. The settings form a single fleet-wide profile stored in `dbo.LinuxHostSettings`.
+
+| Setting | Default | Range | Effect |
+| --- | --- | --- | --- |
+| Reconnect grace period | 1200 s | 60–86400 | How long a disconnected user can reconnect before the VM is reclaimed |
+| Reconcile interval | 60 s | 30–900 | How often each host re-checks session state |
+| Watcher debounce | 10 s | 1–300 | Minimum gap between `logind`-triggered reconciliations |
+| Watcher settle | 2 s | 0–60 | Pause after a `logind` signal before reconciling |
+| Idle timeout | 0 (disabled) | 0, or 300–86400 | Inactivity before a connected user is disconnected |
+| Idle warning lead time | 120 s | 0–900 | On-screen warning before the idle timeout, must be less than the timeout |
+| Remove the lock screen | true | boolean | Disables the Super+L shortcut and the Lock menu entry |
+| Screen lock enabled | false | boolean | Whether the screen locks when the screensaver activates |
+| Screen blank delay | 0 (never) | 0–86400 | Inactivity before the screen blanks |
+| Screen lock delay | 0 (immediate) | 0–86400 | Delay between blanking and locking |
+| Lock screen settings | true | boolean | Applies dconf locks so users cannot override the screen lock values |
+
+The session lifecycle defaults match the values that were previously hardcoded, so adopting this feature changes no behavior until an administrator edits the profile.
+
+The screen lock defaults preserve the posture set by `LINUXBROKER_DISABLE_SCREEN_LOCK`: the lock screen is removed, because a locked GNOME greeter inside an xrdp session frequently cannot be unlocked after a reconnect, which strands the host's lease. That environment variable still chooses the posture seeded at provisioning time; from then on the values are managed from the portal. Set **Screen lock enabled** on and **Remove the lock screen** off to satisfy a STIG or CIS idle-lock control.
+
+#### How settings reach the hosts
+
+Delivery is a hybrid of pull and push, mirroring the timer-plus-watcher design of the release agent itself:
+
+- **Pull (the convergence mechanism)**: each host fetches the profile at the start of every reconcile run using the managed identity it already has, caches it to `/etc/linuxbroker/host-settings.conf`, and reports the version it applied. Hosts that were powered off, unreachable, or created later by scale-up converge on their own with no operator action.
+- **Push (for immediacy)**: **Apply Now** in the portal has the Broker API connect to each reachable host over SSH so a change takes effect at once. A host missed by a push is not left stale; it simply picks the change up on its next reconcile run.
+
+Values are validated at every layer: SQL `CHECK` constraints, API request validation, and a clamp inside the host-side apply script. A settings fetch failure never blocks reconciliation, and idle enforcement is skipped rather than guessed if idle time cannot be read.
+
+Because the profile is versioned, the portal shows which hosts have applied the current version and which are still pending.
 
 ### Security and Authentication