Session Host Service
The Session Host (started as a backend with webstream.exe -backend) is the private application server — the unit of compute that scales with concurrent sessions. It manages a pool of Windows RDP sessions, launches a Streamer inside each one, and registers itself with the Gateway so traffic can be routed to it.
Function
- Session pool management. Provisions and recycles Windows pool accounts (e.g.
webs01, webs02), creating an RDP session per user connection and tearing it down — with profile cleanup and NTFS ACL enforcement — when the session ends.
- Streamer launch. Each RDP session runs its own
webstream.exe streamer instance, launched at session logon; the Session Manager hands it its session UUID and command line over the /control WebSocket protocol.
- Connection brokering. Answers
/getConnection (proxied from the gateway) by allocating a pool session and returning the streamer's port so the browser's WebSockets can be proxied through.
- Gateway registration. Registers on startup, heartbeats every 10 seconds with live capacity and load figures, and unregisters on shutdown.
- Static content. Serves the
httpdocs web client over plain HTTP on the private network (the gateway terminates SSL).
Ports and endpoints
| Listener | Port | Purpose |
|---|
| HTTP | gateway.backend.advertisedUrl port (default 9005) | Health checks, /getConnection, static web client. Port 9005 avoids conflicts: Gateway = 9000, Streamers = 9010/9020/… |
In standalone Session Manager mode (-sm, without a gateway) the service also opens a /control WebSocket on basePortNumber (9000) and HTTP on 9001. Production deployments use -backend, where the gateway proxies WebSockets directly to streamers instead.
Message contracts
Outbound — to the Gateway
| Endpoint | Method | Frequency | Payload |
|---|
/gateway/register | POST | Startup (after a local /health self-check; retried every 30 s, up to 10 times) | { serverUrl, maxSessions, instanceType, ec2InstanceId, tags[], capabilities[], version } |
/gateway/heartbeat | POST | Every 10 s (config heartbeatInterval) | { serverUrl, status, activeSessions, maxSessions, instanceType, tags[], cpuUsage, memoryUsage, timestamp } |
/gateway/unregister | POST | Shutdown | { serverUrl } |
Inbound — from the Gateway
| Endpoint | Method | Frequency | Purpose / payload |
|---|
/health | GET | Every 1–10 s (gateway health monitor) | Returns { status, timestamp, sessions: { total, active, available }, uptime }. |
/getConnection | GET | Per workspace launch / reconnect | Requires X-Session-ID; optional ?width=&height=. Allocates a pool session and returns the streamer connection details. Workspace context arrives in the injected X-Workspace-*, X-App-*, and X-Policy-JSON headers. |
| Static paths | GET | Per page load | Web client assets from serverHttpPath. |
Local — Session Manager ↔ Streamer (WebSocket text protocol)
| Message | Direction | When |
|---|
REQUEST_SESSION_INFO:{username} | Streamer → Session Manager | Streamer startup inside a new RDP session. |
SESSION_INFO:{sessionUuid}|{commandLineParams} | Session Manager → Streamer | Reply carrying the session identity and launch parameters. |
FILE_UPLOAD_COMPLETE:{dialogGuid}|{filePath} | Session Manager → Streamer | Notifies a waiting headless file dialog that an upload has landed. |
Configuration
| Property | Purpose |
|---|
gateway.backend.gatewayUrl | The gateway to register with (HTTPS; the gateway terminates SSL). |
gateway.backend.advertisedUrl | This host's own URL as the gateway should reach it (HTTP, private network, default port 9005). |
gateway.backend.heartbeatInterval | Heartbeat period in seconds (default 10). |
gateway.backend.maxSessions | Session capacity advertised to the gateway's load balancer. |
webstreamSettings.serverMaxSessionCount | Size of the local RDP session pool. |
webstreamSettings.serverSessionUsername / serverSessionPwd | Base pool account credentials (accounts webs01… derive from these). |
webstreamSettings.basePortNumber | Base for the per-session streamer port formula (base + userNumber × 10). |
webstreamSettings.serverHttpPath | Root of the static web client (httpdocs). |
-tags gpu,autocad (command line) | Capability tags advertised at registration, used for tag-aware workspace placement. |
filesystemRestrictions, profileCleanup | Session hygiene applied at pool-account recycle: NTFS DENY ACLs, registry restore, profile purge. |
Aligned settings on peer services
- The gateway's
healthCheck.timeout (≥ 6 s recommended) and failureThreshold (≥ 3) must tolerate this host answering probes slowly during heavy login provisioning, or it will be flapped to Unreachable and workspace launches will fail.
- Streamers on this host read the same
gateway.backend.gatewayUrl for their 15-second licence check-ins.
metrics and activityLogging sections on this host determine what its streamers report to the Metrics Engine.