15 Commits

Author SHA256 Message Date
Alphaeus Mote b05837d51f feat(shell): choose which signed-in user a Run As shell opens as [skip ci]
The agent lists who is signed in with each shell state; the console's Run As
menu offers each name, and the agent opens as that user only while they are
signed in. Several users with nobody at the console is no longer a dead end.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 12:04:50 -05:00
Alphaeus Mote 3832790484 Merge branch 'feat/install-repair' [skip ci] 2026-11-18 09:29:49 -05:00
Alphaeus Mote 21e9bad12f feat(groups): script groups, joined and left by what a script reports [skip ci]
- Every script gets built-ins: Set-ExecuteRGroupMembership (member when the
  value is true, above 0, a non-empty collection or yes-like text; pipe results
  in), Add-/Remove-ExecuteRGroupMembership, and executer_group in Bash. They
  need no credentials: the agent takes their lines out of the output and sends
  the answers with the job's final state.
- The server adds or removes the device in that script group, creating it (top
  level, kind Script) the first time a device joins. Each run decides again.
- Only script groups change: a curated group by that name is ignored, so a
  device can never add itself to one. Last answer per group wins; 25 a job.
- Console: Script kind in the group editor, tree and lists (reported devices,
  no hand-listing), editor completions and snippets for the built-ins.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 09:29:48 -05:00
Alphaeus Mote 0b85bd5e8a feat(install): idempotent install scripts that upgrade or repair a failed agent [skip ci]
Every served install script (Windows/WinPE PowerShell 5.1, Linux and macOS
bash) now looks at the device before acting: a healthy, current agent
enrolled with this server is left alone (Already Installed), an older one is
upgraded in place with its enrollment kept, a failed one (service missing,
disabled, stopped or crash-looping, watchdog down, binary missing or broken,
Windows Installer registration or cache gone) is restarted through the
agent's own initialize and, if that does not help, reinstalled (MSI repair
REINSTALL=ALL REINSTALLMODE=vamus, cache restored from the kept package,
uninstall+install with ProgramData and the registry key set aside as a last
resort; Linux/macOS move files in one by one and re-register the unit or
daemon). The bootstrap token is used only when there is no usable credential
or the agent points at another server, never printed, and masked out of
failure messages. One setup at a time, leftovers of interrupted runs cleared.
Each run ends with one outcome line and exits 1 on failure.

The agent's status verb now prints a JSON line with version, server URL,
credential state (valid/missing/unreadable/other-device) and whether a
bootstrap token is pending, which the scripts read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 09:20:40 -05:00
Alphaeus Mote 505e9849eb Merge branch 'feat/log-format' [skip ci] 2026-11-18 09:03:20 -05:00
Alphaeus Mote 0e2056ca6c feat(runs): run again on a status's devices, the checked ones or the failed ones [skip ci]
- Each status tile of a run (Failed, Timed Out, Skipped, ...) has Run Again on
  These: right-click it or use its ⋯.
- Checked rows get Run Again on N beside Download Logs.
- The run page adds Run Again on N Failed (failed and timed out) next to Run Again.
- The same from a script's Executions panel. Each opens Run Script with those
  devices as targets.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 09:03:11 -05:00
Alphaeus Mote 3e994102ed feat(agent): shells and scripts can run as the signed-in user [skip ci]
- Remote Shell gets Run As: Agent Account (default) or Signed-In User. Windows
  starts the shell with the user's own token, environment and profile folder on
  their desktop, headless; Linux and macOS start their login shell through su -l.
- Scripts get Run As Signed-In User. Every engine then runs out of process as the
  user (PowerShell 7 in the agent's built-in host, 5.1, Bash; su on unix), with
  no window, and the user is given that job folder only.
- The user is the console's, else the only one signed in; several and nobody at
  the console is refused rather than guessed.
- The server never sends either to agents older than 1.13.0 (they would ignore it
  and run as the agent's account): such jobs are created failed, the shell is
  refused. Migration for all three providers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 08:59:56 -05:00
Alphaeus Mote 28b2a53c29 feat(logging): one log line format everywhere, repeated warnings bounded [skip ci]
Every text line ExecuteR writes now reads
[2026-11-16T17:53:40.653Z] - [Category] - [LEVEL] - message key=value:
UTC time to the millisecond, a short category (the logging type without its
namespace, or Agent/Server), TRACE..FATAL, the rendered message and the
properties it did not use as key=value (correlation fields kept, enrichment
noise left out). Serilog writes it through LogLineFormatter (console, file
and the live views' message text); LOG_JSON keeps compact JSON. The watchdog
and its MSI/removal runners write the same format, and the Rust screen host
too (a tracing layer), with the agent taking each host line apart and logging
it once at the host's level and category, without a second timestamp.

LogLineParser reads the format back and the old ones still in device files
(services' [yyyy-MM-dd HH:mm:ss.fff LVL] Source: message, the watchdog's
...Z [LVL] message, tracing's default); the watchdog's live view uses it.

A warning, error or fatal that repeats (same level, SourceContext and
template) is written once, then counted for 60 s; the window's end writes one
line with repeated=N window=60s, a quiet window forgets it, at most 1,000 keys
are tracked and disposing writes open counts. The screen host does the same.

The console's log viewer shows the new level names and categories and copies
lines in the file format.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 08:55:11 -05:00
Alphaeus Mote 09818d81c4 feat(console): agent downloads under Storage & Agent Packages, break-glass in the hover, more terminal themes [skip ci]
- The Agent Downloads card (public links, package list) moves from Enrollment
  Tokens to the Storage & Agent Packages tab.
- Built-In Sign-In drops the Break-Glass Account row; the card's hover names it.
- Eleven more terminal themes: Dracula, One Dark, Monokai, Nord, Gruvbox Dark,
  Tokyo Night, Ubuntu, High Contrast, Green Phosphor, Amber, Solarized Light.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 08:07:32 -05:00
Alphaeus Mote 34a46f3c40 feat(shell): terminal themes, text size and longer scrollback [skip ci]
Terminal Settings (per browser, live in every open shell, docked or popped
out): five themes, text size 9-28 px (Ctrl + = / - / 0 and Ctrl + wheel in
the terminal), scrollback 1,000-25,000 lines, 10,000 by default (was
xterm's 1,000).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 16:56:31 -05:00
Alphaeus Mote d5274dfbea test(backend): presigned link expiry tolerates slow runners [skip ci]
CI #181 measured 298 s left on a 300 s link; allow 10 s.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 14:57:02 -05:00
Alphaeus Mote d1f09eec2b feat(screen): H.264 video for Remote View, RemoteFX fallback at 30 fps [skip ci]
The screen goes as H.264 where the device can encode it: Media Foundation,
the GPU's encoder MFT first (async; NVIDIA, Intel, AMD), else Microsoft's
software encoder. The browser decodes with WebCodecs onto a canvas over the
RDP canvas; RDP keeps input, cursor, clipboard and Ctrl+Alt+Del.

- Negotiated in band: the browser asks with destination "screen;video=h264";
  a host with an encoder answers EXRMUX01 and frames stdio (channel 0 RDP,
  channel 1 video). Old hosts and hosts without an encoder (Windows PE,
  Server Core) answer plainly; the relay is unchanged.
- Baseline, no B-frames, low latency, CBR ~0.1 bit/pixel/frame; only changes
  are encoded, plus three refinement frames; at most 4 frames unacknowledged.
- Fallbacks: hardware -> software encoder; no encoder for a size -> STOP and
  RDP bitmaps; browser that cannot decode sends OFF -> RDP bitmaps.
- mfplat/ole32 loaded at run time from System32: static imports unchanged,
  so the exe still starts on Windows PE.
- Default frame rate 15 -> 30 (video and RemoteFX).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 13:56:29 -05:00
Alphaeus Mote cfba9bb51e feat(screen): text clipboard both ways in Remote View control sessions [skip ci]
The screen host now serves RDP's clipboard channel on Windows: a copy on the
device is announced to the operator's browser and a copy in the browser is
placed on the device, plain text only, up to 1 MiB each way. View-only
sessions get no clipboard channel. Device changes are polled (no listener
window); each write uses a message-only window made and destroyed for it,
the one exception to the no-windows rule, now documented.

The web view waits for the component's clipboard set-up before connecting:
it fires "ready" first, and a connection made then asks for no clipboard
channel. Verified both ways live through the stdio bridge and headless
Chrome against this machine's clipboard.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 11:14:23 -05:00
Alphaeus Mote 61da8b704f chore(screen): log the client's offered codecs and the codec picked [skip ci]
The IronRDP web client 0.7 offers RemoteFX only, so that is what every
session encodes with; the log makes that visible when a session is slow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 10:53:04 -05:00
Alphaeus Mote 8de2214c93 feat(webui): right-click menus and copy paths in Files and Registry [skip ci]
Files: right-click a row for its menu (the whole selection when the row is
part of it), with Copy Path(s) and Copy Name; right-click the folder for
Copy Folder Path, New File/Folder, Upload and Refresh; a Copy Folder Path
button sits next to the path.
Registry: Copy Key Path/Name on keys, Copy Name/Data/Value Path on values
(the whole value is fetched when the list only holds its start), and a
Copy Key Path button next to the path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 10:53:03 -05:00
118 changed files with 15913 additions and 538 deletions
+153 -7
View File
@@ -1042,7 +1042,7 @@ ExecuteR-Agent.exe start start the service
ExecuteR-Agent.exe stop stop the service
ExecuteR-Agent.exe initialize install + start
ExecuteR-Agent.exe remove stop + remove the service
ExecuteR-Agent.exe status machine- and human-readable state
ExecuteR-Agent.exe status JSON line (service, version, server, credential) + human-readable
ExecuteR-Agent.exe version unified build version
ExecuteR-Agent.exe run <name|id> start an On Demand script (see "On Demand and the device CLI")
ExecuteR-Agent.exe upload <path> send files up to S3 (see "Device uploads to S3")
@@ -1098,6 +1098,29 @@ back. Closing the window brings it back when the console is showing that
device's shell and ends the session otherwise; reloading or closing the
console tab ends every popped-out shell, since they run on its page.
**Terminal Settings** (the **Tt** button; theme and text size also sit in a
pop-out's toolbar) are remembered per browser and apply to every open shell at
once: a theme (Dark, Classic, PowerShell Blue, Solarized Dark, Dracula, One Dark,
Monokai, Nord, Gruvbox Dark, Tokyo Night, Ubuntu, High Contrast, Green Phosphor,
Amber, Light, Solarized Light), the text
size (9-28 px; in the terminal Ctrl + = / Ctrl + - or Ctrl + mouse wheel, Ctrl + 0
resets) and the scrollback, the output lines kept above the screen (1,000 to
25,000; 10,000 by default). Older lines drop off as new output arrives.
**Run As** picks whose account a new shell runs as: the **Agent Account**
(LocalSystem, root; the default each time) or the **Signed-In User**: the
console's user, else the only user signed in (several users and nobody at the
console is ambiguous, so the shell is refused rather than guessed), or one of
the signed-in users by name. The agent reports who is signed in with every
shell it opens, and with a refused run-as-user open, so the menu lists them;
it refuses a name that is not signed in (on macOS, anyone but the console's
user). Windows
starts the shell with that user's own token (`WTSQueryUserToken`), environment
and profile folder on their desktop, headless: no window appears for them.
Linux and macOS start the user's login shell through `su -l`. The server
refuses it for agents older than 1.13.0, which would ignore it and start the
agent's account instead; the audit entry records which account was asked for.
---
## Agent upgrades and the watchdog
@@ -1472,6 +1495,37 @@ The agent generates its NKey locally (the private seed never leaves the device),
bootstraps over HTTPS, receives a scoped NATS JWT, erases the token, and
connects over WSS. The device appears in the UI within seconds.
**Running the command again is safe.** Every script (Windows, Windows PE,
Linux, macOS) looks at the device before it acts and ends with one outcome
line — `Installed`, `Upgraded`, `Repaired`, `Already Installed` or
`Failed: <reason>` (exit code 1):
| What the device has | What the script does |
|---------------------|----------------------|
| No agent | Installs as above (MSI; the portable ZIP in Windows PE or with `&type=zip`) |
| A healthy agent, as new as the server's package or newer, enrolled with this server | Nothing |
| An older agent | Upgrades in place (the MSI as a major upgrade; Linux/macOS lay the files down again); the enrollment is kept |
| Service missing, disabled, stopped or crash-looping; watchdog not running | Restarts it through the agent's own `initialize` (re-registers the service as Automatic, starts agent and watchdog); if that does not help, installs the package again |
| Agent binary missing or not running; Windows Installer registration or its cached package gone | Installs the package again: the same MSI build as a repair (`REINSTALL=ALL REINSTALLMODE=vamus`, re-caching it; a lost cache is first restored from the MSI the agent keeps under `%ProgramData%\ExecuteR\packages`), another build as an upgrade, every file laid down (`amus`). Only when Windows Installer refuses that does it uninstall and install again, with `%ProgramData%\ExecuteR` and `HKLM\SOFTWARE\ExecuteR` set aside and put back, so the enrollment and settings survive. Linux/macOS move the files in one by one and register the unit / daemon again |
| No usable credential (missing, unreadable, of other hardware), or pointed at another server | Hands the agent this command's bootstrap token and restarts it. A valid enrollment is never replaced, so the device keeps its identity; re-enrolling the same hardware keeps the same device row anyway |
The decision reads `executer-agent status` / `ExecuteR-Agent.exe status`,
whose first line is JSON: service state, version, server URL, credential
(`valid`, `missing`, `unreadable`, `other-device`; an expired credential is
still `valid`, it renews itself) and whether a bootstrap token is pending —
never the token. Health means the service is registered, enabled and still
running a few seconds later, the watchdog runs, the credential is valid and
the server URL matches (case and a trailing slash aside; a Group Policy
`ServerURL` pointing elsewhere is a failure, not something the script
overrides). The script embeds the version the package link serves, so a
current device downloads nothing. Interrupted runs do not break a rerun: one
setup runs at a time (a global mutex on Windows, a lock directory on
Linux/macOS), leftover downloads and half-moved files are cleared, a Windows
Installer operation in progress is waited for, and data set aside by an
interrupted last-resort reinstall is put back first. The token goes only to
`msiexec`'s hidden `BOOTSTRAPTOKEN`, the agent's registry / `agent.json`, or
`configure --token`; it is masked out of failure messages.
![Add device](docs/screenshots/add-device.png)
---
@@ -1778,7 +1832,8 @@ Per-script options in the editor (Details):
| Option | Default | What it does |
|--------|---------|--------------|
| **Run From File** | off | PowerShell 7 stages the script in the job folder and runs it by path (`AddCommand`), not from memory. PowerShell 5 and Bash always run from a file. |
| **Set Working Directory to Script Folder** | off | Starts a staged script in its job folder (the process's directory for 5.1 and Bash; the runspace's location for PowerShell 7, never the shared agent process's). Only with a staged file. Off keeps the engine's usual directory: the agent's own (`C:\Windows\System32` for the service). |
| **Set Working Directory to Script Folder** | off | Starts a staged script in its job folder (the process's directory for 5.1 and Bash; the runspace's location for PowerShell 7, never the shared agent process's). Only with a staged file. Off keeps the engine's usual directory: the agent's own (`C:\Windows\System32` for the service), or the user's profile folder or home with Run As Signed-In User. |
| **Run As Signed-In User** | off | Runs the script as the person signed in on the device (the console's user, else the only one signed in) instead of the agent's account. Every engine runs out of process: PowerShell 7 in the agent's built-in host, 5.1 in `powershell.exe`, Bash in `bash` (through `su` on Linux and macOS), with output and errors but no progress records. Windows uses the user's token, environment (plus the bundled modules) and profile folder, headless, so nothing appears on their screen. The user is given that job folder only (Windows: Modify on it; Linux/macOS: it becomes theirs and the job root traverse-only). Nobody signed in, or several and nobody at the console, fails the job; so does an agent older than 1.13.0, which the server never sends it to. |
| **Clean Up After Run** | on | Deletes the job folder when the run ends. |
| **Restart After Run** | Off | Restarts the device after the run: **Always**, or **When the Script Asks**, with an optional delay (up to 60 minutes) and an optional warning for signed-in users. See [Restart After Run](#restart-after-run). |
@@ -2198,13 +2253,14 @@ way as manual runs.
## Device groups and script triggers
Groups form a **tree**. Each group is one of three kinds:
Groups form a **tree**. Each group is one of four kinds:
| Kind | Members |
|------|---------|
| **Folder** | None of its own — it organizes the groups nested under it |
| **Static** | An explicit list of devices |
| **Dynamic** | The devices matching its rules, evaluated against live device data |
| **Script** | The devices whose scripts last reported they belong ([Script groups](#script-groups)) |
A group's membership **includes every group nested under it**, so running,
scheduling or scoping a role on `Sites` reaches `Sites › Office › Web` too.
@@ -2315,6 +2371,41 @@ Windows PowerShell 5.1 and Bash, the `EXECUTER_TRIGGER_KIND`, `_USER`,
`_SESSION_ID`, `_OCCURRED_UTC` and `_SCHEDULE_ID` environment variables. `Kind`
is `enrollment`, `agent-ready`, `logon` or `device-cli`.
### Script groups
A script decides whether its device belongs in a group, on the device, and the
console follows: every script has the built-ins below (no credentials: the agent
carries the answer with the job's final state), the device joins or leaves the
named group when the job ends, and the group is created (top level, kind Script)
the first time a device joins it. Each run decides again, so a scheduled script
keeps the group current.
```powershell
# Member when the value is $true, above 0, a non-empty collection, or text other than false/0/no/off.
Get-Package -Name 'Java*' -ErrorAction SilentlyContinue | Set-ExecuteRGroupMembership 'Has Java'
Set-ExecuteRGroupMembership -Name 'Low Disk' -Value ((Get-PSDrive C).Free -lt 10GB)
Add-ExecuteRGroupMembership 'Pilot Ring'
Remove-ExecuteRGroupMembership 'Pilot Ring'
```
```bash
executer_group "Has Java" "$(pgrep -c java)" # true/false, a number (above 0) or text; default true
```
- The job's output shows each answer as a line (`Script group “Has Java”: this
device is a member.`); the built-ins' own marker lines never reach the log.
- Names are matched without regard to case; the last answer per group in a job
wins; a job reports on at most 25 groups.
- Only script groups change. A name that belongs to a static, dynamic or folder
group is ignored (logged on the server), so a device can never put itself into
a group an operator curates; a device only ever changes its own membership.
- Script groups can be renamed, moved into folders, targeted, scheduled and
used in role scopes like any group; their members cannot be listed by hand.
Saving one as dynamic or a folder drops its reported devices. Not being a
member of a group that does not exist yet creates nothing.
- Joins, leaves and the group's creation are audited (actor `script:<name>`)
and show in the activity feed.
### At Logon
The agent watches interactive sign-ins and reports each one with the user
@@ -2773,6 +2864,48 @@ cookies and authorization headers. A structured property with one of those names
(`{Password}`, `{Jwt}`, … see `Redaction.NeverLog`) is masked as `[redacted]`
before any sink sees it, live views included.
### Log line format
Every text line any ExecuteR process writes (server, agent, watchdog, MSI and
removal runners, screen host) has one shape:
```text
[2026-11-16T17:53:40.653Z] - [LeafRouter] - [INFO] - The site's leaf answers again; moving back to it from the hub leaf=wss://172.18.16.104:9001
[2026-11-16T17:53:40.687Z] - [EventBus] - [WARN] - The site's leaf could not be reached; the bus goes through the server meanwhile reason="TLS: certificate expired"
[2026-11-16T17:54:40.701Z] - [EventBus] - [WARN] - The site's leaf could not be reached; the bus goes through the server meanwhile reason="TLS: certificate expired" repeated=37 window=60s
```
- **Time**: UTC, ISO 8601, milliseconds, `Z`.
- **Category**: a short component name: the logging type without its namespace
or generic arguments (`Agent.Screen.ScreenSessions` → `ScreenSessions`, a
nested `Outer+Inner` → `Outer.Inner`); `Agent` or `Server` for a line with no
type; `Watchdog`, `MsiRunner`, `RemovalRunner` for the watchdog's;
`ScreenHost` (or a dependency's crate, `ironrdp_server`) for the screen host's.
- **Level**: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`.
- **Message**: rendered with strings bare, then every property the message did
not use as ` key=value` (correlation fields such as `CorrelationId`,
`ClientId`, `JobId` included; `SourceContext`, `MachineName`, `Application`,
`EventId` and the framework's `RequestId`/`ConnectionId`/`ActionId` left out).
A value with whitespace, `=` or `"` is double-quoted with `\"` escaped; a
missing value is `null`. An exception follows on the next lines.
`LOG_JSON=1` writes compact JSON instead, unchanged. The live views carry the
same message text. Log files from earlier versions
(`[2026-11-06 12:00:00.000 INF] Source: message`, the watchdog's
`2026-11-06 12:00:00.000Z [INF] message`) are still read by the watchdog's live
view (`LogLineParser`).
**Repeats are bounded.** A warning, error or fatal is the same as another when
its level, category (full SourceContext) and message template match. The first
is written at once; the same one again within 60 s is only counted, and when the
window ends with any counted, one line is written: the last of them with
`repeated=N window=60s`. While it keeps repeating that summary comes once a
minute; a minute without it forgets it, so the next one is written at once. At
most 1,000 distinct events are tracked (the oldest goes first, with its count
written), and stopping the process writes every count still open. Information
and below are never held back. The screen host does the same for its own
warnings and errors.
### Live logs and log files in the console
Every process keeps its last 2,000 log lines in memory (a Serilog sink feeding a
@@ -3309,7 +3442,8 @@ newer agent.* Upgrade the agent.
keyboard and mouse (**Control**) or without (**View Only**). It works at the
sign-in, lock and UAC screens, when nobody is signed in, and in Windows PE.
**How it works.** The pixels and input are RDP. The console runs Devolutions'
**How it works.** Input, cursor and clipboard are RDP; the picture is H.264
video where the device can encode it (below), RDP bitmaps otherwise. The console runs Devolutions'
IronRDP web client (`@devolutions/iron-remote-desktop` with the
`@devolutions/iron-remote-desktop-rdp` WASM backend, loaded only on this page),
which connects over a WebSocket using RDCleanPath. On the device the agent
@@ -3393,9 +3527,21 @@ agent), a device without the screen host or where capture fails shows why.
changed."); reconnect to follow it.
- When the host can't open the input desktop, the console shows **Secure Screen**
and keeps the session open.
- No clipboard in this version.
- **Windows PE**: the portable package carries the screen host; it starts in the
agent's session on the interactive desktop.
- **Clipboard** (Windows, control sessions): copy text on either side and paste on
the other, up to 1 MiB; no files or images. The browser asks once for clipboard
access (Chromium; HTTPS only). View-only sessions have no clipboard.
- **Windows PE**: the portable package carries the screen host; the agent's service
starts it in the console session, like on full Windows.
- **Video.** On Windows with Media Foundation the screen goes as **H.264**: the
GPU's encoder when there is one (NVIDIA, Intel, AMD), else Microsoft's software
encoder; the browser decodes it with WebCodecs (in hardware where it can). The
toolbar shows **H.264** or **H.264 GPU** (hover for the encoder). Only changes
are sent, at up to 30 fps and about 0.1 bit per pixel per frame (about 6 Mbit/s
at most for a busy 1080p screen, next to nothing for a still one). It travels in
the same socket, so nothing else is opened. Windows PE and Server Core have no
encoder, browsers without WebCodecs (or over plain HTTP) can't decode it, and
older agents don't offer it: those sessions use RDP bitmaps (RemoteFX) at up to
30 fps, as does any session whose encoder or decoder fails.
**Security.**
@@ -59,7 +59,7 @@ public static class RemovalHost
DataDirectory = Path.GetFullPath(data),
SelfPath = null,
};
var log = new WatchdogLog(runnerDirectory, console: false, name: RemovalRunner.LogFileName);
var log = new WatchdogLog(runnerDirectory, console: false, name: RemovalRunner.LogFileName, category: "RemovalRunner");
var agentPath = Path.Combine(options.InstallDirectory, options.AgentExecutable);
IAgentService agent;
+1 -1
View File
@@ -192,7 +192,7 @@ public static class WatchdogCli
{
var (options, _) = ParseOptions(args);
options = options with { SelfPath = null };
var log = new WatchdogLog(options.LogDirectory, console: false, name: "ExecuteR-Watchdog-msi");
var log = new WatchdogLog(options.LogDirectory, console: false, name: "ExecuteR-Watchdog-msi", category: "MsiRunner");
var agent = new WindowsAgentService(Branding.AgentServiceName, Path.Combine(options.InstallDirectory, options.AgentExecutable), log);
var watchdog = new WindowsAgentService(Branding.WatchdogServiceName,
Path.Combine(options.InstallDirectory, Branding.WatchdogExecutableName), log);
+19 -6
View File
@@ -6,22 +6,31 @@ namespace Agent.Watchdog;
/// The watchdog's own log: one small rolling file in the agent's log folder
/// (<c>ExecuteR-Watchdog.log</c>, rolled at 1 MB, three files kept), the
/// console in the foreground, and the lines of the current upgrade run kept in
/// memory so a failure's outcome can carry them.
/// memory so a failure's outcome can carry them. Lines are ExecuteR's one log
/// format (as <c>Shared.Infrastructure.Logging.LogLineFormatter</c> writes it,
/// without Serilog, which the watchdog does not carry):
/// <c>[2026-11-16T17:53:40.653Z] - [Watchdog] - [INFO] - message</c>.
/// </summary>
public sealed class WatchdogLog
{
public const long RollBytes = 1024 * 1024;
public const int KeptFiles = 3;
/// <summary>The category of the watchdog's own lines.</summary>
public const string DefaultCategory = "Watchdog";
private readonly Lock gate = new();
private readonly string? path;
private readonly bool console;
private readonly string category;
private readonly List<string> run = [];
private bool fileBroken;
public WatchdogLog(string? directory, bool console, string? name = null)
/// <param name="category">The component each line names (<c>Watchdog</c>, <c>MsiRunner</c>, <c>RemovalRunner</c>).</param>
public WatchdogLog(string? directory, bool console, string? name = null, string category = DefaultCategory)
{
this.console = console;
this.category = category;
if (!string.IsNullOrWhiteSpace(directory))
{
name ??= Path.GetFileNameWithoutExtension(Environment.ProcessPath) is { Length: > 0 } exe
@@ -35,11 +44,11 @@ public sealed class WatchdogLog
/// <summary>Every line written, for tests and the foreground.</summary>
public event Action<string>? Written;
public void Info(string message) => Write("INF", message);
public void Info(string message) => Write("INFO", message);
public void Warn(string message, Exception? exception = null) => Write("WRN", With(message, exception));
public void Warn(string message, Exception? exception = null) => Write("WARN", With(message, exception));
public void Error(string message, Exception? exception = null) => Write("ERR", With(message, exception));
public void Error(string message, Exception? exception = null) => Write("ERROR", With(message, exception));
/// <summary>Starts collecting the lines of an upgrade run.</summary>
public void BeginRun()
@@ -59,12 +68,16 @@ public sealed class WatchdogLog
}
}
/// <summary>One line: <c>[2026-11-16T17:53:40.653Z] - [Watchdog] - [INFO] - message</c>.</summary>
public static string Format(DateTimeOffset time, string category, string level, string message)
=> $"[{time.UtcDateTime.ToString("yyyy-MM-dd'T'HH:mm:ss.fff'Z'", CultureInfo.InvariantCulture)}] - [{category}] - [{level}] - {message}";
private static string With(string message, Exception? exception)
=> exception is null ? message : $"{message}: {exception.GetBaseException().Message}";
private void Write(string level, string message)
{
var line = $"{DateTimeOffset.UtcNow.ToString("yyyy-MM-dd HH:mm:ss.fff'Z'", CultureInfo.InvariantCulture)} [{level}] {message}";
var line = Format(DateTimeOffset.UtcNow, category, level, message);
lock (gate)
{
run.Add(line);
+31 -3
View File
@@ -94,7 +94,7 @@ public static class AgentCli
}
case "status":
return Lifecycle.Status();
return Status();
// Cross-platform enrollment configuration (registry on Windows,
// /etc/executer/agent.json elsewhere) — what the MSI does via
@@ -151,12 +151,20 @@ public static class AgentCli
public static int Remove() => ServiceLifecycle.Remove();
public static int Start() => ServiceLifecycle.Start();
public static int Stop() => ServiceLifecycle.Stop();
public static int Status() => ServiceLifecycle.Status();
public static (bool Installed, string State, string? StartType) Query() => ServiceLifecycle.Query();
public static string ServiceName => Branding.AgentServiceName;
/// <summary>Nothing after the human-readable lines on Windows.</summary>
public static int Status() => 0;
#else
public static int Install() => UnixServiceLifecycle.Install();
public static int Remove() => UnixServiceLifecycle.Remove();
public static int Start() => UnixServiceLifecycle.Start();
public static int Stop() => UnixServiceLifecycle.Stop();
public static (bool Installed, string State, string? StartType) Query() => UnixServiceLifecycle.Query();
public static string ServiceName => OperatingSystem.IsMacOS() ? Branding.AgentLaunchdLabel : Branding.AgentSystemdUnit;
/// <summary>systemctl status / launchctl print after the human-readable lines.</summary>
public static int Status() => UnixServiceLifecycle.Status();
#endif
}
@@ -187,6 +195,26 @@ public static class AgentCli
return exitCode;
}
/// <summary>
/// One JSON line first (service, state, version, server, credential: what the
/// install scripts read to decide between leave alone, repair and re-enroll),
/// the human-readable lines after it. Always 0: the report is the answer.
/// </summary>
private static int Status()
{
var (installed, state, startType) = Lifecycle.Query();
var report = AgentHealth.ReadLocal();
Console.WriteLine(AgentHealth.Json(Lifecycle.ServiceName, installed, state, startType, report));
Console.WriteLine($"Service '{Branding.AgentServiceDisplayName}': {state}{(startType is null ? "" : $" ({startType})")}");
foreach (var line in AgentHealth.Describe(report))
{
Console.WriteLine(line);
}
Lifecycle.Status();
return 0;
}
private static int Configure(string[] args)
{
string? url = null;
@@ -274,7 +302,7 @@ public static class AgentCli
Console.WriteLine(" start Start the installed service");
Console.WriteLine(" stop Stop the service (the watchdog never undoes a stop)");
Console.WriteLine(" initialize install + start (agent and watchdog)");
Console.WriteLine(" status Show service and enrollment state");
Console.WriteLine(" status Show service, version, server and enrollment state (JSON line first)");
Console.WriteLine(" version Print the build version");
Console.WriteLine(" run <name|id> [-p Name=Value]... [--wait] [--timeout <s>]");
Console.WriteLine(" Start an On Demand script (run --list shows them, run --help for more)");
+156
View File
@@ -0,0 +1,156 @@
using System.Text.Encodings.Web;
using System.Text.Json;
using Agent.Configuration;
using Agent.Enrollment;
using Agent.Identity;
using Agent.Platform;
using Microsoft.Extensions.Logging.Abstractions;
using Shared.Infrastructure.Constants;
using Shared.Infrastructure.Versioning;
namespace Agent.Commands;
/// <summary>
/// What <c>status</c> reports beyond the service state: the version, the server the
/// agent is pointed at and whether its enrollment credential is usable. The install
/// scripts read it to choose between leaving a device alone, repairing it and
/// re-enrolling it with their bootstrap token. Never the token itself.
/// </summary>
public static class AgentHealth
{
/// <summary>The credential loads and belongs to this hardware (an expired one renews itself).</summary>
public const string CredentialValid = "valid";
/// <summary>No credential file: never enrolled, or purged.</summary>
public const string CredentialMissing = "missing";
/// <summary>A credential file that does not decrypt or parse.</summary>
public const string CredentialUnreadable = "unreadable";
/// <summary>A credential of another client id: the hardware changed; the agent re-enrolls as a new device.</summary>
public const string CredentialOtherDevice = "other-device";
public sealed record Report(
string Version,
string? ServerUrl,
string Credential,
string? EnrollmentId,
DateTimeOffset? CredentialExpiresUtc,
bool BootstrapTokenPending);
/// <summary>
/// The report from configuration (Group Policy first, as the agent reads it), the
/// credential store and the client id this hardware computes (null when it cannot
/// be read: the credential is then judged without it).
/// </summary>
public static Report Read(
AgentConfiguration configuration, ICredentialStore credentials, bool credentialFileExists, Func<string?> clientId, string version)
{
string credential;
AgentCredentials? stored = null;
if (!credentialFileExists)
{
credential = CredentialMissing;
}
else if ((stored = credentials.Load()) is null)
{
credential = CredentialUnreadable;
}
else if (clientId() is { } current && !string.Equals(current, stored.ClientId, StringComparison.Ordinal))
{
credential = CredentialOtherDevice;
}
else
{
credential = CredentialValid;
}
return new Report(
version,
string.IsNullOrWhiteSpace(configuration.ServerUrlText.Value) ? null : configuration.ServerUrlText.Value.Trim(),
credential,
stored?.EnrollmentId.ToString("D"),
stored?.ExpiresUtc,
configuration.HasBootstrapToken);
}
/// <summary>The report of this machine's installed agent.</summary>
public static Report ReadLocal()
{
var registry = PlatformServices.CreateRegistryStore();
var configuration = new AgentConfigurationLoader(registry, allowEnvironment: false).Load();
var store = new CredentialStore(NullLogger<CredentialStore>.Instance);
var file = Path.Combine(Branding.AgentProgramDataDirectory, Branding.CredentialFileName);
return Read(configuration, store, File.Exists(file), LocalClientId, BuildVersion.Resolve(typeof(AgentHealth).Assembly));
}
private static string? LocalClientId()
{
try
{
return ClientIdentityFactory.ComputeClientId(PlatformServices.CreateIdentitySource().Read());
}
catch (Exception)
{
// No hardware identity here (WinPE without WMI): judge the credential on its own.
return null;
}
}
/// <summary>
/// The machine-readable line <c>status</c> prints first: one JSON object, URLs
/// unescaped so a shell script can read fields with sed.
/// </summary>
public static string Json(string service, bool installed, string state, string? startType, Report report)
{
using var buffer = new MemoryStream();
using (var writer = new Utf8JsonWriter(buffer, new JsonWriterOptions { Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping }))
{
writer.WriteStartObject();
writer.WriteString("service", service);
writer.WriteBoolean("installed", installed);
writer.WriteString("state", state);
if (startType is not null)
{
writer.WriteString("startType", startType);
}
writer.WriteString("version", report.Version);
writer.WriteString("serverUrl", report.ServerUrl);
writer.WriteString("credential", report.Credential);
writer.WriteString("enrollmentId", report.EnrollmentId);
if (report.CredentialExpiresUtc is { } expires)
{
writer.WriteString("credentialExpiresUtc", expires.ToUniversalTime().ToString("O"));
}
else
{
writer.WriteNull("credentialExpiresUtc");
}
writer.WriteBoolean("bootstrapTokenPending", report.BootstrapTokenPending);
writer.WriteEndObject();
}
return System.Text.Encoding.UTF8.GetString(buffer.ToArray());
}
/// <summary>The human-readable lines after the JSON one.</summary>
public static IEnumerable<string> Describe(Report report)
{
yield return $"Version: {report.Version}";
yield return $"Server: {report.ServerUrl ?? "(not configured)"}";
yield return report.Credential switch
{
CredentialValid => $"Enrollment: {report.EnrollmentId ?? "enrolled"}",
CredentialMissing => "Enrollment: none",
CredentialUnreadable => "Enrollment: credential unreadable",
CredentialOtherDevice => "Enrollment: credential of another device",
_ => $"Enrollment: {report.Credential}",
};
if (report.BootstrapTokenPending)
{
yield return "Bootstrap token: present (enrollment pending)";
}
}
}
+11 -26
View File
@@ -1,6 +1,4 @@
using System.Globalization;
using System.Text;
using System.Text.RegularExpressions;
using Shared.Contracts.Api;
using Shared.Infrastructure.Logging;
@@ -12,7 +10,7 @@ namespace Agent.Logs;
/// got shorter, or a different file, was rolled: it is read from its start. Only whole
/// lines are taken; a line still being written waits for the next poll.
/// </summary>
public sealed partial class LogFileFollower(Func<string?> locate)
public sealed class LogFileFollower(Func<string?> locate)
{
/// <summary>How much of the end of the file the first poll reads.</summary>
public const int Backlog = 64 * 1024;
@@ -96,33 +94,20 @@ public sealed partial class LogFileFollower(Func<string?> locate)
}
}
/// <summary><c>2026-11-06 12:00:00.000Z [INF] message</c>, as <c>WatchdogLog</c> writes it.</summary>
/// <summary>
/// <c>[2026-11-06T12:00:00.000Z] - [Watchdog] - [INFO] - message</c>, as <c>WatchdogLog</c>
/// writes it, or a line from before that format (see <see cref="LogLineParser"/>).
/// Anything else (an exception's stack) is a line of its own, as information.
/// </summary>
private void Add(string line)
{
var match = LinePattern().Match(line);
if (!match.Success)
if (LogLineParser.TryParse(line, out var parsed))
{
Live.Append(parsed.TimestampUtc, parsed.Level, parsed.Category, parsed.Message);
}
else
{
Live.Append(DateTimeOffset.UtcNow, LogLevels.Information, null, line);
return;
}
var time = DateTimeOffset.TryParseExact(
match.Groups["time"].Value, "yyyy-MM-dd HH:mm:ss.fff", CultureInfo.InvariantCulture,
DateTimeStyles.AssumeUniversal | DateTimeStyles.AdjustToUniversal, out var parsed)
? parsed
: DateTimeOffset.UtcNow;
var level = match.Groups["level"].Value switch
{
"VRB" => LogLevels.Verbose,
"DBG" => LogLevels.Debug,
"WRN" => LogLevels.Warning,
"ERR" => LogLevels.Error,
"FTL" => LogLevels.Fatal,
_ => LogLevels.Information,
};
Live.Append(time, level, null, match.Groups["message"].Value);
}
[GeneratedRegex(@"^(?<time>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3})Z \[(?<level>[A-Z]{3})\] (?<message>.*)$")]
private static partial Regex LinePattern();
}
+194
View File
@@ -0,0 +1,194 @@
#if WINDOWS_AGENT
using System.ComponentModel;
using System.Runtime.InteropServices;
using System.Security.Principal;
using System.Text;
using Agent.Sessions;
namespace Agent.Platform;
/// <summary>
/// The signed-in user's primary token (<c>WTSQueryUserToken</c>, which only LocalSystem may
/// call), and what a process started with it gets: the user's own environment block and
/// profile folder, as Explorer would give it.
/// </summary>
internal sealed partial class WindowsUserToken : IDisposable
{
private const int ErrorPrivilegeNotHeld = 1314;
private WindowsUserToken(IntPtr handle, string name)
{
Handle = handle;
Name = name;
}
public IntPtr Handle { get; private set; }
/// <summary>DOMAIN\user, as the session reports it.</summary>
public string Name { get; }
/// <summary>The user's SID (for granting it a job folder).</summary>
public SecurityIdentifier? Sid
{
get
{
using var identity = new WindowsIdentity(Handle);
return identity.User;
}
}
public static WindowsUserToken Open(SignedInUser user)
{
if (user.WindowsSession is not { } session)
{
throw new InvalidOperationException($"{user.Name} has no session to run in.");
}
if (!WTSQueryUserToken((uint)session, out var token))
{
var error = Marshal.GetLastWin32Error();
throw new Win32Exception(error, error == ErrorPrivilegeNotHeld
? "Only an agent running as LocalSystem can start processes as the signed-in user."
: $"The token of {user.Name} could not be obtained.");
}
return new WindowsUserToken(token, user.Name);
}
/// <summary>The user's profile folder (C:\Users\name), or null when it cannot be read.</summary>
public string? ProfileDirectory()
{
uint size = 0;
GetUserProfileDirectoryW(Handle, null, ref size);
if (size == 0)
{
return null;
}
var buffer = new StringBuilder((int)size);
return GetUserProfileDirectoryW(Handle, buffer, ref size) ? buffer.ToString() : null;
}
/// <summary>
/// The user's environment (not the agent's) with <paramref name="overrides"/> applied and
/// <paramref name="modulePath"/> (the agent's bundled modules) added to PSModulePath, as a
/// CreateProcess block (CREATE_UNICODE_ENVIRONMENT). Free it with <see cref="Marshal.FreeHGlobal"/>.
/// </summary>
public IntPtr EnvironmentBlock(IReadOnlyDictionary<string, string>? overrides, string? modulePath = null)
{
var variables = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
if (CreateEnvironmentBlock(out var block, Handle, false))
{
try
{
foreach (var (name, value) in ReadBlock(block))
{
variables[name] = value;
}
}
finally
{
DestroyEnvironmentBlock(block);
}
}
foreach (var (name, value) in overrides ?? new Dictionary<string, string>())
{
// Keep the caller's spelling (bash under Git Bash is case-sensitive).
variables.Remove(name);
variables[name] = value;
}
if (modulePath is not null)
{
variables["PSModulePath"] = AppendPath(variables.GetValueOrDefault("PSModulePath"), modulePath);
}
return Marshal.StringToHGlobalUni(BuildBlock(variables));
}
/// <summary><paramref name="list"/> (a ;-separated path list) with <paramref name="path"/> at the end, once.</summary>
internal static string AppendPath(string? list, string path)
{
var parts = (list ?? string.Empty).Split(';', StringSplitOptions.RemoveEmptyEntries).ToList();
if (!parts.Contains(path, StringComparer.OrdinalIgnoreCase))
{
parts.Add(path);
}
return string.Join(';', parts);
}
/// <summary>The name=value pairs of a native environment block (UTF-16, double-NUL terminated).</summary>
internal static IEnumerable<KeyValuePair<string, string>> ReadBlock(IntPtr block)
{
var entries = new List<KeyValuePair<string, string>>();
var cursor = block;
while (true)
{
var entry = Marshal.PtrToStringUni(cursor);
if (string.IsNullOrEmpty(entry))
{
break;
}
// Names may start with '=' (per-drive folders): the separator is the next '='.
var equals = entry.IndexOf('=', 1);
if (equals > 0)
{
entries.Add(new(entry[..equals], entry[(equals + 1)..]));
}
cursor += (entry.Length + 1) * sizeof(char);
}
return entries;
}
/// <summary>A block CreateProcess accepts: sorted by name (case-insensitive), each "name=value\0", then a final "\0".</summary>
internal static string BuildBlock(IEnumerable<KeyValuePair<string, string>> variables)
{
var builder = new StringBuilder();
foreach (var (name, value) in variables.OrderBy(v => v.Key, StringComparer.OrdinalIgnoreCase))
{
builder.Append(name).Append('=').Append(value).Append('\0');
}
if (builder.Length == 0)
{
builder.Append('\0');
}
return builder.Append('\0').ToString();
}
public void Dispose()
{
if (Handle != IntPtr.Zero)
{
CloseHandle(Handle);
Handle = IntPtr.Zero;
}
}
[LibraryImport("wtsapi32.dll", SetLastError = true)]
[return: MarshalAs(UnmanagedType.Bool)]
private static partial bool WTSQueryUserToken(uint sessionId, out IntPtr token);
[LibraryImport("userenv.dll", SetLastError = true)]
[return: MarshalAs(UnmanagedType.Bool)]
private static partial bool CreateEnvironmentBlock(out IntPtr environment, IntPtr token, [MarshalAs(UnmanagedType.Bool)] bool inherit);
[LibraryImport("userenv.dll", SetLastError = true)]
[return: MarshalAs(UnmanagedType.Bool)]
private static partial bool DestroyEnvironmentBlock(IntPtr environment);
[DllImport("userenv.dll", SetLastError = true, CharSet = CharSet.Unicode)]
[return: MarshalAs(UnmanagedType.Bool)]
private static extern bool GetUserProfileDirectoryW(IntPtr token, StringBuilder? profileDirectory, ref uint size);
[LibraryImport("kernel32.dll", SetLastError = true)]
[return: MarshalAs(UnmanagedType.Bool)]
private static partial bool CloseHandle(IntPtr handle);
}
#endif
+132 -18
View File
@@ -63,7 +63,8 @@ public static class ExternalScriptRunner
JobFolder? folder = null,
string scriptName = "script",
bool setWorkingDirectory = false,
JobTrigger? trigger = null)
JobTrigger? trigger = null,
Agent.Sessions.SignedInUser? runAs = null)
{
// Child processes inherit PSModulePath, so 5.1 also sees the bundled
// gallery modules (PSResourceGet supports Windows PowerShell 5.1+).
@@ -71,13 +72,22 @@ public static class ExternalScriptRunner
var owned = folder is null;
folder ??= JobFolder.Create(JobRoot.DefaultPath(), Guid.NewGuid());
var run = new ProcessRun(folder, setWorkingDirectory, runAs);
try
{
return engine == ScriptEngine.WindowsPowerShell
? await RunWindowsPowerShellAsync(
content, prelude, parameters, secrets, secretsVariableName, files, filesRoot, folder, scriptName, setWorkingDirectory, trigger, onRecord, cancellationToken)
: await RunBashAsync(
content, prelude, parameters, secrets, files, filesRoot, folder, scriptName, setWorkingDirectory, trigger, onRecord, cancellationToken);
return engine switch
{
ScriptEngine.Bash => await RunBashAsync(
content, prelude, parameters, secrets, files, filesRoot, folder, scriptName, trigger, run, onRecord, cancellationToken),
// PowerShell 7 as the signed-in user: the agent's own engine in a process of theirs
// (the built-in host), with the same wrapper as 5.1.
ScriptEngine.PowerShell => await RunWindowsPowerShellAsync(
content, prelude, parameters, secrets, secretsVariableName, files, filesRoot, folder, scriptName, trigger, run, onRecord, cancellationToken,
AgentLocation.ExecutablePath, [Agent.Shell.WindowsShellResolver.HostVerb]),
_ => await RunWindowsPowerShellAsync(
content, prelude, parameters, secrets, secretsVariableName, files, filesRoot, folder, scriptName, trigger, run, onRecord, cancellationToken,
WindowsPowerShellPath(runAs is not null), []),
};
}
finally
{
@@ -98,10 +108,12 @@ public static class ExternalScriptRunner
DirectoryInfo? filesRoot,
JobFolder folder,
string scriptName,
bool setWorkingDirectory,
JobTrigger? trigger,
ProcessRun run,
Action<NormalizedOutputRecord> onRecord,
CancellationToken cancellationToken)
CancellationToken cancellationToken,
string interpreter,
IReadOnlyList<string> interpreterArguments)
{
var scriptPath = folder.WriteScript(scriptName, ScriptEngine.WindowsPowerShell, content);
@@ -162,14 +174,19 @@ public static class ExternalScriptRunner
var wrapperPath = folder.WriteHelper(WrapperFileName, wrapper.ToString());
return await RunProcessAsync(
"powershell.exe",
$"-NoProfile -NonInteractive -ExecutionPolicy Bypass -File \"{wrapperPath}\"",
interpreter,
[.. interpreterArguments, "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File", wrapperPath],
WindowsPowerShellEnvironment(folder, trigger),
setWorkingDirectory ? folder.Path : null,
run,
onRecord,
cancellationToken);
}
/// <summary>Windows PowerShell: by name for the agent's own processes; by full path for a user's (CreateProcessAsUser does not search PATH).</summary>
private static string WindowsPowerShellPath(bool fullPath) => fullPath
? Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.System), "WindowsPowerShell", "v1.0", "powershell.exe")
: "powershell.exe";
private static async Task<ExternalResult> RunBashAsync(
string content,
string? prelude,
@@ -179,8 +196,8 @@ public static class ExternalScriptRunner
DirectoryInfo? filesRoot,
JobFolder folder,
string scriptName,
bool setWorkingDirectory,
JobTrigger? trigger,
ProcessRun run,
Action<NormalizedOutputRecord> onRecord,
CancellationToken cancellationToken)
{
@@ -252,8 +269,17 @@ public static class ExternalScriptRunner
}
}
return await RunProcessAsync(
bash, $"\"{BashPath(scriptPath)}\"", environment, setWorkingDirectory ? folder.Path : null, onRecord, cancellationToken);
return await RunProcessAsync(bash, [BashPath(scriptPath)], environment, run, onRecord, cancellationToken);
}
/// <summary>
/// Where and as whom a script's process runs: the job folder (its working directory with
/// Set Working Directory) and, for Run As Signed-In User, the user.
/// </summary>
internal sealed record ProcessRun(JobFolder Folder, bool SetWorkingDirectory, Agent.Sessions.SignedInUser? RunAs)
{
/// <summary>The job folder with Set Working Directory; otherwise null (the agent's own folder, or the user's home).</summary>
public string? WorkingDirectory => SetWorkingDirectory ? Folder.Path : null;
}
/// <summary>The job folder (EXECUTER_JOB_DIR), the agent (EXECUTER_AGENT_*) and what started the job (EXECUTER_TRIGGER_*).</summary>
@@ -276,20 +302,36 @@ public static class ExternalScriptRunner
private static async Task<ExternalResult> RunProcessAsync(
string fileName,
string arguments,
IReadOnlyList<string> arguments,
IReadOnlyDictionary<string, string>? environment,
string? workingDirectory,
ProcessRun run,
Action<NormalizedOutputRecord> onRecord,
CancellationToken cancellationToken)
{
if (run.RunAs is { } user)
{
// The user reads (and may write) their job folder; nothing else of the agent's.
UserJobAccess.Grant(run.Folder.Path, user);
#if WINDOWS_AGENT
return await RunAsWindowsUserAsync(fileName, arguments, environment, run, user, onRecord, cancellationToken);
#else
// su (root needs no password) keeps this environment; the user's shell execs the
// interpreter, from their home unless Set Working Directory starts it in the job folder.
var command = run.SetWorkingDirectory ? "exec \"$0\" \"$@\"" : "cd 2>/dev/null; exec \"$0\" \"$@\"";
var su = new[] { "/bin/su", "/usr/bin/su" }.FirstOrDefault(File.Exists)
?? throw new InvalidOperationException("su is not available on this device.");
arguments = [user.Name, "-c", command, fileName, .. arguments];
fileName = su;
#endif
}
using var process = new Process
{
StartInfo = new ProcessStartInfo
{
FileName = fileName,
Arguments = arguments,
// Empty inherits the agent's current directory (unchanged default).
WorkingDirectory = workingDirectory ?? string.Empty,
WorkingDirectory = run.WorkingDirectory ?? string.Empty,
UseShellExecute = false,
RedirectStandardOutput = true,
RedirectStandardError = true,
@@ -297,6 +339,11 @@ public static class ExternalScriptRunner
StandardErrorEncoding = Encoding.UTF8,
},
};
foreach (var argument in arguments)
{
process.StartInfo.ArgumentList.Add(argument);
}
if (environment is not null)
{
foreach (var (key, value) in environment)
@@ -351,6 +398,73 @@ public static class ExternalScriptRunner
}
}
#if WINDOWS_AGENT
/// <summary>
/// The interpreter as the signed-in user: their token, environment (plus this run's variables and the
/// agent's bundled modules) and profile folder, headless (no window, hidden) in a kill-on-close job.
/// </summary>
private static async Task<ExternalResult> RunAsWindowsUserAsync(
string fileName,
IReadOnlyList<string> arguments,
IReadOnlyDictionary<string, string>? environment,
ProcessRun run,
Agent.Sessions.SignedInUser user,
Action<NormalizedOutputRecord> onRecord,
CancellationToken cancellationToken)
{
Agent.Screen.IScreenProcess process;
using (var token = Agent.Platform.WindowsUserToken.Open(user))
{
var block = token.EnvironmentBlock(environment, PowerShellRunspaceFactory.BundledModulesPath);
try
{
process = Agent.Screen.WindowsScreenProcessLauncher.Launch(
token.Handle, user.WindowsSession, fileName, arguments, block, run.WorkingDirectory ?? token.ProfileDirectory());
}
finally
{
System.Runtime.InteropServices.Marshal.FreeHGlobal(block);
}
}
await using (process)
{
// Nothing is typed in: end of input at once.
await process.Input.DisposeAsync();
var output = PumpLinesAsync(process.Output, line => onRecord(new NormalizedOutputRecord(OutputStreamKind.Output, line.TrimEnd())));
var error = PumpLinesAsync(process.Error, line => onRecord(new NormalizedOutputRecord(OutputStreamKind.Error, line)));
try
{
var exitCode = await process.Exited.WaitAsync(cancellationToken);
await Task.WhenAll(output, error);
return new ExternalResult(exitCode, WasCancelled: false);
}
catch (OperationCanceledException)
{
// Disposing closes the job, which takes the whole tree.
process.Kill();
return new ExternalResult(-1, WasCancelled: true);
}
}
}
private static async Task PumpLinesAsync(Stream stream, Action<string> onLine)
{
using var reader = new StreamReader(stream, Encoding.UTF8);
try
{
while (await reader.ReadLineAsync() is { } line)
{
onLine(line);
}
}
catch (Exception exception) when (exception is IOException or ObjectDisposedException)
{
// The process went away.
}
}
#endif
private static string? ResolveBash()
{
if (!OperatingSystem.IsWindows())
+37 -7
View File
@@ -29,7 +29,8 @@ public sealed class PowerShellJobHandler(
Agent.LocalRun.JobObservers? observers = null,
JobStartClock? clock = null,
Agent.Restart.RestartCoordinator? restarts = null,
Func<bool>? allowRestart = null)
Func<bool>? allowRestart = null,
Agent.Sessions.ISignedInUserResolver? signedInUsers = null)
{
/// <summary>Most output lines a job that may restart keeps for sending again after the restart.</summary>
public const int MaxKeptOutputLines = 20_000;
@@ -54,6 +55,10 @@ public sealed class PowerShellJobHandler(
ScriptFileFetcher.FetchResult? fetch = null;
var tapId = command.Trigger?.RequestId;
// Script groups: the built-ins come before the script's own functions; their lines become the job's reports.
var prelude = ScriptGroupBuiltIns.Compose(command.Engine, command.Prelude);
var groupReports = new ScriptGroupReportCollector();
// A job that may restart the device keeps its output, so what has not reached the
// server when it restarts can be sent again (bounded; see RestartCoordinator).
var kept = command.RestartAfterRun != RestartAfterRun.Off ? new List<JobOutputPayload>() : null;
@@ -199,12 +204,34 @@ public sealed class PowerShellJobHandler(
}
}
// Run As Signed-In User: whose account, decided before anything runs. Nobody (or nobody
// clear) fails the job rather than running it as the agent's account.
Agent.Sessions.SignedInUser? runAs = null;
string? runAsFailure = null;
if (command.RunAsUser)
{
var lookup = (signedInUsers ?? Agent.Sessions.SignedInUsers.Default).Resolve();
runAs = lookup.User;
runAsFailure = runAs is null ? $"Not run as the signed-in user: {lookup.Reason}" : null;
if (runAs is not null)
{
logger.LogInformation("Job {JobId} runs as {User}", jobId, runAs.Name);
}
}
if (folderFailure is not null)
{
finalState = JobState.Failed;
exitCode = 1;
message = folderFailure;
}
else if (runAsFailure is not null)
{
finalState = JobState.Failed;
exitCode = 1;
message = runAsFailure;
await Task.WhenAll(pending);
}
else if (deliveryFailure is not null)
{
finalState = JobState.Failed;
@@ -222,9 +249,9 @@ public sealed class PowerShellJobHandler(
: $"Execution exceeded the {timeout.TotalSeconds:F0}s timeout while downloading files.";
await Task.WhenAll(pending);
}
else if (command.Engine != ScriptEngine.PowerShell)
else if (command.Engine != ScriptEngine.PowerShell || runAs is not null)
{
// Out-of-process engine: Windows PowerShell 5.1 or Bash.
// Out-of-process engine: Windows PowerShell 5.1 or Bash, or any engine as the signed-in user.
if (!ExternalScriptRunner.IsAvailable(command.Engine))
{
finalState = JobState.Failed;
@@ -239,7 +266,7 @@ public sealed class PowerShellJobHandler(
var external = await ExternalScriptRunner.RunAsync(
command.Engine,
command.Content,
command.Prelude,
prelude,
externalParameters,
command.Secrets,
string.IsNullOrWhiteSpace(command.SecretsVariableName) ? "Secrets" : command.SecretsVariableName,
@@ -258,7 +285,8 @@ public sealed class PowerShellJobHandler(
folder: folder,
scriptName: command.ScriptName,
setWorkingDirectory: command.SetWorkingDirectory,
trigger: command.Trigger);
trigger: command.Trigger,
runAs: runAs);
if (external.WasCancelled && cancellationToken.IsCancellationRequested)
{
@@ -298,7 +326,7 @@ public sealed class PowerShellJobHandler(
var result = await executionService.ExecuteAsync(
command.Content,
boundParameters,
command.Prelude,
prelude,
onRecord: record => pending.Add(PublishOutputAsync(record, Interlocked.Increment(ref sequence))),
onProgress: progress => pending.Add(PublishProgressAsync(progress)),
cancellationToken: timeoutCts.Token,
@@ -447,6 +475,7 @@ public sealed class PowerShellJobHandler(
async Task PublishOutputAsync(NormalizedOutputRecord record, long seq)
{
record = groupReports.Take(record);
observers?.Output(tapId, record.Stream, record.Text);
var line = new JobOutputPayload(jobId, publisher.ClientId, seq, record.Stream, DateTimeOffset.UtcNow, record.Text);
if (kept is not null)
@@ -511,7 +540,8 @@ public sealed class PowerShellJobHandler(
ErrorType: error?.Type, ErrorId: error?.Id, ErrorMessage: error?.Message,
Restart: plan?.State,
RestartDelaySeconds: plan is null ? null : (int)plan.Delay.TotalSeconds,
RestartMessage: plan?.Message);
RestartMessage: plan?.Message,
GroupMemberships: state is JobState.Running ? null : groupReports.Reports);
async Task PublishFinalAsync(JobStatePayload payload)
{
@@ -29,6 +29,10 @@ public static class PowerShellRunspaceFactory
/// both resolve them. Idempotent; a no-op for dev builds where the staged
/// directory does not exist.
/// </summary>
/// <summary>The agent's bundled Modules directory, or null when it has none (development builds).</summary>
public static string? BundledModulesPath =>
Directory.Exists(Path.Combine(AppContext.BaseDirectory, "Modules")) ? Path.Combine(AppContext.BaseDirectory, "Modules") : null;
public static void EnsureBundledModulesOnPath()
{
if (modulesPathEnsured)
+165
View File
@@ -0,0 +1,165 @@
using System.Text.Json;
using Shared.Contracts.Messages;
using Shared.Contracts.Models;
namespace Agent.PowerShell;
/// <summary>
/// The built-ins every script gets for script groups (<see cref="ScriptGroups"/>), and the
/// collector that takes their lines out of a job's output for the job's final state. The
/// built-ins only write a line: no credentials are involved, the agent carries the result.
/// </summary>
public static class ScriptGroupBuiltIns
{
/// <summary>PowerShell (7 and 5.1): Set-, Add- and Remove-ExecuteRGroupMembership.</summary>
public const string PowerShell = """
function Set-ExecuteRGroupMembership {
<#
.SYNOPSIS
Puts this device in an ExecuteR script group, or takes it out, from a result.
.DESCRIPTION
The device is a member when the value is $true, a number above 0, a non-empty
collection (pipe a command's results in), or text other than false/0/no/off.
The group is created the first time a device joins it. Each run decides again.
.EXAMPLE
Get-Package -Name 'Java*' -ErrorAction SilentlyContinue | Set-ExecuteRGroupMembership 'Has Java'
.EXAMPLE
Set-ExecuteRGroupMembership -Name 'Low Disk' -Value ((Get-PSDrive C).Free -lt 10GB)
#>
[CmdletBinding()]
param(
[Parameter(Mandatory, Position = 0)][string] $Name,
[Parameter(Position = 1, ValueFromPipeline)] $Value
)
begin { $__items = [System.Collections.Generic.List[object]]::new() }
process { if ($MyInvocation.ExpectingInput) { $__items.Add($Value) } }
end {
if (-not $MyInvocation.ExpectingInput -and $PSBoundParameters.ContainsKey('Value')) {
if ($Value -is [System.Collections.IEnumerable] -and $Value -isnot [string]) { foreach ($__i in $Value) { $__items.Add($__i) } }
else { $__items.Add($Value) }
}
$__member = $false
if ($__items.Count -gt 1) { $__member = $true }
elseif ($__items.Count -eq 1) {
$__v = $__items[0]
if ($null -eq $__v) { $__member = $false }
elseif ($__v -is [bool]) { $__member = $__v }
elseif ($__v -is [byte] -or $__v -is [int16] -or $__v -is [int] -or $__v -is [long] -or $__v -is [double] -or $__v -is [decimal] -or $__v -is [single] -or $__v -is [uint32] -or $__v -is [uint64]) { $__member = $__v -gt 0 }
elseif ($__v -is [string]) { $__member = @('', 'false', '0', 'no', 'off') -notcontains $__v.Trim().ToLowerInvariant() }
else { $__member = $true }
}
Write-ExecuteRGroupMembership $Name $__member
}
}
function Add-ExecuteRGroupMembership {
<# .SYNOPSIS Puts this device in an ExecuteR script group (created if missing). #>
param([Parameter(Mandatory, Position = 0)][string] $Name)
Write-ExecuteRGroupMembership $Name $true
}
function Remove-ExecuteRGroupMembership {
<# .SYNOPSIS Takes this device out of an ExecuteR script group. #>
param([Parameter(Mandatory, Position = 0)][string] $Name)
Write-ExecuteRGroupMembership $Name $false
}
function Write-ExecuteRGroupMembership([string] $Name, [bool] $Member) {
$json = @{ group = $Name; member = $Member } | ConvertTo-Json -Compress
[Console]::Out.Flush()
Write-Host ('::executer-group::' + $json)
}
""";
/// <summary>Bash: executer_group NAME [VALUE] (VALUE: true/false, a number, or text; default true).</summary>
public const string Bash = """
executer_group() {
local name="$1" value="${2-true}" lower member=true
lower=$(printf '%s' "$value" | tr '[:upper:]' '[:lower:]' | tr -d '[:space:]')
case "$lower" in
''|false|0|no|off) member=false ;;
*) if printf '%s' "$lower" | grep -Eq '^-?[0-9]+$'; then [ "$lower" -gt 0 ] && member=true || member=false; fi ;;
esac
name=$(printf '%s' "$name" | sed 's/\\/\\\\/g; s/"/\\"/g')
printf '::executer-group::{"group":"%s","member":%s}\n' "$name" "$member"
}
""";
/// <summary>The prelude a job runs: the built-ins for its engine, then its own functions.</summary>
public static string Compose(ScriptEngine engine, string? prelude)
=> (engine == ScriptEngine.Bash ? Bash.Replace("\r\n", "\n") : PowerShell) + (prelude ?? string.Empty);
}
/// <summary>
/// Takes the built-ins' lines out of a job's output (any stream: in process they arrive as
/// information records, out of process as stdout) and keeps the last word per group.
/// </summary>
public sealed class ScriptGroupReportCollector
{
private readonly Lock gate = new();
private readonly List<GroupMembershipReport> reports = [];
/// <summary>What the job said, in order, the last per group (null when nothing).</summary>
public IReadOnlyList<GroupMembershipReport>? Reports
{
get
{
lock (gate)
{
return reports.Count == 0 ? null : [.. reports];
}
}
}
/// <summary>The record to publish: a report line becomes a readable one; anything else is unchanged.</summary>
public NormalizedOutputRecord Take(NormalizedOutputRecord record)
{
var text = record.Text?.TrimStart();
if (text is null || !text.StartsWith(ScriptGroups.Marker, StringComparison.Ordinal))
{
return record;
}
GroupMembershipReport? report = null;
try
{
using var json = JsonDocument.Parse(text[ScriptGroups.Marker.Length..]);
var root = json.RootElement;
if (root.TryGetProperty("group", out var group) && group.ValueKind == JsonValueKind.String
&& root.TryGetProperty("member", out var member) && member.ValueKind is JsonValueKind.True or JsonValueKind.False)
{
report = new GroupMembershipReport(group.GetString()!, member.GetBoolean());
}
}
catch (JsonException)
{
// Not ours after all: shown as written.
}
if (report is null)
{
return record;
}
if (ScriptGroups.Normalize(report.Group) is not { } name)
{
return new NormalizedOutputRecord(OutputStreamKind.Warning, $"Script group “{report.Group}” ignored: the name is empty, too long or has / or \\.");
}
lock (gate)
{
reports.RemoveAll(r => string.Equals(r.Group, name, StringComparison.OrdinalIgnoreCase));
if (reports.Count >= ScriptGroups.MaxReportsPerJob)
{
return new NormalizedOutputRecord(OutputStreamKind.Warning, $"Script group “{name}” ignored: a job reports on at most {ScriptGroups.MaxReportsPerJob} groups.");
}
reports.Add(report with { Group = name });
}
return new NormalizedOutputRecord(
OutputStreamKind.Information, report.Member ? $"Script group “{name}”: this device is a member." : $"Script group “{name}”: this device is not a member.");
}
}
+94
View File
@@ -0,0 +1,94 @@
using System.Diagnostics;
using System.Globalization;
using System.Runtime.InteropServices;
#if WINDOWS_AGENT
using System.Security.AccessControl;
using System.Security.Principal;
#endif
using Agent.Sessions;
namespace Agent.PowerShell;
/// <summary>
/// Run As Signed-In User: hands one job folder to the user its script runs as, and nothing more.
/// Windows adds the user (Modify) to the folder and everything in it (the files carry their own
/// locked-down ACLs). Linux/macOS give the folder to the user and let others traverse (not list)
/// the job root, whose other folders stay root's own 0700.
/// </summary>
public static class UserJobAccess
{
public static void Grant(string folder, SignedInUser user)
{
#if WINDOWS_AGENT
using var token = Agent.Platform.WindowsUserToken.Open(user);
var sid = token.Sid ?? throw new InvalidOperationException($"The SID of {user.Name} could not be read.");
GrantWindows(new DirectoryInfo(folder), sid);
#else
if (OperatingSystem.IsWindows())
{
return;
}
var (uid, gid) = Ids(user.Name);
var root = Path.GetDirectoryName(Path.TrimEndingDirectorySeparator(folder));
if (!string.IsNullOrEmpty(root))
{
var mode = File.GetUnixFileMode(root);
File.SetUnixFileMode(root, mode | UnixFileMode.GroupExecute | UnixFileMode.OtherExecute);
}
foreach (var path in Directory.EnumerateFileSystemEntries(folder, "*", SearchOption.AllDirectories).Prepend(folder))
{
if (lchown(path, uid, gid) != 0)
{
throw new InvalidOperationException($"{path} could not be given to {user.Name} (errno {Marshal.GetLastPInvokeError()}).");
}
}
#endif
}
#if WINDOWS_AGENT
private static void GrantWindows(DirectoryInfo folder, SecurityIdentifier sid)
{
var security = folder.GetAccessControl();
security.AddAccessRule(new FileSystemAccessRule(
sid, FileSystemRights.Modify | FileSystemRights.Synchronize,
InheritanceFlags.ContainerInherit | InheritanceFlags.ObjectInherit, PropagationFlags.None, AccessControlType.Allow));
folder.SetAccessControl(security);
foreach (var file in folder.EnumerateFiles())
{
var fileSecurity = file.GetAccessControl();
fileSecurity.AddAccessRule(new FileSystemAccessRule(sid, FileSystemRights.Modify | FileSystemRights.Synchronize, AccessControlType.Allow));
file.SetAccessControl(fileSecurity);
}
foreach (var child in folder.EnumerateDirectories())
{
if ((child.Attributes & FileAttributes.ReparsePoint) == 0)
{
GrantWindows(child, sid);
}
}
}
#else
/// <summary>The user's uid and primary gid (<c>id -u</c>, <c>id -g</c>).</summary>
private static (uint Uid, uint Gid) Ids(string user)
=> (uint.Parse(Id("-u", user), NumberStyles.None, CultureInfo.InvariantCulture),
uint.Parse(Id("-g", user), NumberStyles.None, CultureInfo.InvariantCulture));
private static string Id(string flag, string user)
{
var start = new ProcessStartInfo("id") { RedirectStandardOutput = true, RedirectStandardError = true, UseShellExecute = false };
start.ArgumentList.Add(flag);
start.ArgumentList.Add(user);
using var process = Process.Start(start) ?? throw new InvalidOperationException("id could not be started.");
var output = process.StandardOutput.ReadToEnd().Trim();
process.WaitForExit(5000);
return process.ExitCode == 0 && output.Length > 0 ? output : throw new InvalidOperationException($"{user} is not a user on this device.");
}
[DllImport("libc", SetLastError = true)]
private static extern int lchown([MarshalAs(UnmanagedType.LPUTF8Str)] string path, uint owner, uint group);
#endif
}
+67
View File
@@ -0,0 +1,67 @@
using Microsoft.Extensions.Logging;
using Shared.Contracts.Api;
using Shared.Infrastructure.Logging;
namespace Agent.Screen;
/// <summary>
/// The screen host's own log lines (its stderr, <c>@event</c> lines aside) into the agent's
/// log. The host writes ExecuteR's one format; its time, category and level prefix is taken
/// apart here and the rest (message and <c>key=value</c> fields) logged again at the host's
/// level under the host's category, so the agent's file shows each host line once, in the
/// same format, without a second timestamp. The host bounds its own repeats; a line that
/// is not in a known format is logged whole, as information.
/// </summary>
public static class ScreenHostLog
{
/// <summary>The category of the host's own lines (and of any line that names none).</summary>
public const string Category = "ScreenHost";
/// <summary>How much of one line is kept.</summary>
public const int MaxLineChars = 2000;
/// <summary>Logs one stderr line of the host.</summary>
/// <param name="loggers">Where a category's logger comes from; without one, everything goes to <paramref name="fallback"/>.</param>
public static void Relay(string line, ILoggerFactory? loggers, ILogger fallback)
{
if (line.Length > MaxLineChars)
{
line = line[..MaxLineChars];
}
var (category, level, message) = LogLineParser.TryParse(line, out var parsed)
? (CategoryOf(parsed.Category), ToLogLevel(parsed.Level), parsed.Message)
: (Category, LogLevel.Information, line);
var logger = loggers?.CreateLogger(category) ?? fallback;
logger.Log(level, "{HostLine}", message);
}
/// <summary>A short, safe category for a host line: <c>ScreenHost</c>, or the crate it names (<c>ironrdp_server</c>).</summary>
public static string CategoryOf(string? category)
{
if (string.IsNullOrWhiteSpace(category))
{
return Category;
}
// An older host writes the tracing target (executer_screen::video).
var crate = category.Split("::", 2)[0];
if (crate.StartsWith("executer_screen", StringComparison.Ordinal) || crate.Length > 64
|| !crate.All(c => char.IsAsciiLetterOrDigit(c) || c is '_' or '-' or '.'))
{
return Category;
}
return crate;
}
public static LogLevel ToLogLevel(string level) => level switch
{
LogLevels.Verbose => LogLevel.Trace,
LogLevels.Debug => LogLevel.Debug,
LogLevels.Warning => LogLevel.Warning,
LogLevels.Error => LogLevel.Error,
LogLevels.Fatal => LogLevel.Critical,
_ => LogLevel.Information,
};
}
+7 -2
View File
@@ -26,6 +26,9 @@ public sealed class ScreenSessions : IAsyncDisposable
private readonly Func<bool> enabled;
private readonly Func<string?> logLevel;
private readonly ILogger logger;
/// <summary>Loggers for the screen host's own lines, by its category (<see cref="ScreenHostLog"/>).</summary>
private readonly ILoggerFactory? hostLoggers;
private readonly ConcurrentDictionary<Guid, ScreenStream> streams = new();
private readonly ConcurrentDictionary<Guid, (string Consent, DateTimeOffset Expires)> granted = new();
private readonly ConcurrentDictionary<Guid, ScreenBannerEntry> viewing = new();
@@ -45,10 +48,12 @@ public sealed class ScreenSessions : IAsyncDisposable
Func<string?>? logLevel = null,
TimeSpan? heartbeat = null,
TimeSpan? idle = null,
Agent.Sessions.SessionWatcher? watcher = null)
Agent.Sessions.SessionWatcher? watcher = null,
ILoggerFactory? hostLoggers = null)
{
this.host = host;
this.watcher = watcher;
this.hostLoggers = hostLoggers;
this.enabled = enabled;
this.logger = logger;
this.logLevel = logLevel ?? (() => null);
@@ -192,7 +197,7 @@ public sealed class ScreenSessions : IAsyncDisposable
return new ScreenOpenReply(ScreenOpenStatuses.Failed, "The console session changed; try again.");
}
var stream = new ScreenStream(request.SessionId, request.StreamId, process, publish, logger, request.ViewOnly, heartbeat, idle, cipher: cipher);
var stream = new ScreenStream(request.SessionId, request.StreamId, process, publish, logger, request.ViewOnly, heartbeat, idle, cipher: cipher, hostLoggers: hostLoggers);
streams[request.StreamId] = stream;
stream.Start();
_ = ForgetWhenDoneAsync(stream);
+7 -3
View File
@@ -9,7 +9,8 @@ namespace Agent.Screen;
/// (waiting while a window is unacknowledged, so a slow browser stalls the host's
/// writes instead of growing memory here), the server's bytes go to stdin (and are
/// acknowledged only once written), <c>@event</c> lines on stderr become state
/// frames and every other stderr line goes to the agent log. Ends when the host
/// frames and every other stderr line goes to the agent log (see
/// <see cref="ScreenHostLog"/>). Ends when the host
/// exits, the server ends the stream or goes silent, or <see cref="Stop"/> is
/// called; then the host is closed (stdin EOF), killed if it lingers, and
/// disposed.
@@ -21,6 +22,7 @@ public sealed class ScreenStream
private readonly IScreenProcess process;
private readonly ScreenStreamPump pump;
private readonly ILogger logger;
private readonly ILoggerFactory? hostLoggers;
private readonly TaskCompletionSource<string> stopped = new(TaskCreationOptions.RunContinuationsAsynchronously);
private readonly TaskCompletionSource<ScreenHostEvent?> ready = new(TaskCreationOptions.RunContinuationsAsynchronously);
private readonly CancellationTokenSource cancel = new();
@@ -38,13 +40,15 @@ public sealed class ScreenStream
TimeSpan? heartbeat = null,
TimeSpan? idle = null,
int windowBytes = ScreenStreamDefaults.WindowBytes,
StreamCipher? cipher = null)
StreamCipher? cipher = null,
ILoggerFactory? hostLoggers = null)
{
SessionId = sessionId;
StreamId = streamId;
ViewOnly = viewOnly;
this.process = process;
this.logger = logger;
this.hostLoggers = hostLoggers;
pump = new ScreenStreamPump(
publish,
windowBytes,
@@ -195,7 +199,7 @@ public sealed class ScreenStream
}
else if (line.Length > 0)
{
logger.LogInformation("Screen host: {Line}", line.Length <= 2000 ? line : line[..2000]);
ScreenHostLog.Relay(line, hostLoggers, logger);
}
}
}
+39 -22
View File
@@ -26,23 +26,16 @@ internal sealed class WindowsScreenProcessLauncher(bool intoConsoleSession, bool
public IScreenProcess Start(string fileName, IReadOnlyList<string> arguments)
{
var stdin = new AnonymousPipeServerStream(PipeDirection.Out, HandleInheritability.Inheritable);
var stdout = new AnonymousPipeServerStream(PipeDirection.In, HandleInheritability.Inheritable);
var stderr = new AnonymousPipeServerStream(PipeDirection.In, HandleInheritability.Inheritable);
var token = IntPtr.Zero;
var job = IntPtr.Zero;
var attributeList = IntPtr.Zero;
var handleList = IntPtr.Zero;
var processInfo = default(PROCESS_INFORMATION);
try
{
uint? session = null;
int? session = null;
if (intoConsoleSession)
{
var console = WTSGetActiveConsoleSessionId();
if (console != InvalidSession)
{
session = console;
session = (int)console;
token = ConsoleToken(console);
}
else if (consoleRequired)
@@ -51,7 +44,36 @@ internal sealed class WindowsScreenProcessLauncher(bool intoConsoleSession, bool
}
}
// Only the three pipe ends cross into the host.
return Launch(token, session, fileName, arguments, IntPtr.Zero, Path.GetDirectoryName(fileName));
}
finally
{
if (token != IntPtr.Zero)
{
CloseHandle(token);
}
}
}
/// <summary>
/// Starts <paramref name="fileName"/> on the interactive desktop with redirected stdio, no window and
/// only its three pipe ends inherited, in a kill-on-close job. With a <paramref name="token"/> it runs
/// as that token (the caller keeps it); <paramref name="environment"/> is a Unicode block or zero for
/// the token's defaults; <paramref name="session"/> is what <see cref="IScreenProcess.SessionId"/> reports.
/// </summary>
internal static IScreenProcess Launch(
IntPtr token, int? session, string fileName, IReadOnlyList<string> arguments, IntPtr environment, string? folder)
{
var stdin = new AnonymousPipeServerStream(PipeDirection.Out, HandleInheritability.Inheritable);
var stdout = new AnonymousPipeServerStream(PipeDirection.In, HandleInheritability.Inheritable);
var stderr = new AnonymousPipeServerStream(PipeDirection.In, HandleInheritability.Inheritable);
var job = IntPtr.Zero;
var attributeList = IntPtr.Zero;
var handleList = IntPtr.Zero;
var processInfo = default(PROCESS_INFORMATION);
try
{
// Only the three pipe ends cross into the process.
var handles = new[]
{
stdin.ClientSafePipeHandle.DangerousGetHandle(),
@@ -69,7 +91,7 @@ internal sealed class WindowsScreenProcessLauncher(bool intoConsoleSession, bool
attributeList, 0, PROC_THREAD_ATTRIBUTE_HANDLE_LIST, handleList,
IntPtr.Size * handles.Length, IntPtr.Zero, IntPtr.Zero))
{
throw new Win32Exception(Marshal.GetLastWin32Error(), "The screen host's handle list could not be set.");
throw new Win32Exception(Marshal.GetLastWin32Error(), "The process's handle list could not be set.");
}
var startup = new STARTUPINFOEX { lpAttributeList = attributeList };
@@ -82,14 +104,14 @@ internal sealed class WindowsScreenProcessLauncher(bool intoConsoleSession, bool
startup.StartupInfo.hStdError = handles[2];
var commandLine = new StringBuilder(CommandLine(fileName, arguments));
var flags = EXTENDED_STARTUPINFO_PRESENT | CREATE_NO_WINDOW | CREATE_SUSPENDED;
var folder = Path.GetDirectoryName(fileName);
var flags = EXTENDED_STARTUPINFO_PRESENT | CREATE_NO_WINDOW | CREATE_SUSPENDED
| (environment != IntPtr.Zero ? CREATE_UNICODE_ENVIRONMENT : 0);
var started = token != IntPtr.Zero
? CreateProcessAsUserW(token, fileName, commandLine, IntPtr.Zero, IntPtr.Zero, true, flags, IntPtr.Zero, folder, ref startup, out processInfo)
: CreateProcess(fileName, commandLine, IntPtr.Zero, IntPtr.Zero, true, flags, IntPtr.Zero, folder, ref startup, out processInfo);
? CreateProcessAsUserW(token, fileName, commandLine, IntPtr.Zero, IntPtr.Zero, true, flags, environment, folder, ref startup, out processInfo)
: CreateProcess(fileName, commandLine, IntPtr.Zero, IntPtr.Zero, true, flags, environment, folder, ref startup, out processInfo);
if (!started)
{
throw new Win32Exception(Marshal.GetLastWin32Error(), "The screen host did not start.");
throw new Win32Exception(Marshal.GetLastWin32Error(), $"{Path.GetFileName(fileName)} did not start.");
}
job = KillOnCloseJob();
@@ -108,7 +130,7 @@ internal sealed class WindowsScreenProcessLauncher(bool intoConsoleSession, bool
stdout.DisposeLocalCopyOfClientHandle();
stderr.DisposeLocalCopyOfClientHandle();
var process = new WindowsScreenProcess(processInfo.hProcess, job, stdin, stdout, stderr, session is { } id ? (int)id : null);
var process = new WindowsScreenProcess(processInfo.hProcess, job, stdin, stdout, stderr, session);
processInfo.hProcess = IntPtr.Zero;
job = IntPtr.Zero;
return process;
@@ -138,11 +160,6 @@ internal sealed class WindowsScreenProcessLauncher(bool intoConsoleSession, bool
}
finally
{
if (token != IntPtr.Zero)
{
CloseHandle(token);
}
if (attributeList != IntPtr.Zero)
{
DeleteProcThreadAttributeList(attributeList);
+1 -1
View File
@@ -50,7 +50,7 @@ public static class AgentHost
// LOG_DIRECTORY moved the agent's).
var liveLog = new LiveLog();
builder.Logging.ClearProviders();
builder.Services.AddSerilog(LoggingSetup.CreateLogger(logSettings, "agent", liveLog), dispose: true);
builder.Services.AddSerilog(LoggingSetup.CreateLogger(logSettings, "Agent", liveLog), dispose: true);
builder.Services.AddSingleton(new Logs.AgentLogs(
liveLog, logSettings.Directory, Path.Combine(Upgrade.UpgradeFolders.Installed.InstallDirectory, "Logs")));
+2 -1
View File
@@ -175,7 +175,8 @@ public sealed class AgentSession : IAgentSession
() => configuration.AllowRemoteView.Value,
() => Agent.Screen.ScreenHost.PolicyOf(configuration),
screenLogger,
watcher: sessions);
watcher: sessions,
hostLoggers: loggerFactory);
// The Being Viewed banner (RemoteViewBanner, off by default; read at service start like the rest).
Agent.Screen.ScreenBanner? banner = null;
+19 -14
View File
@@ -237,24 +237,29 @@ public static class ServiceLifecycle
return 0;
}
public static int Status()
/// <summary>
/// The registration and state <c>status</c> reports: NotInstalled when the SCM has no
/// such service; the start type (Automatic, Manual, Disabled) is null when unreadable.
/// </summary>
public static (bool Installed, string State, string? StartType) Query()
{
string state;
var installed = Exists();
if (installed)
if (!Exists())
{
using var controller = new ServiceController(Branding.AgentServiceName);
state = controller.Status.ToString();
}
else
{
state = "NotInstalled";
return (false, "NotInstalled", null);
}
// Machine-readable line first, human-readable after.
Console.WriteLine($"{{\"service\":\"{Branding.AgentServiceName}\",\"installed\":{(installed ? "true" : "false")},\"state\":\"{state}\"}}");
Console.WriteLine($"Service '{Branding.AgentServiceDisplayName}': {state}");
return 0;
using var controller = new ServiceController(Branding.AgentServiceName);
string? startType;
try
{
startType = controller.StartType.ToString();
}
catch (InvalidOperationException)
{
startType = null;
}
return (true, controller.Status.ToString(), startType);
}
private static bool Exists()
+52
View File
@@ -99,11 +99,63 @@ public static class UnixServiceLifecycle
? Run("launchctl", $"kill SIGTERM system/{LaunchdLabel}", ignoreErrors: true)
: Run("systemctl", $"stop {SystemdUnit}", ignoreErrors: true);
/// <summary>The service manager's own description, after the JSON line <c>status</c> prints.</summary>
public static int Status()
=> OperatingSystem.IsMacOS()
? Run("launchctl", $"print system/{LaunchdLabel}", ignoreErrors: true)
: Run("systemctl", $"status {SystemdUnit} --no-pager", ignoreErrors: true);
/// <summary>
/// The registration and state <c>status</c> reports: the unit file / plist present,
/// and systemd's ActiveState (active, inactive, failed, activating) or launchd's
/// "running" / "not running" / "not loaded".
/// </summary>
public static (bool Installed, string State, string? StartType) Query()
{
if (OperatingSystem.IsMacOS())
{
var plist = $"/Library/LaunchDaemons/{LaunchdLabel}.plist";
var (code, output) = Capture("launchctl", $"print system/{LaunchdLabel}");
var state = code != 0 ? "not loaded" : output.Contains("state = running", StringComparison.Ordinal) ? "running" : "not running";
return (File.Exists(plist), state, null);
}
var unit = $"/etc/systemd/system/{SystemdUnit}.service";
var active = Capture("systemctl", $"is-active {SystemdUnit}").Output.Trim();
var enabled = Capture("systemctl", $"is-enabled {SystemdUnit}").Output.Trim();
return (File.Exists(unit), active.Length == 0 ? "unknown" : active, enabled.Length == 0 ? null : enabled);
}
private static (int ExitCode, string Output) Capture(string fileName, string arguments)
{
try
{
using var process = Process.Start(new ProcessStartInfo
{
FileName = fileName,
Arguments = arguments,
UseShellExecute = false,
RedirectStandardOutput = true,
RedirectStandardError = true,
});
if (process is null)
{
return (-1, string.Empty);
}
var errors = process.StandardError.ReadToEndAsync();
var output = process.StandardOutput.ReadToEnd();
process.WaitForExit();
_ = errors.Result;
return (process.ExitCode, output);
}
catch (System.ComponentModel.Win32Exception)
{
// No systemctl / launchctl here (a container): nothing registered.
return (-1, string.Empty);
}
}
private static int InstallSystemd()
{
var unit = $"/etc/systemd/system/{SystemdUnit}.service";
+179
View File
@@ -0,0 +1,179 @@
using System.Diagnostics;
namespace Agent.Sessions;
/// <summary>
/// The account a shell or script runs as for Run As Signed-In User: its name (DOMAIN\user on
/// Windows) and, on Windows, the session whose token it uses.
/// </summary>
public sealed record SignedInUser(string Name, int? WindowsSession = null);
/// <summary>
/// Who to run as, or why nobody can be picked; <see cref="SignedIn"/> names everyone signed in
/// (sorted; null when the sessions could not be read), so the operator can choose one.
/// </summary>
public sealed record SignedInUserLookup(SignedInUser? User, string? Reason, IReadOnlyList<string>? SignedIn = null)
{
public static SignedInUserLookup Nobody(string reason, IReadOnlyList<string>? signedIn = null) => new(null, reason, signedIn);
public static SignedInUserLookup Of(SignedInUser user, IReadOnlyList<string>? signedIn = null) => new(user, null, signedIn ?? [user.Name]);
}
/// <summary>Finds the user to run as on this device.</summary>
public interface ISignedInUserResolver
{
/// <summary>
/// <paramref name="requested"/>: that signed-in user (by name, any case), refused when they are
/// not signed in; null: the usual rule (see <see cref="SignedInUsers.Pick"/>).
/// </summary>
SignedInUserLookup Resolve(string? requested = null);
}
/// <summary>
/// The rule every platform shares: the console's user when someone is at the console;
/// otherwise the only signed-in user. Several users and nobody at the console is ambiguous
/// (a terminal server), so nothing is picked rather than the wrong person.
/// </summary>
public static class SignedInUsers
{
public const string NobodyReason = "Nobody is signed in on the device.";
/// <summary>The resolver for this platform.</summary>
public static ISignedInUserResolver Default { get; } =
#if WINDOWS_AGENT
new WindowsSignedInUserResolver(new WindowsSessionQuery());
#else
OperatingSystem.IsMacOS() ? new MacSignedInUserResolver() : new LinuxSignedInUserResolver();
#endif
/// <summary>
/// Picks from <paramref name="sessions"/> (each with its user). <paramref name="requested"/>
/// names one: their console session when they have it, else their first; nobody when they
/// are not signed in (never an account that merely exists). Otherwise the console's user,
/// else the only user signed in.
/// </summary>
public static SignedInUserLookup Pick<TSession>(
IReadOnlyList<TSession> sessions, Func<TSession, string?> user, Func<TSession, bool> atConsole, Func<TSession, SignedInUser> toUser,
string? requested = null)
{
var signedIn = sessions.Where(s => !string.IsNullOrWhiteSpace(user(s))).ToList();
var names = signedIn.Select(s => user(s)!).Distinct(StringComparer.OrdinalIgnoreCase).Order(StringComparer.OrdinalIgnoreCase).ToList();
if (!string.IsNullOrWhiteSpace(requested))
{
// The exact name first (unix names are case-sensitive), else any case (Windows').
var theirs = signedIn.Where(s => string.Equals(user(s), requested.Trim(), StringComparison.Ordinal)).ToList();
if (theirs.Count == 0)
{
theirs = signedIn.Where(s => string.Equals(user(s), requested.Trim(), StringComparison.OrdinalIgnoreCase)).ToList();
}
return theirs.Count == 0
? SignedInUserLookup.Nobody($"{requested.Trim()} is not signed in on the device.", names)
: SignedInUserLookup.Of(toUser(theirs.FirstOrDefault(atConsole) ?? theirs[0]), names);
}
if (signedIn.FirstOrDefault(atConsole) is { } console)
{
return SignedInUserLookup.Of(toUser(console), names);
}
return names.Count switch
{
0 => SignedInUserLookup.Nobody(NobodyReason, names),
1 => SignedInUserLookup.Of(toUser(signedIn[0]), names),
_ => SignedInUserLookup.Nobody(
$"Several users are signed in ({string.Join(", ", names)}) and nobody is at the console; choose one under Run As.", names),
};
}
}
#if WINDOWS_AGENT
/// <summary>Terminal Services sessions: the active console session's user, else the only signed-in user.</summary>
public sealed class WindowsSignedInUserResolver(ISessionQuery query) : ISignedInUserResolver
{
public SignedInUserLookup Resolve(string? requested = null)
{
var console = query.ActiveConsoleSession();
var sessions = query.Enumerate();
if (sessions is null)
{
return SignedInUserLookup.Nobody("The device's sessions could not be read.");
}
return SignedInUsers.Pick(
sessions, s => s.User, s => s.SessionId == console, s => new SignedInUser(s.User!, s.SessionId), requested);
}
}
#endif
/// <summary>logind's user sessions: a local one's user (the seat's), else the only signed-in user.</summary>
public sealed class LinuxSignedInUserResolver(Func<IReadOnlyList<LogonEvent>?>? sessions = null) : ISignedInUserResolver
{
private readonly Func<IReadOnlyList<LogonEvent>?> current = sessions
?? (() => new LinuxLogonSource(Microsoft.Extensions.Logging.Abstractions.NullLogger.Instance).Current());
public SignedInUserLookup Resolve(string? requested = null)
{
var list = current();
if (list is null)
{
return SignedInUserLookup.Nobody("The device's sessions could not be read (loginctl is unavailable).");
}
// Local sessions stand in for the console: with one local user that is the one. root's own
// sessions are never "the user" (it is the agent's account already).
var users = list.Where(l => !string.IsNullOrWhiteSpace(l.User) && l.User != "root").ToList();
var local = users.Where(l => l.Detail == "local").Select(l => l.User!).Distinct(StringComparer.Ordinal).ToList();
return SignedInUsers.Pick(
users,
l => l.User,
l => local.Count == 1 && l.User == local[0],
l => new SignedInUser(l.User!),
requested);
}
}
/// <summary>The owner of /dev/console (the user at the login window is root: nobody).</summary>
public sealed class MacSignedInUserResolver(Func<string?>? consoleOwner = null) : ISignedInUserResolver
{
private readonly Func<string?> owner = consoleOwner ?? ReadConsoleOwner;
public SignedInUserLookup Resolve(string? requested = null)
{
var name = owner()?.Trim();
if (string.IsNullOrEmpty(name) || name is "root" or "_mbsetupuser")
{
return SignedInUserLookup.Nobody(
string.IsNullOrWhiteSpace(requested) ? SignedInUsers.NobodyReason : $"{requested.Trim()} is not signed in on the device.", []);
}
// Only the console's user counts on macOS (fast user switching's others have no shell to lend).
return string.IsNullOrWhiteSpace(requested) || string.Equals(requested.Trim(), name, StringComparison.Ordinal)
? SignedInUserLookup.Of(new SignedInUser(name))
: SignedInUserLookup.Nobody($"{requested.Trim()} is not the user at the device's console.", [name]);
}
private static string? ReadConsoleOwner()
{
try
{
var start = new ProcessStartInfo("/usr/bin/stat") { RedirectStandardOutput = true, RedirectStandardError = true, UseShellExecute = false };
start.ArgumentList.Add("-f");
start.ArgumentList.Add("%Su");
start.ArgumentList.Add("/dev/console");
using var process = Process.Start(start);
if (process is null)
{
return null;
}
var output = process.StandardOutput.ReadToEnd();
return process.WaitForExit(5000) && process.ExitCode == 0 ? output : null;
}
catch (Exception exception) when (exception is System.ComponentModel.Win32Exception or InvalidOperationException or IOException)
{
return null;
}
}
}
+35 -1
View File
@@ -5,11 +5,19 @@ using static Agent.Shell.ConPtyInterop;
namespace Agent.Shell;
/// <summary>
/// Who a ConPTY shell runs as when not the agent's own account: a primary token (the caller
/// keeps it until <see cref="ConPtySession.Start"/> returns), its environment block and the
/// folder to start in.
/// </summary>
internal sealed record PtyUser(IntPtr Token, IntPtr Environment, string? Directory);
/// <summary>
/// A live ConPTY-backed shell process. Terminal output is delivered via
/// <see cref="OutputReceived"/>; input is written with <see cref="WriteAsync"/>.
/// With a <see cref="PtyUser"/> it starts as that user, on their desktop.
/// </summary>
public sealed class ConPtySession : IPtySession
internal sealed class ConPtySession(PtyUser? user = null) : IPtySession
{
private IntPtr pseudoConsole = IntPtr.Zero;
private IntPtr attributeList = IntPtr.Zero;
@@ -90,6 +98,32 @@ public sealed class ConPtySession : IPtySession
throw new InvalidOperationException("UpdateProcThreadAttribute failed.");
}
if (user is not null)
{
// On the user's desktop, so a window the shell opens shows there; the shell itself is
// headless (the pseudoconsole has no window) and starts hidden, so nothing flashes.
startupInfo.StartupInfo.lpDesktop = @"winsta0\default";
startupInfo.StartupInfo.dwFlags = Agent.Screen.WindowsScreenInterop.STARTF_USESHOWWINDOW;
startupInfo.StartupInfo.wShowWindow = 0;
if (!Agent.Screen.WindowsScreenInterop.CreateProcessAsUserW(
user.Token,
null,
new System.Text.StringBuilder(commandLine),
IntPtr.Zero,
IntPtr.Zero,
false,
EXTENDED_STARTUPINFO_PRESENT | Agent.Screen.WindowsScreenInterop.CREATE_UNICODE_ENVIRONMENT,
user.Environment,
user.Directory,
ref startupInfo,
out processInfo))
{
throw new InvalidOperationException($"CreateProcessAsUser failed (Win32 {Marshal.GetLastWin32Error()}).");
}
return;
}
if (!CreateProcessW(
lpApplicationName: null,
lpCommandLine: commandLine,
+113 -8
View File
@@ -1,4 +1,5 @@
using Agent.Messaging;
using Agent.Sessions;
using Microsoft.Extensions.Logging;
using Shared.Contracts.Messages;
using Shared.Contracts.Models;
@@ -13,8 +14,9 @@ namespace Agent.Shell;
/// one closes the previous. Output is published as base64 over Core NATS with
/// a monotonic sequence.
/// </summary>
public sealed class ShellManager(AgentPublisher publisher, ILogger logger) : IDisposable
public sealed class ShellManager(AgentPublisher publisher, ILogger logger, ISignedInUserResolver? users = null) : IDisposable
{
private readonly ISignedInUserResolver signedIn = users ?? SignedInUsers.Default;
private readonly Lock gate = new();
private ActiveShell? current;
@@ -45,7 +47,42 @@ public sealed class ShellManager(AgentPublisher publisher, ILogger logger) : IDi
return;
}
var pty = CreatePty();
// As the signed-in user: their token (Windows) or su -l (linux/macOS), never the agent's account.
string? asUser = null;
IDisposable? userResources = null;
IPtySession pty;
// Who is signed in travels with the state, so the console can offer each of them.
IReadOnlyList<string>? signedInUsers;
if (command.AsUser)
{
var lookup = signedIn.Resolve(command.User);
signedInUsers = lookup.SignedIn;
if (lookup.User is not { } user)
{
var reason = $"Not opened as the signed-in user: {lookup.Reason}";
logger.LogWarning("Shell session {SessionId} not opened: {Reason}", sessionId, reason);
PublishState(sessionId, ShellSessionState.Failed, reason, signedInUsers: signedInUsers);
return;
}
try
{
(pty, launch, userResources) = CreateUserPty(user, launch);
}
catch (Exception ex) when (ex is not OperationCanceledException)
{
logger.LogWarning("Shell session {SessionId} not opened as {User}: {Reason}", sessionId, user.Name, ex.Message);
PublishState(sessionId, ShellSessionState.Failed, $"Not opened as {user.Name}: {ex.Message}", signedInUsers: signedInUsers);
return;
}
asUser = user.Name;
}
else
{
pty = CreatePty();
signedInUsers = SignedInNames();
}
var active = new ActiveShell
{
@@ -65,10 +102,19 @@ public sealed class ShellManager(AgentPublisher publisher, ILogger logger) : IDi
try
{
pty.Start(launch.FileName, launch.Args, Math.Max(command.Cols, 1), Math.Max(command.Rows, 1));
PublishState(sessionId, ShellSessionState.Open, null, launch.Kind);
logger.LogInformation("Shell session {SessionId} opened: {Kind} ({Shell}, requested {Requested})",
sessionId, launch.Kind ?? "login shell", launch.FileName, command.Shell ?? ShellKinds.Auto);
try
{
pty.Start(launch.FileName, launch.Args, Math.Max(command.Cols, 1), Math.Max(command.Rows, 1));
}
finally
{
// The token and environment block are only needed to start the process.
userResources?.Dispose();
}
PublishState(sessionId, ShellSessionState.Open, null, launch.Kind, asUser, signedInUsers);
logger.LogInformation("Shell session {SessionId} opened: {Kind} ({Shell}, requested {Requested}) as {User}",
sessionId, launch.Kind ?? "login shell", launch.FileName, command.Shell ?? ShellKinds.Auto, asUser ?? "the agent's account");
}
catch (Exception ex)
{
@@ -78,6 +124,50 @@ public sealed class ShellManager(AgentPublisher publisher, ILogger logger) : IDi
}
}
#if WINDOWS_AGENT
/// <summary>A ConPTY started with the user's token, environment and profile folder (the resources go once it has started).</summary>
private static (IPtySession Pty, ShellLaunch Launch, IDisposable Resources) CreateUserPty(SignedInUser user, ShellLaunch launch)
{
var token = Agent.Platform.WindowsUserToken.Open(user);
try
{
var environment = token.EnvironmentBlock(null);
var resources = new UserPtyResources(token, environment);
return (new ConPtySession(new PtyUser(token.Handle, environment, token.ProfileDirectory())), launch, resources);
}
catch
{
token.Dispose();
throw;
}
}
private sealed class UserPtyResources(Agent.Platform.WindowsUserToken token, IntPtr environment) : IDisposable
{
public void Dispose()
{
System.Runtime.InteropServices.Marshal.FreeHGlobal(environment);
token.Dispose();
}
}
#else
/// <summary>The user's login shell through su (root needs no password); the requested shell does not apply.</summary>
private static (IPtySession Pty, ShellLaunch Launch, IDisposable Resources) CreateUserPty(SignedInUser user, ShellLaunch launch)
{
_ = launch;
var su = new[] { "/bin/su", "/usr/bin/su" }.FirstOrDefault(File.Exists)
?? throw new InvalidOperationException("su is not available on this device.");
return (new UnixPtySession(), new ShellLaunch(null, su, ["-l", user.Name]), new NoResources());
}
private sealed class NoResources : IDisposable
{
public void Dispose()
{
}
}
#endif
public async Task WriteAsync(ShellInputPayload input, CancellationToken cancellationToken)
{
ActiveShell? active;
@@ -170,12 +260,27 @@ public sealed class ShellManager(AgentPublisher publisher, ILogger logger) : IDi
payload);
}
private void PublishState(Guid sessionId, ShellSessionState state, string? message, string? shell = null)
private void PublishState(
Guid sessionId, ShellSessionState state, string? message, string? shell = null, string? user = null, IReadOnlyList<string>? signedInUsers = null)
{
_ = publisher.PublishAsync(
NatsSubjects.AgentShellState(publisher.ClientId, sessionId),
MessageTypes.ShellState,
new ShellStatePayload(sessionId, state, message, shell));
new ShellStatePayload(sessionId, state, message, shell, user, signedInUsers));
}
/// <summary>Who is signed in (for the console's Run As list); null when it cannot be read.</summary>
private IReadOnlyList<string>? SignedInNames()
{
try
{
return signedIn.Resolve().SignedIn;
}
catch (Exception ex) when (ex is not OutOfMemoryException)
{
logger.LogDebug("Signed-in users could not be listed: {Message}", ex.Message);
return null;
}
}
private static void DisposeShell(ActiveShell? active, string reason)
+2
View File
@@ -649,6 +649,8 @@ public sealed class ScriptEntity : IFolderItem
/// <see cref="RestartOptions.MaxWarningSeconds"/>).
/// </summary>
public int RestartWarningSeconds { get; set; }
/// <summary>Run as the device's signed-in user (out of process) instead of the agent's account.</summary>
public bool RunAsUser { get; set; }
public DateTimeOffset CreatedUtc { get; set; }
public DateTimeOffset UpdatedUtc { get; set; }
public string? CreatedBy { get; set; }
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,29 @@
using Microsoft.EntityFrameworkCore.Migrations;
#nullable disable
namespace Backend.Data.Migrations.Postgres
{
/// <inheritdoc />
public partial class ScriptRunAsUser : Migration
{
/// <inheritdoc />
protected override void Up(MigrationBuilder migrationBuilder)
{
migrationBuilder.AddColumn<bool>(
name: "RunAsUser",
table: "Scripts",
type: "boolean",
nullable: false,
defaultValue: false);
}
/// <inheritdoc />
protected override void Down(MigrationBuilder migrationBuilder)
{
migrationBuilder.DropColumn(
name: "RunAsUser",
table: "Scripts");
}
}
}
@@ -1122,6 +1122,9 @@ namespace Backend.Data.Migrations.Postgres
b.Property<int>("RestartWarningSeconds")
.HasColumnType("integer");
b.Property<bool>("RunAsUser")
.HasColumnType("boolean");
b.Property<bool>("RunFromFile")
.HasColumnType("boolean");
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,29 @@
using Microsoft.EntityFrameworkCore.Migrations;
#nullable disable
namespace Backend.Data.Migrations.SqlServer
{
/// <inheritdoc />
public partial class ScriptRunAsUser : Migration
{
/// <inheritdoc />
protected override void Up(MigrationBuilder migrationBuilder)
{
migrationBuilder.AddColumn<bool>(
name: "RunAsUser",
table: "Scripts",
type: "bit",
nullable: false,
defaultValue: false);
}
/// <inheritdoc />
protected override void Down(MigrationBuilder migrationBuilder)
{
migrationBuilder.DropColumn(
name: "RunAsUser",
table: "Scripts");
}
}
}
@@ -1122,6 +1122,9 @@ namespace Backend.Data.Migrations.SqlServer
b.Property<int>("RestartWarningSeconds")
.HasColumnType("int");
b.Property<bool>("RunAsUser")
.HasColumnType("bit");
b.Property<bool>("RunFromFile")
.HasColumnType("bit");
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,29 @@
using Microsoft.EntityFrameworkCore.Migrations;
#nullable disable
namespace Backend.Data.Migrations.Sqlite
{
/// <inheritdoc />
public partial class ScriptRunAsUser : Migration
{
/// <inheritdoc />
protected override void Up(MigrationBuilder migrationBuilder)
{
migrationBuilder.AddColumn<bool>(
name: "RunAsUser",
table: "Scripts",
type: "INTEGER",
nullable: false,
defaultValue: false);
}
/// <inheritdoc />
protected override void Down(MigrationBuilder migrationBuilder)
{
migrationBuilder.DropColumn(
name: "RunAsUser",
table: "Scripts");
}
}
}
@@ -1111,6 +1111,9 @@ namespace Backend.Data.Migrations.Sqlite
b.Property<int>("RestartWarningSeconds")
.HasColumnType("INTEGER");
b.Property<bool>("RunAsUser")
.HasColumnType("INTEGER");
b.Property<bool>("RunFromFile")
.HasColumnType("INTEGER");
+90 -108
View File
@@ -12,7 +12,8 @@ namespace Backend.Enrollment;
///
/// The returned PowerShell downloads the agent package from this same origin
/// and installs it with SERVERURL + BOOTSTRAPTOKEN. The package is served from
/// AGENT_PACKAGE_PATH (default /data/agent).
/// AGENT_PACKAGE_PATH (default /data/agent). Every script is safe to run again:
/// it installs, upgrades, repairs or leaves the agent alone (<see cref="InstallScripts"/>).
/// </summary>
public static class InstallEndpoints
{
@@ -50,8 +51,9 @@ public static class InstallEndpoints
: Results.Text(pem, "application/x-pem-file; charset=utf-8");
}
private static IResult GetInstallScript(
HttpContext context, IConfiguration configuration, Backend.Tls.TlsSettings tls, string? token, string? type)
private static async Task<IResult> GetInstallScript(
HttpContext context, IConfiguration configuration, Backend.Tls.TlsSettings tls, Files.AgentPackageService packages,
Upgrades.AgentCatalogService catalog, string? token, string? type, CancellationToken cancellationToken)
{
if (string.IsNullOrWhiteSpace(token))
{
@@ -78,14 +80,24 @@ public static class InstallEndpoints
// scripts also work in Windows PE: there the MSI script switches to the
// portable package (Windows Installer does not run in WinPE).
// The package links carry the token: without public downloads, a live token is what lets them through.
// Each script compares the installed agent with the version the package link
// serves, so a rerun on a current, healthy device changes nothing.
var catalogued = (await catalog.NewestByTypeAsync(cancellationToken))
.ToDictionary(p => p.Key, p => p.Value.Version, StringComparer.OrdinalIgnoreCase);
string? Version(string packageType) => ServedVersion(packageType, catalogued, packages);
var tokenQuery = "token=" + Uri.EscapeDataString(token!);
var zipUrl = $"{baseUrl}{ApiRoutes.AgentPackage}?type=zip&{tokenQuery}";
var script = type?.ToLowerInvariant() switch
{
"linux" => BuildUnixScript(baseUrl, token!, "linux", tokenQuery, skipDownloadVerify, fingerprint),
"osx" or "mac" or "macos" or "darwin" => BuildUnixScript(baseUrl, token!, "osx", tokenQuery, skipDownloadVerify, fingerprint),
"zip" => BuildZipScript(baseUrl, token!, zipUrl, skipDownloadVerify, fingerprint),
_ => BuildMsiScript(baseUrl, token!, $"{baseUrl}{ApiRoutes.AgentPackage}?type=msi&{tokenQuery}", zipUrl, skipDownloadVerify, fingerprint),
"linux" => BuildUnixScript(baseUrl, token!, "linux", tokenQuery, skipDownloadVerify, fingerprint,
Version(AgentPackageTypes.LinuxX64), Version(AgentPackageTypes.LinuxArm64)),
"osx" or "mac" or "macos" or "darwin" => BuildUnixScript(baseUrl, token!, "osx", tokenQuery, skipDownloadVerify, fingerprint,
Version(AgentPackageTypes.MacX64), Version(AgentPackageTypes.MacArm64)),
"zip" => BuildWindowsScript(baseUrl, token!, msiUrl: null, zipUrl, msiVersion: null, Version(AgentPackageTypes.WindowsZip),
skipDownloadVerify, fingerprint),
_ => BuildWindowsScript(baseUrl, token!, $"{baseUrl}{ApiRoutes.AgentPackage}?type=msi&{tokenQuery}", zipUrl,
Version(AgentPackageTypes.Msi), Version(AgentPackageTypes.WindowsZip), skipDownloadVerify, fingerprint),
};
return Results.Text(script, "text/plain; charset=utf-8");
@@ -191,129 +203,99 @@ public static class InstallEndpoints
// an elevated PowerShell — the Add device modal states this prerequisite.
// Windows PE (the MiniNT key) has no Windows Installer, so there the MSI
// script takes the portable path instead — same service, same enrollment.
private static string BuildMsiScript(
string baseUrl, string token, string packageUrl, string zipUrl, bool skipDownloadVerify, string? fingerprint) => $$"""
// The body (InstallScripts) looks before it acts: install, upgrade, repair or
// nothing, and the token only where the enrollment needs it.
internal static string BuildWindowsScript(
string baseUrl, string token, string? msiUrl, string zipUrl, string? msiVersion, string? zipVersion,
bool skipDownloadVerify, string? fingerprint) => $$"""
$ErrorActionPreference = 'Stop'
{{PsDownloadTls}}
{{(skipDownloadVerify ? PsAcceptCert : "")}}
$server = '{{baseUrl}}'
$token = '{{token}}'
$server = {{PsQuote(baseUrl)}}
$token = {{PsQuote(token)}}
$msiUrl = {{PsQuote(msiUrl ?? "")}}
$zipUrl = {{PsQuote(zipUrl)}}
$msiVersion = {{PsQuote(msiVersion ?? "")}}
$zipVersion = {{PsQuote(zipVersion ?? "")}}
$portableOnly = {{(msiUrl is null ? "$true" : "$false")}}
{{PsDownload(fingerprint)}}
if (Test-Path '{{PsWinPeKey}}') {
Write-Host 'Windows PE detected: installing ExecuteR Agent (portable)...'
{{PortableInstall(zipUrl)}}
}
else {
Write-Host 'Installing ExecuteR Agent...'
$msi = Join-Path $env:TEMP ('ExecuteRAgent-' + [guid]::NewGuid().ToString('N') + '.msi')
try {
Save-ExecuteRFile '{{packageUrl}}' $msi
$arguments = @('/i', ('"' + $msi + '"'), '/qn', "SERVERURL=$server", "BOOTSTRAPTOKEN=$token")
$p = Start-Process msiexec.exe -ArgumentList $arguments -Wait -PassThru
if ($p.ExitCode -ne 0) { throw "msiexec exited with $($p.ExitCode)" }
Write-Host 'ExecuteR Agent installed. It will enroll and start automatically.'
}
finally {
Remove-Item $msi -ErrorAction SilentlyContinue
}
}
""";
private const string PsWinPeKey = @"HKLM:\SYSTEM\CurrentControlSet\Control\MiniNT";
/// <summary>
/// The portable install body (expects <c>$server</c>/<c>$token</c>): unpack
/// the zip under Program Files (X:\ in Windows PE), seed enrollment, then
/// register and start the Windows service through the agent's own
/// <c>initialize</c> (Service Control Manager APIs, never sc.exe). Unzips
/// with System.IO.Compression rather than Expand-Archive, which a minimal
/// PowerShell (Windows PE) may lack; a re-run stops the running agent first
/// so its files can be replaced. ExtractToDirectory creates missing
/// parent folders.
/// </summary>
private static string PortableInstall(string packageUrl) => $$"""
$dest = Join-Path $env:ProgramFiles 'ExecuteR\Agent'
$exe = Join-Path $dest 'ExecuteR-Agent.exe'
$zip = Join-Path $env:TEMP ('ExecuteRAgent-' + [guid]::NewGuid().ToString('N') + '.zip')
$unpacked = $zip + '.d'
try {
Save-ExecuteRFile '{{packageUrl}}' $zip
Add-Type -AssemblyName System.IO.Compression.FileSystem
if (Test-Path $dest) {
[System.IO.Compression.ZipFile]::ExtractToDirectory($zip, $unpacked)
if (Test-Path $exe) { try { & $exe stop | Out-Null } catch { } }
Copy-Item -Path (Join-Path $unpacked '*') -Destination $dest -Recurse -Force
}
else {
# First install: unpack in place (Windows PE's RAM drive is small).
[System.IO.Compression.ZipFile]::ExtractToDirectory($zip, $dest)
}
# Windows PE: nobody signs in, so the Being Viewed banner has no place there.
if (Test-Path '{{PsWinPeKey}}') {
Remove-Item (Join-Path $dest '{{Shared.Infrastructure.Constants.Branding.BannerExecutableName}}') -Force -ErrorAction SilentlyContinue
}
# Seed configuration then install + start the service via the agent's own APIs.
New-Item -Path 'HKLM:\SOFTWARE\ExecuteR' -Force | Out-Null
Set-ItemProperty -Path 'HKLM:\SOFTWARE\ExecuteR' -Name 'ServerURL' -Value $server
Set-ItemProperty -Path 'HKLM:\SOFTWARE\ExecuteR' -Name 'BootstrapToken' -Value $token
& $exe initialize
if ($LASTEXITCODE -ne 0) { throw "ExecuteR-Agent initialize exited with $LASTEXITCODE" }
Write-Host 'ExecuteR Agent installed and starting.'
}
finally {
Remove-Item $zip -ErrorAction SilentlyContinue
Remove-Item $unpacked -Recurse -Force -ErrorAction SilentlyContinue
}
{{InstallScripts.WindowsFunctions}}
{{InstallScripts.WindowsMain}}
""";
/// <summary>
/// linux/macOS installer: detects the architecture, downloads the matching
/// agent zip, unpacks to /opt/executer/agent, configures enrollment via
/// the agent's own CLI and registers the systemd unit / launchd daemon.
/// linux/macOS installer: detects the architecture, then installs, upgrades or
/// repairs the agent from the matching zip under /opt/executer/agent, configures
/// enrollment through the agent's own CLI and registers the systemd unit /
/// launchd daemon through its initialize (InstallScripts has the rules).
/// </summary>
// ReplaceLineEndings("\n"): the .cs source is checked out with CRLF on
// Windows, but a bash script with CRLF fails hard when piped to bash
// (`set -euo pipefail\r` -> ": invalid option namepefail"). Force LF.
private static string BuildUnixScript(string baseUrl, string token, string os, string tokenQuery, bool skipDownloadVerify, string? fingerprint) => ($$"""
// Everything runs from main() on the last line: bash reads a piped script as
// it goes, so a cut-off download runs nothing.
internal static string BuildUnixScript(
string baseUrl, string token, string os, string tokenQuery, bool skipDownloadVerify, string? fingerprint,
string? x64Version, string? arm64Version) => ($$"""
#!/usr/bin/env bash
set -euo pipefail
if [ "$(id -u)" -ne 0 ]; then echo 'Run with sudo/root.' >&2; exit 1; fi
server='{{baseUrl}}'
token='{{token}}'
if [ "$(id -u)" -ne 0 ]; then echo 'Failed: run with sudo/root.' >&2; exit 1; fi
server={{ShQuote(baseUrl)}}
token={{ShQuote(token)}}
os='{{os}}'
case "$(uname -m)" in
x86_64|amd64) arch=x64 ;;
aarch64|arm64) arch=arm64 ;;
*) echo "Unsupported architecture: $(uname -m)" >&2; exit 1 ;;
*) echo "Failed: unsupported architecture $(uname -m)" >&2; exit 1 ;;
esac
pkg="{{baseUrl}}{{ApiRoutes.AgentPackage}}?type={{os}}-${arch}&{{tokenQuery}}"
case "$arch" in
x64) target={{ShQuote(x64Version ?? "")}} ;;
*) target={{ShQuote(arm64Version ?? "")}} ;;
esac
dest=/opt/executer/agent
tmp=$(mktemp -d)
trap 'rm -rf "$tmp"' EXIT
lock=/var/run/executer-install.lock
reported=0
locked=0
tmp=$(mktemp -d "${TMPDIR:-/tmp}/executer-install.XXXXXX")
cleanup() {
local rc=$?
rm -rf "$tmp"
if [ "$locked" = 1 ]; then rm -rf "$lock"; fi
if [ "$rc" -ne 0 ] && [ "$reported" = 0 ]; then echo "Failed: the setup stopped unexpectedly (exit $rc)."; fi
}
trap cleanup EXIT
{{ShDownload(fingerprint, skipDownloadVerify)}}
echo "Installing ExecuteR Agent ({{os}}-${arch})..."
download "$pkg" "$tmp/agent.zip"
mkdir -p "$dest"
if command -v unzip >/dev/null 2>&1; then
unzip -oq "$tmp/agent.zip" -d "$dest"
else
python3 -m zipfile -e "$tmp/agent.zip" "$dest"
fi
chmod +x "$dest/executer-agent"
"$dest/executer-agent" configure --url "$server" --token "$token"
"$dest/executer-agent" initialize
echo 'ExecuteR Agent installed. It will enroll and start automatically.'
{{InstallScripts.UnixFunctions}}
main
""").ReplaceLineEndings("\n");
private static string BuildZipScript(string baseUrl, string token, string packageUrl, bool skipDownloadVerify, string? fingerprint) => $$"""
$ErrorActionPreference = 'Stop'
Write-Host 'Installing ExecuteR Agent (portable)...'
{{PsDownloadTls}}
{{(skipDownloadVerify ? PsAcceptCert : "")}}
$server = '{{baseUrl}}'
$token = '{{token}}'
{{PsDownload(fingerprint)}}
{{PortableInstall(packageUrl)}}
""";
/// <summary>A PowerShell single-quoted literal.</summary>
internal static string PsQuote(string value) => "'" + value.Replace("'", "''") + "'";
/// <summary>A bash single-quoted literal.</summary>
internal static string ShQuote(string value) => "'" + value.Replace("'", "'\\''") + "'";
/// <summary>
/// The version the package link serves for a type (as <see cref="ServePackageAsync"/>
/// picks: the catalog's newest unless this node holds a newer one), or null when
/// unknown. Only a version the comparison understands goes into a script.
/// </summary>
internal static string? ServedVersion(string packageType, IReadOnlyDictionary<string, string> catalogued, Files.AgentPackageService packages)
{
var path = packages.ResolveLocalPath(packageType);
var local = path is null ? null : Files.AgentPackageService.ReadVersionMarker(Path.GetDirectoryName(path));
var version = catalogued.TryGetValue(packageType, out var newest) && (path is null || !AgentVersions.IsNewer(local, newest))
? newest
: local;
return ScriptSafeVersion(version);
}
internal static string? ScriptSafeVersion(string? version)
=> version is not null && AgentVersions.IsValid(version)
&& version.Trim().All(c => char.IsAsciiLetterOrDigit(c) || c is '.' or '+' or '-')
? version.Trim()
: null;
/// <summary>
/// The CA fingerprint a bootstrap token carries ("secret.fp", 64 hex
File diff suppressed because it is too large Load Diff
+4 -4
View File
@@ -145,7 +145,7 @@ public sealed class DeviceGroupService(AppDbContext db, InventoryReportCache inv
var known = devices.Select(d => d.ClientId).ToHashSet(StringComparer.Ordinal);
var direct = groups.ToDictionary(g => g.Id, _ => new HashSet<string>(StringComparer.Ordinal));
var staticIds = groups.Where(g => g.Kind == GroupKind.Static).Select(g => g.Id).ToHashSet();
var staticIds = groups.Where(g => ScriptGroups.HasMemberRows(g.Kind)).Select(g => g.Id).ToHashSet();
foreach (var row in staticRows)
{
// Rows for deleted devices or non-static groups are ignored.
@@ -197,7 +197,7 @@ public sealed class DeviceGroupService(AppDbContext db, InventoryReportCache inv
{
switch (group.Kind)
{
case GroupKind.Static:
case GroupKind.Static or GroupKind.Script:
return await db.DeviceGroupMembers.AsNoTracking()
.Where(m => m.GroupId == group.Id && db.Devices.Any(d => d.ClientId == m.ClientId))
.Select(m => m.ClientId)
@@ -306,7 +306,7 @@ public sealed class DeviceGroupService(AppDbContext db, InventoryReportCache inv
var directIds = groups
.Where(group => group.Kind switch
{
GroupKind.Static => staticGroupIds.Contains(group.Id),
GroupKind.Static or GroupKind.Script => staticGroupIds.Contains(group.Id),
GroupKind.Dynamic => ParseRules(group.RulesJson) is { } rules && RuleEvaluator.Matches(rules, fields),
_ => false,
})
@@ -397,7 +397,7 @@ public sealed class DeviceGroupService(AppDbContext db, InventoryReportCache inv
return (await GetMembershipAsync(cancellationToken)).Effective(group.Id).Contains(clientId);
}
if (group.Kind == GroupKind.Static)
if (ScriptGroups.HasMemberRows(group.Kind))
{
return await db.DeviceGroupMembers.AsNoTracking()
.AnyAsync(m => m.GroupId == group.Id && m.ClientId == clientId, cancellationToken);
+9 -6
View File
@@ -127,9 +127,9 @@ public static class GroupEndpoints
return rulesProblem;
}
// Only static groups keep an explicit list; switching kind drops it so
// a later switch back does not resurrect stale members.
if (request.Kind != GroupKind.Static && entity.Kind == GroupKind.Static)
// Only static and script groups keep an explicit list; switching to a kind without one drops
// it so a later switch back does not resurrect stale members.
if (!ScriptGroups.HasMemberRows(request.Kind) && ScriptGroups.HasMemberRows(entity.Kind))
{
await db.DeviceGroupMembers.Where(m => m.GroupId == id).ExecuteDeleteAsync(cancellationToken);
}
@@ -292,9 +292,12 @@ public static class GroupEndpoints
{
return Results.BadRequest(new
{
error = entity.Kind == GroupKind.Dynamic
? "Membership of a dynamic group is determined by its rules."
: "A folder holds groups, not devices. Add the devices to a static group inside it.",
error = entity.Kind switch
{
GroupKind.Dynamic => "Membership of a dynamic group is determined by its rules.",
GroupKind.Script => "Membership of a script group is set by the scripts that report on it.",
_ => "A folder holds groups, not devices. Add the devices to a static group inside it.",
},
});
}
+122
View File
@@ -0,0 +1,122 @@
using Backend.Data;
using Backend.Security;
using Microsoft.EntityFrameworkCore;
using Shared.Contracts.Models;
namespace Backend.Groups;
/// <summary>
/// Applies what a device's job said about its script groups (<see cref="ScriptGroups"/>): each named
/// script group gains or loses that device, and a group a device joins first is created (top level).
/// Only script groups change: a report naming a static, dynamic or folder group is ignored, so a
/// device can never put itself into a group an operator curates. One device's report only ever
/// changes that device's own membership.
/// </summary>
public sealed class ScriptGroupMembership(AppDbContext db, AuditService audit, ILogger<ScriptGroupMembership> logger)
{
/// <summary>What changed, for the activity feed.</summary>
public sealed record Outcome(IReadOnlyList<string> Joined, IReadOnlyList<string> Left, IReadOnlyList<string> Created, IReadOnlyList<string> Ignored)
{
public bool Changed => Joined.Count + Left.Count > 0;
}
public async Task<Outcome> ApplyAsync(
string clientId, string scriptName, IReadOnlyList<GroupMembershipReport> reports, CancellationToken cancellationToken)
{
var joined = new List<string>();
var left = new List<string>();
var created = new List<string>();
var ignored = new List<string>();
// The last word per group wins; past the limit nothing more is read.
var wanted = new Dictionary<string, bool>(StringComparer.OrdinalIgnoreCase);
foreach (var report in reports.Take(ScriptGroups.MaxReportsPerJob))
{
if (ScriptGroups.Normalize(report.Group) is { } name)
{
wanted.Remove(name);
wanted[name] = report.Member;
}
}
if (wanted.Count == 0 || !await db.Devices.AnyAsync(d => d.ClientId == clientId, cancellationToken))
{
return new Outcome(joined, left, created, ignored);
}
var lowered = wanted.Keys.Select(k => k.ToLowerInvariant()).ToList();
var named = await db.DeviceGroups
.Where(g => lowered.Contains(g.Name.ToLower()))
.ToListAsync(cancellationToken);
var now = DateTimeOffset.UtcNow;
foreach (var (name, member) in wanted)
{
var matches = named.Where(g => string.Equals(g.Name, name, StringComparison.OrdinalIgnoreCase)).ToList();
var group = matches.FirstOrDefault(g => g.Kind == GroupKind.Script);
if (group is null && matches.Count > 0)
{
// A curated group by that name: never touched by a device.
ignored.Add(name);
continue;
}
if (group is null)
{
if (!member)
{
continue;
}
group = new DeviceGroupEntity
{
Id = Guid.NewGuid(),
Name = name,
Kind = GroupKind.Script,
Description = $"Devices whose scripts report they belong; first reported by “{scriptName}”.",
CreatedUtc = now,
UpdatedUtc = now,
UpdatedBy = $"script:{scriptName}",
};
db.DeviceGroups.Add(group);
named.Add(group);
created.Add(name);
}
var row = await db.DeviceGroupMembers.SingleOrDefaultAsync(m => m.GroupId == group.Id && m.ClientId == clientId, cancellationToken);
if (member && row is null)
{
db.DeviceGroupMembers.Add(new DeviceGroupMemberEntity { GroupId = group.Id, ClientId = clientId, AddedUtc = now });
joined.Add(group.Name);
}
else if (!member && row is not null)
{
db.DeviceGroupMembers.Remove(row);
left.Add(group.Name);
}
}
await db.SaveChangesAsync(cancellationToken);
foreach (var name in created)
{
await audit.LogAsync(AuditCategories.Admin, "group-created", $"script:{scriptName}",
clientId: clientId, detail: $"{name} (Script)", cancellationToken: cancellationToken);
}
if (joined.Count + left.Count > 0)
{
await audit.LogAsync(AuditCategories.Admin, "group-members", $"script:{scriptName}", clientId: clientId,
detail: $"joined={string.Join(", ", joined)} left={string.Join(", ", left)}", cancellationToken: cancellationToken);
}
if (ignored.Count > 0)
{
logger.LogWarning(
"Device {ClientId} reported membership of {Groups} from “{Script}”; ignored: those are not script groups",
clientId, string.Join(", ", ignored), scriptName);
}
return new Outcome(joined, left, created, ignored);
}
}
+5
View File
@@ -155,6 +155,11 @@ public sealed class JobDispatcher(IServiceScopeFactory scopeFactory, ILogger<Job
skips.Add(new RunSkip(device.ClientId, device.Hostname, SkipReasons.Offline));
await RemoveAsync(db, job, cancellationToken);
}
else if (JobRunner.RunAsUserRefusal(snapshot.RunAsUser == true, device.AgentVersion) is { } refusal)
{
// An older agent would ignore Run As Signed-In User and run as its own account.
await FailAsync(runner, job, refusal, tally, cancellationToken);
}
else
{
sendable.Add((job, device));
+44 -4
View File
@@ -118,6 +118,22 @@ public sealed class JobRunner(
return job;
}
/// <summary>
/// Why a job of a Run As Signed-In User script cannot go to an agent at <paramref name="agentVersion"/>
/// (it would ignore the option and run as its own account), or null when it can.
/// </summary>
internal static string? RunAsUserRefusal(bool runAsUser, string? agentVersion)
=> runAsUser && !RunAsUser.Supported(agentVersion) ? RunAsUser.Unsupported(agentVersion) : null;
/// <summary>A job created already failed (never sent).</summary>
private static JobEntity Refused(JobEntity job, string message, DateTimeOffset now)
{
job.State = JobState.Failed;
job.CompletedUtc = now;
job.OutputSummary = message;
return job;
}
private static JobEntity NewJob(ScriptEntity script, string clientId, string? requestedBy, Guid? runId, DateTimeOffset createdUtc) => new()
{
JobId = Guid.NewGuid(),
@@ -192,10 +208,19 @@ public sealed class JobRunner(
foreach (var chunk in devices.Chunk(WriteBatch))
{
var now = DateTimeOffset.UtcNow;
var batch = chunk.Select(d => new Outgoing(NewJob(prepared.Script, d.ClientId, requestedBy, runId, now), activityText(d))).ToList();
// A device whose agent cannot honor Run As Signed-In User gets its job already failed.
var created = chunk.Select(d =>
{
var job = NewJob(prepared.Script, d.ClientId, requestedBy, runId, now);
return (Device: d, Job: RunAsUserRefusal(prepared.Script.RunAsUser, d.AgentVersion) is { } refusal ? Refused(job, refusal, now) : job);
}).ToList();
var batch = created
.Where(c => c.Job.State == JobState.Queued)
.Select(c => new Outgoing(c.Job, activityText(c.Device)))
.ToList();
undecided.UnionWith(batch.Select(o => o.Job));
await InsertAsync(batch.Select(o => o.Job).ToList(), cancellationToken);
jobs.AddRange(batch.Select(o => o.Job));
await InsertAsync(created.Select(c => c.Job).ToList(), cancellationToken);
jobs.AddRange(created.Select(c => c.Job));
var previous = sending;
var sent = publishing is null ? null : await publishing;
@@ -366,7 +391,8 @@ public sealed class JobRunner(
Trigger: trigger,
RestartAfterRun: script.RestartAfterRun,
RestartDelaySeconds: script.RestartDelaySeconds,
RestartWarningSeconds: script.RestartWarningSeconds),
RestartWarningSeconds: script.RestartWarningSeconds,
RunAsUser: script.RunAsUser),
cancellationToken);
}
@@ -604,6 +630,20 @@ public sealed class JobRunner(
DateTimeOffset? notBeforeUtc = null,
JobTrigger? trigger = null)
{
if (prepared.Script.RunAsUser)
{
var agentVersion = await db.Devices.AsNoTracking()
.Where(d => d.ClientId == job.ClientId)
.Select(d => d.AgentVersion)
.FirstOrDefaultAsync(cancellationToken);
if (RunAsUserRefusal(true, agentVersion) is { } refusal)
{
// Settled here: nothing for the dispatcher to retry.
await MarkFailedAsync(job, refusal, cancellationToken);
return true;
}
}
var dispatched = await PublishAsync(prepared, job, arguments, notBeforeUtc, trigger, cancellationToken);
if (dispatched)
+6 -2
View File
@@ -32,7 +32,9 @@ public sealed record RunSnapshot(
DateTimeOffset? NotBeforeUtc = null,
Shared.Contracts.Messages.JobTrigger? Trigger = null,
// Warn Signed-In Users; null in snapshots sealed before it existed (off).
int? RestartWarningSeconds = null)
int? RestartWarningSeconds = null,
// Run as the signed-in user; null in snapshots sealed before it existed (off).
bool? RunAsUser = null)
{
/// <summary>
/// The snapshot of a run; <paramref name="notBeforeUtc"/> and <paramref name="trigger"/> belong to
@@ -58,7 +60,8 @@ public sealed record RunSnapshot(
prepared.Script.RestartDelaySeconds,
notBeforeUtc,
trigger,
prepared.Script.RestartWarningSeconds);
prepared.Script.RestartWarningSeconds,
prepared.Script.RunAsUser);
/// <summary>A detached script entity to prepare and dispatch from.</summary>
public ScriptEntity ToScript() => new()
@@ -77,6 +80,7 @@ public sealed record RunSnapshot(
RestartAfterRun = RestartAfterRun ?? Shared.Contracts.Models.RestartAfterRun.Off,
RestartDelaySeconds = RestartDelaySeconds ?? 0,
RestartWarningSeconds = RestartWarningSeconds ?? 0,
RunAsUser = RunAsUser ?? false,
};
}
+28
View File
@@ -1461,6 +1461,34 @@ public sealed class MessagingWorkers(
await broadcaster.BroadcastActivityAsync(new ActivityEventPayload(
"job-completed", $"Job “{stored.ScriptName}” {payload.State.ToString().ToLowerInvariant()}",
payload.ClientId, payload.JobId, DateTimeOffset.UtcNow), cancellationToken);
// What the script said about its device's script groups, once (a redelivered final state is not applied).
if (stored.Applied && payload.GroupMemberships is { Count: > 0 } reports)
{
await ApplyGroupMembershipsAsync(payload, stored.ScriptName, reports, cancellationToken);
}
}
}
private async Task ApplyGroupMembershipsAsync(
JobStatePayload payload, string scriptName, IReadOnlyList<GroupMembershipReport> reports, CancellationToken cancellationToken)
{
try
{
using var scope = scopeFactory.CreateScope();
var outcome = await scope.ServiceProvider.GetRequiredService<Backend.Groups.ScriptGroupMembership>()
.ApplyAsync(payload.ClientId, scriptName, reports, cancellationToken);
if (outcome.Changed)
{
var parts = outcome.Joined.Select(g => $"joined “{g}”").Concat(outcome.Left.Select(g => $"left “{g}”"));
await broadcaster.BroadcastActivityAsync(new ActivityEventPayload(
"group-membership", $"“{scriptName}”: device {string.Join(", ", parts)}",
payload.ClientId, payload.JobId, DateTimeOffset.UtcNow), cancellationToken);
}
}
catch (Exception ex) when (ex is not OperationCanceledException)
{
logger.LogError(ex, "Job {JobId}: its script group memberships could not be applied", payload.JobId);
}
}
+2 -1
View File
@@ -90,7 +90,7 @@ var logSettings = LogSettings.FromConfiguration(
// The last lines in memory too, for Server Logs in the console.
var liveLog = new LiveLog();
builder.Logging.ClearProviders();
builder.Services.AddSerilog(LoggingSetup.CreateLogger(logSettings, "backend", liveLog), dispose: true);
builder.Services.AddSerilog(LoggingSetup.CreateLogger(logSettings, "Server", liveLog), dispose: true);
builder.Services.AddSingleton(new Backend.Logs.ServerLogs(liveLog, logSettings.Directory));
builder.Services.ConfigureHttpJsonOptions(options =>
@@ -157,6 +157,7 @@ builder.Services.AddSingleton(DeviceLifecycleOptions.FromConfiguration(builder.C
builder.Services.AddSingleton<Backend.Groups.InventoryReportCache>();
builder.Services.AddSingleton<Backend.Dashboard.DashboardCache>();
builder.Services.AddScoped<DeviceGroupService>();
builder.Services.AddScoped<Backend.Groups.ScriptGroupMembership>();
builder.Services.AddScoped<ScriptTriggerService>();
builder.Services.AddScoped<Backend.Groups.DeviceRunService>();
+7 -4
View File
@@ -144,6 +144,7 @@ public static class ScriptEndpoints
RestartAfterRun = request.RestartAfterRun ?? RestartAfterRun.Off,
RestartDelaySeconds = request.RestartDelaySeconds ?? 0,
RestartWarningSeconds = request.RestartWarningSeconds ?? 0,
RunAsUser = request.RunAsUser ?? false,
CreatedUtc = now,
UpdatedUtc = now,
CreatedBy = actor,
@@ -220,6 +221,7 @@ public static class ScriptEndpoints
script.RestartAfterRun = request.RestartAfterRun ?? script.RestartAfterRun;
script.RestartDelaySeconds = request.RestartDelaySeconds ?? script.RestartDelaySeconds;
script.RestartWarningSeconds = request.RestartWarningSeconds ?? script.RestartWarningSeconds;
script.RunAsUser = request.RunAsUser ?? script.RunAsUser;
NormalizeOptions(script);
script.UpdatedUtc = DateTimeOffset.UtcNow;
script.UpdatedBy = context.User.Identity?.Name;
@@ -285,15 +287,16 @@ public static class ScriptEndpoints
script.SetWorkingDirectory,
script.RestartAfterRun,
script.RestartDelaySeconds,
script.RestartWarningSeconds);
script.RestartWarningSeconds,
script.RunAsUser);
/// <summary>
/// Set Working Directory needs a staged file: PowerShell 7 stages one only
/// with Run From File (5.1 and Bash always do), so without it the option is off.
/// Set Working Directory needs a staged file: PowerShell 7 stages one only with Run From
/// File or Run As Signed-In User (5.1 and Bash always do), so without either the option is off.
/// </summary>
internal static void NormalizeOptions(ScriptEntity script)
{
if (ParseEngine(script.Language) == ScriptEngine.PowerShell && !script.RunFromFile)
if (ParseEngine(script.Language) == ScriptEngine.PowerShell && !script.RunFromFile && !script.RunAsUser)
{
script.SetWorkingDirectory = false;
}
+6 -4
View File
@@ -40,15 +40,17 @@ public sealed class ShellBridge(
}
/// <summary>
/// Publishes the privileged shell.open command to the agent (<paramref name="shell"/>: a <see cref="ShellKinds"/> value);
/// false when it may not be sent (Require Sealed Agents, and the device does not seal).
/// Publishes the privileged shell.open command to the agent (<paramref name="shell"/>: a <see cref="ShellKinds"/> value;
/// <paramref name="asUser"/>: as the signed-in user); false when it may not be sent (Require Sealed Agents, and the
/// device does not seal).
/// </summary>
public async Task<bool> OpenAsync(ShellBinding binding, int cols, int rows, string? shell, CancellationToken cancellationToken)
public async Task<bool> OpenAsync(
ShellBinding binding, int cols, int rows, string? shell, CancellationToken cancellationToken, bool asUser = false, string? user = null)
{
var envelope = MessageEnvelope.Create(
MessageTypes.CommandShellOpen,
BackendSource,
new ShellOpenCommandPayload(binding.ShellId, cols, rows, shell),
new ShellOpenCommandPayload(binding.ShellId, cols, rows, shell, asUser, asUser ? user : null),
new EndpointRef(EndpointKinds.Agent, binding.ClientId));
if (!await PublishToAgentAsync(binding.ClientId, NatsSubjects.AgentCommandShellOpen(binding.ClientId), envelope, cancellationToken))
+16 -2
View File
@@ -61,6 +61,19 @@ public static class ShellEndpoints
return Results.NotFound();
}
// An older agent would ignore As Signed-In User and start the shell as its own account.
if (request.AsUser && !RunAsUser.Supported(device.AgentVersion))
{
return Results.Problem(statusCode: StatusCodes.Status409Conflict, title: RunAsUser.Unsupported(device.AgentVersion));
}
// A chosen signed-in user: a plain account name (a Windows domain account or a unix name), never a path or a list.
var user = string.IsNullOrWhiteSpace(request.User) ? null : request.User.Trim();
if (user is not null && (!request.AsUser || user.Length > 256 || user.Any(c => char.IsControl(c) || c is '/' or ':' or ',' or '"')))
{
return Results.BadRequest(new { error = "User must name one signed-in user, with Run As Signed-In User." });
}
var shellId = Guid.NewGuid();
var actor = context.User.Identity?.Name;
@@ -75,7 +88,8 @@ public static class ShellEndpoints
await db.SaveChangesAsync(cancellationToken);
var binding = bridge.Register(shellId, clientId, request.BrowserSessionId);
if (!await bridge.OpenAsync(binding, Math.Clamp(request.Cols, 1, 500), Math.Clamp(request.Rows, 1, 200), shell, cancellationToken))
if (!await bridge.OpenAsync(
binding, Math.Clamp(request.Cols, 1, 500), Math.Clamp(request.Rows, 1, 200), shell, cancellationToken, request.AsUser, user))
{
return Results.Problem(
statusCode: StatusCodes.Status409Conflict,
@@ -84,7 +98,7 @@ public static class ShellEndpoints
// The requested shell lives in the audit detail (the session row has no column for it).
await audit.LogAsync(AuditCategories.Shell, "opened", actor,
clientId: clientId, detail: $"shell={shellId} kind={shell}",
clientId: clientId, detail: $"shell={shellId} kind={shell} as={(request.AsUser ? user ?? "signed-in-user" : "agent")}",
remoteIp: Proxy.ClientIp.EffectiveText(context), cancellationToken: cancellationToken);
return Results.Ok(new CreateShellResponse(
+2
View File
@@ -772,6 +772,7 @@ dependencies = [
"async-trait",
"bytes",
"ironrdp-async",
"ironrdp-cliprdr",
"ironrdp-connector",
"ironrdp-core",
"ironrdp-graphics",
@@ -780,6 +781,7 @@ dependencies = [
"ironrdp-server",
"ironrdp-session",
"ironrdp-tokio",
"rayon",
"rcgen",
"serde",
"serde_json",
+9 -1
View File
@@ -21,16 +21,18 @@ ironrdp-server = { version = "0.13", default-features = false, features = ["rayo
ironrdp-pdu = "0.9"
ironrdp-core = "0.2"
ironrdp-rdcleanpath = "0.3.1"
ironrdp-cliprdr = "0.7"
tokio = { version = "1", features = ["rt", "macros", "io-util", "io-std", "sync", "time"] }
tokio-rustls = { version = "0.26", default-features = false, features = ["ring", "tls12"] }
rcgen = { version = "0.14", default-features = false, features = ["ring", "crypto"] }
anyhow = "1"
async-trait = "0.1"
bytes = "1"
rayon = "1"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tracing = "0.1"
tracing-subscriber = { version = "0.3", default-features = false, features = ["fmt", "std"] }
tracing-subscriber = { version = "0.3", default-features = false, features = ["registry", "std"] }
[target.'cfg(windows)'.dependencies.windows]
version = "0.62"
@@ -41,12 +43,18 @@ features = [
"Win32_Graphics_Dxgi",
"Win32_Graphics_Dxgi_Common",
"Win32_Graphics_Gdi",
"Win32_Media_MediaFoundation",
"Win32_Security",
"Win32_System_Com",
"Win32_System_DataExchange",
"Win32_System_Memory",
"Win32_System_LibraryLoader",
"Win32_System_Ole",
"Win32_System_Registry",
"Win32_System_RemoteDesktop",
"Win32_System_StationsAndDesktops",
"Win32_System_SystemInformation",
"Win32_System_Variant",
"Win32_System_Threading",
"Win32_UI_HiDpi",
"Win32_UI_Input_KeyboardAndMouse",
+67 -15
View File
@@ -23,7 +23,7 @@ ExecuteR-Screen --version
| `--stdio` | Required. stdin/stdout carry the WebSocket byte stream (the only transport). |
| `--view-only` | All keyboard/mouse input from the client is dropped here (the relay cannot see inside RDP). |
| `--monitor -1` | Default. All monitors as one virtual desktop. `--monitor N` serves monitor `N` (index from the `state` event). |
| `--max-fps n` | Frame rate cap, 1-60, default 15. |
| `--max-fps n` | Frame rate cap, 1-60, default 30 (video and RDP bitmaps). |
| `--log-level` | Human log verbosity on stderr, default `info`. |
Options come only from the command line. Nothing read from stdin is ever interpreted as an
@@ -53,6 +53,14 @@ Exactly the bytes the IronRDP web client exchanges with an RDCleanPath proxy ove
x224_connection_confirm, [server_certificate])`.
3. Plaintext RDP in both directions (the client skips its own TLS upgrade, as with the gateway).
**Video (H.264).** A browser that can decode H.264 sends `destination` = `screen;video=h264`.
When this host has an H.264 encoder it then writes `EXRMUX01` before the RDCleanPath response,
and from there on both directions are frames `[channel u8][length u32 LE][payload]`: channel 0
carries the bytes above (RDCleanPath response, then RDP), channel 1 the video messages
(`src/video.rs`: `START`, `FRAME` with Annex B H.264, `STOP`; from the browser `ACK`, `KEY`,
`OFF`). Hosts without an encoder, and older hosts (the field is opaque to them), answer plainly,
so every combination of console and agent version works. The relay passes the bytes unchanged.
Refusals: a request without an X.224 connection request (VMConnect) gets `new_http_error(400)`;
a client that does not offer TLS security gets `new_negotiation_error(X.224 failure
SSL_REQUIRED_BY_SERVER)`. Bytes that are not an RDCleanPath PDU get no answer (like the gateway).
@@ -62,7 +70,20 @@ TLS). The username and password the client sends are ignored.
### stderr
Human log lines, plus machine events as single lines `@event <json>`:
Log lines in ExecuteR's one log format (`src/logging.rs`; see the root README, *Log line format*):
```text
[2026-11-16T17:53:40.653Z] - [ScreenHost] - [WARN] - hardware H.264 encoder failed; using software reason="MFT busy"
```
UTC time to the millisecond, the category `ScreenHost` (a dependency's events carry its crate name,
such as `ironrdp_server`), the level (`TRACE` … `ERROR`), the message and the event's fields as
`key=value`. A warning or error that repeats is written once, then counted for 60 s; the window's
end writes one line with `repeated=N window=60s` (the last of them), and a quiet window forgets it.
Counts still open are written before the host exits. The agent logs each such line once, under the
host's category and level with this prefix taken off, so its own file has no second timestamp.
Plus machine events as single lines `@event <json>`:
| Event | When |
|---|---|
@@ -102,7 +123,24 @@ stdout ◄─ (X.224 confirm wrapped │ ▲
handshake, socket or listener is involved. A self-signed certificate (rcgen, in memory, per
process) is what the RDCleanPath response carries; the client only parses its public key.
`server_addr` is reported as `127.0.0.1:3389` (the client ignores it).
* **Encoding.** ironrdp-server negotiates RemoteFX (the web client's default) and falls back to
* **Video.** With a framed stream (above) the capture pump sends the screen as H.264 instead of
RDP bitmaps (`src/video.rs`, `src/platform/windows/h264.rs`); RDP keeps the desktop size,
cursor, input and clipboard. BGRX is converted to NV12 (BT.709, limited range, parallel rows)
and encoded by Media Foundation: the first hardware encoder MFT that takes the size
(asynchronous; NVIDIA, Intel, AMD), else Microsoft's software encoder. Constrained to what the
browser decodes without delay: Baseline profile, no B-frames, low-latency mode, CBR at about
0.1 bit per pixel per frame (1.5-12 Mbit/s). Only changes are encoded, plus three frames after
the screen settles so it sharpens. At most 4 frames may be unacknowledged by the browser (it
acknowledges each frame it draws), so a slow link or decoder skips frames instead of falling
behind. A hardware encoder that fails, or gives no output 15 times in a row, is replaced by the
software one; with no encoder for a size (or any failure there) the host sends `STOP` and RDP
bitmaps serve it; the browser sends `OFF` (no picture 5 s after `START`, or 3 decoder failures
in a row) and RDP bitmaps serve the rest of the session. The browser draws on a canvas over the
RDP canvas with `pointer-events: none`, so the mouse still reaches the RDP client. Measured
(release, this machine's software encoder, no GPU): 1080p with a 400x400 textured block moving
encodes in about 10 ms a frame including NV12 conversion, about 1.6 Mbit/s at 30 fps
(`h264_1080p_moving_block`).
* **Encoding.** Without video, ironrdp-server negotiates RemoteFX (the web client's default) and falls back to
RLE bitmaps. The pump sends dirty regions only (DXGI dirty/move rectangles, or 64x64 tile diffs
for GDI), merged and capped, and ironrdp-server diffs them against its framebuffer again.
Frames are paced by `--max-fps`; the update channel holds at most two frames, so a slow link
@@ -116,16 +154,24 @@ stdout ◄─ (X.224 confirm wrapped │ ▲
screen's aspect ratio (capped at the window's height), so it fills the page without bars below.
* **Pointer.** Cursor shapes are sent as 32-bpp pointer updates using the client pointer cache;
hidden cursors are hidden. The cursor position is not pushed (the browser draws its own pointer).
* **Clipboard: not implemented.** ironrdp-server has a CLIPRDR channel, but writing the Windows
clipboard (`SetClipboardData`) requires a window to own it, which the security rules below forbid.
When added, it must be plain text only, capped at 1 MiB, and disabled with `--view-only`.
* **Clipboard (Windows).** Plain text both ways over CLIPRDR (`src/clipboard.rs`): a copy on either
side is announced to the other, which fetches it (the operator's text is placed on the device as
soon as it is announced, so it is there before they paste). Capped at 1 MiB (UTF-8) each way; no
files or images; no clipboard channel at all with `--view-only`. Device changes are found by
polling the clipboard sequence number (4 per second); writes go through a message-only window
made and destroyed for that one write (see Security 1). The web client needs its clipboard set
up before it connects, or it asks for no clipboard channel (`RemoteScreenView.tsx` waits for it).
Linux: no clipboard yet.
* **Codec.** The IronRDP web client 0.7 offers RemoteFX only (logged as `client bitmap codecs` and
`bitmap codec`), so RDP bitmaps are RemoteFX whatever else the host could do; hence the separate
video channel.
## Platforms
| Platform | Capture | Input | Notes |
|---|---|---|---|
| Windows 10/11 (priority 1) | DXGI Desktop Duplication (dirty + move rects), GDI `BitBlt` fallback (secure desktop if duplication is refused, VMs, rotated screens) | `SendInput`: scancodes incl. extended keys, Unicode, absolute mouse over the virtual desktop (negative origins), wheel, horizontal wheel, X buttons, lock-key sync; Ctrl+Alt+Del via `SendSAS` | Capture and injection threads follow the input desktop (`OpenInputDesktop` + `SetThreadDesktop`): lock screen, UAC prompt and sign-in screen are served when the host runs as SYSTEM in the console session. Per-monitor DPI aware. Tested: unit, in-memory e2e, and a live session over real stdio on this machine. |
| Windows PE (priority 1) | GDI only (no DWM) | `SendInput` | Detected via `HKLM\SYSTEM\CurrentControlSet\Control\MiniNT` (`winpe:true`). Static CRT, no VC++ runtime. Static imports: kernel32, user32, gdi32, advapi32, ntdll, bcrypt, bcryptprimitives, oleaut32, api-ms-win-core-synch-l1-2-0. dxgi/d3d11/sas are loaded at run time only on full Windows. The agent runs as a service in session 0 there too, so it starts the host in the console session (session 0's desktop is never on the screen). |
| Windows PE (priority 1) | GDI only (no DWM); no Media Foundation, so RDP bitmaps (RemoteFX) instead of H.264 | `SendInput` | Detected via `HKLM\SYSTEM\CurrentControlSet\Control\MiniNT` (`winpe:true`). Static CRT, no VC++ runtime. Static imports: kernel32, user32, gdi32, advapi32, ntdll, bcrypt, bcryptprimitives, oleaut32, api-ms-win-core-synch-l1-2-0. dxgi/d3d11/sas and mfplat/ole32 (H.264) are loaded at run time only on full Windows. The agent runs as a service in session 0 there too, so it starts the host in the console session (session 0's desktop is never on the screen). |
| Linux X11 (priority 2) | `GetImage` on the root window + tile diff, monitors from RandR, cursor from XFixes | XTest (keys via evdev keycodes, buttons, wheels) | Pure-Rust X11 client (`x11rb`). Type-checked and clippy-clean for `x86_64-unknown-linux-gnu`; **not run on Linux yet**. No XShm (slower at large sizes), no Unicode typing. |
| Linux Wayland, macOS | `probe` reports `capture:false` with a reason; `serve` exits 2. | | |
@@ -151,22 +197,26 @@ stdout ◄─ (X.224 confirm wrapped │ ▲
ExecuteR-Screen runs as SYSTEM on the user's desktop, so it is treated as an elevation-of-privilege surface:
1. **No windows, no message pump.** The Windows code creates no HWND, hook or message loop
(cursor, capture and input use `GetCursorInfo`, DXGI/GDI and `SendInput`). This is also why
clipboard support is left out (see above).
1. **No lasting windows, no message pump.** Cursor, capture and input use `GetCursorInfo`,
DXGI/GDI and `SendInput`: no HWND, hook or message loop. The one exception is the clipboard
write: `SetClipboardData` needs an owner window after `EmptyClipboard`, so each write creates a
message-only window (default procedure, never pumped), places the text and destroys it at once.
Clipboard changes are polled, not listened for.
2. **DLL search path.** First thing in `main`: `SetDefaultDllDirectories(LOAD_LIBRARY_SEARCH_SYSTEM32)`
and `SetDllDirectoryW("")`. The executable is linked with `/DEPENDENTLOADFLAG:0x800`, so its static
imports also resolve from System32 only. Run-time DLLs (dxgi, d3d11, sas) are loaded with
`LoadLibraryExW(..., LOAD_LIBRARY_SEARCH_SYSTEM32)`. Nothing is loaded from the current directory,
`LoadLibraryExW(..., LOAD_LIBRARY_SEARCH_SYSTEM32)`, as are mfplat and ole32 for H.264 (Media
Foundation and COM, multithreaded apartment on the capture thread: no windows). Nothing is loaded from the current directory,
`PATH` or the user profile.
3. **stdin/stdout carry only RDCleanPath + RDP.** No file path, command or option is ever taken
3. **stdin/stdout carry only RDCleanPath + RDP** (and, framed beside them, video frames out and
acknowledgements in: fixed message types, frames capped at 1 MiB from the browser). No file path, command or option is ever taken
from the byte stream; the RDCleanPath fields are opaque and only logged (the token never).
The request is size-capped (64 KiB). Options come only from the agent's command line.
4. **No IPC objects or persistence.** No named pipes, no sockets at all (the RDP acceptor runs on
stdio; no loopback listener exists), no files, no registry writes (the only registry access is
a read of the WinPE marker key). The TLS key pair lives in memory only.
5. **Clipboard.** Not implemented. Any future implementation must be plain text only, size-capped
(1 MiB), and disabled in `--view-only`.
5. **Clipboard.** Plain text only (CF_UNICODETEXT), 1 MiB cap each way, off in `--view-only`
(no CLIPRDR channel is offered). File and image formats are refused.
6. **View-only** is enforced in this process: every keyboard and mouse event is dropped before mapping.
## Build
@@ -178,7 +228,8 @@ cd src/ScreenHost
cargo build --release # target/release/ExecuteR-Screen.exe
cargo test # unit + e2e + live stdio test (skips without a capturable screen)
cargo clippy --all-targets -- -D warnings
cargo test --release --test e2e -- --ignored --nocapture # 1080p throughput measurement
cargo test --release --test e2e -- --ignored --nocapture # 1080p throughput measurement (RemoteFX)
cargo test --release --lib h264_1080p -- --ignored --nocapture # 1080p H.264 encode measurement
```
`.cargo/config.toml` sets `-C target-feature=+crt-static` for the Windows MSVC targets (no VC++
@@ -213,6 +264,7 @@ Top-level dependencies (all permissive):
| rustls (via tokio-rustls) | Apache-2.0 OR ISC OR MIT | TLS types for the acceptor |
| ring | Apache-2.0 AND ISC | crypto provider |
| rcgen | MIT OR Apache-2.0 | self-signed certificate |
| rayon | MIT OR Apache-2.0 | parallel NV12 conversion |
| windows (Windows) | MIT OR Apache-2.0 | Win32 API |
| x11rb (Linux) | MIT OR Apache-2.0 | X11 protocol |
+12 -1
View File
@@ -133,6 +133,8 @@ pub type UpdateBatch = Vec<DisplayUpdate>;
pub struct PumpConfig {
pub max_fps: u32,
/// H.264 video, when the host can encode it: used once the browser takes it.
pub video: Option<crate::video::VideoPath>,
}
/// Number of client pointer-cache slots we use (clients advertise at least 25 for the
@@ -180,7 +182,7 @@ pub fn run_pump(
mut source: Box<dyn ScreenSource>,
tx: mpsc::Sender<UpdateBatch>,
ctl: Arc<PumpControl>,
cfg: PumpConfig,
mut cfg: PumpConfig,
mut on_state: impl FnMut(&SourceState),
mut on_origin: impl FnMut(i32, i32),
) {
@@ -258,7 +260,16 @@ pub fn run_pump(
if !fits {
// Layout changed under us; the next poll_state will resize. Ask for a full frame then.
ctl.full_refresh.store(true, Ordering::Relaxed);
} else if let Some(video) = cfg.video.as_mut().filter(|v| v.handles(&frame)) {
// Video carries the picture; RDP keeps the size, the cursor and input.
let changed = full || !matches!(captured, Capture::Unchanged);
if !video.tick(&frame, changed) {
ctl.full_refresh.store(true, Ordering::Relaxed);
}
sent_first_frame = true;
} else {
// Video stopped carrying the picture (the browser gave up on it): a complete frame now.
let full = full || cfg.video.as_mut().is_some_and(crate::video::VideoPath::hand_back);
let rects = if full {
vec![bounds]
} else {
+2 -2
View File
@@ -45,7 +45,7 @@ pub struct ServeArgs {
pub log_level: LogLevel,
}
pub const DEFAULT_MAX_FPS: u32 = 15;
pub const DEFAULT_MAX_FPS: u32 = 30;
pub const MAX_MAX_FPS: u32 = 60;
#[derive(Clone, Debug, PartialEq, Eq)]
@@ -187,7 +187,7 @@ mod tests {
let s = serve(&["--stdio"]).unwrap();
assert_eq!(
s,
ServeArgs { view_only: false, monitor: MonitorSelection::All, max_fps: 15, log_level: LogLevel::Info }
ServeArgs { view_only: false, monitor: MonitorSelection::All, max_fps: 30, log_level: LogLevel::Info }
);
}
+265
View File
@@ -0,0 +1,265 @@
//! Text clipboard between the operator and the device, over RDP's clipboard channel
//! (CLIPRDR). Copying on either side announces text to the other; the other side asks for
//! it when it pastes (the web client: when its tab regains focus). Text only (Unicode); no
//! files or images; at most [`MAX_TEXT_BYTES`] either way. Only in control sessions: a
//! view-only session has no clipboard channel at all.
use std::sync::{Arc, Mutex};
use ironrdp_cliprdr::backend::{ClipboardMessage, CliprdrBackend, CliprdrBackendFactory};
use ironrdp_cliprdr::pdu::{
ClipboardFormat, ClipboardFormatId, ClipboardGeneralCapabilityFlags, FileContentsRequest, FileContentsResponse,
FormatDataRequest, FormatDataResponse, LockDataId, OwnedFormatDataResponse,
};
use ironrdp_server::{CliprdrServerFactory, ServerEvent, ServerEventSender};
use tokio::sync::mpsc::UnboundedSender;
/// Text larger than this (UTF-8 bytes) is neither offered nor taken: a clipboard is for
/// snippets, files have their own tools (README, Security).
pub const MAX_TEXT_BYTES: usize = 1024 * 1024;
/// The device's clipboard, as the bridge needs it.
pub trait OsClipboard: Send + Sync {
/// The clipboard's text, if it holds any.
fn read_text(&self) -> Option<String>;
/// Replaces the clipboard with `text`. The change this makes is not reported back
/// through `watch`.
fn write_text(&self, text: &str);
/// Calls `changed` whenever something else changes the clipboard.
fn watch(&self, changed: Box<dyn Fn() + Send + Sync>);
}
/// What the server-side bridge shares with every backend it builds.
struct Shared {
os: Arc<dyn OsClipboard>,
sender: Mutex<Option<UnboundedSender<ServerEvent>>>,
}
impl Shared {
fn send(&self, message: ClipboardMessage) {
if let Some(sender) = self.sender.lock().ok().and_then(|s| s.clone()) {
let _ = sender.send(ServerEvent::Clipboard(message));
}
}
/// Tells the client the device has text to paste.
fn announce(&self) {
if self.os.read_text().is_some_and(|t| !t.is_empty() && t.len() <= MAX_TEXT_BYTES) {
self.send(ClipboardMessage::SendInitiateCopy(vec![ClipboardFormat::new(
ClipboardFormatId::CF_UNICODETEXT,
)]));
}
}
}
/// Builds the clipboard channel for a session on top of the device's clipboard.
pub struct ClipboardFactory {
shared: Arc<Shared>,
}
impl ClipboardFactory {
pub fn new(os: Arc<dyn OsClipboard>) -> Self {
let shared = Arc::new(Shared { os, sender: Mutex::new(None) });
let watcher = Arc::downgrade(&shared);
shared.os.watch(Box::new(move || {
if let Some(shared) = watcher.upgrade() {
tracing::debug!("device clipboard changed");
shared.announce();
}
}));
Self { shared }
}
}
impl CliprdrBackendFactory for ClipboardFactory {
fn build_cliprdr_backend(&self) -> Box<dyn CliprdrBackend> {
Box::new(ClipboardBackend { shared: Arc::clone(&self.shared) })
}
}
impl ServerEventSender for ClipboardFactory {
fn set_sender(&mut self, sender: UnboundedSender<ServerEvent>) {
if let Ok(mut slot) = self.shared.sender.lock() {
*slot = Some(sender);
}
}
}
impl CliprdrServerFactory for ClipboardFactory {}
struct ClipboardBackend {
shared: Arc<Shared>,
}
impl core::fmt::Debug for ClipboardBackend {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
f.write_str("ClipboardBackend")
}
}
ironrdp_core::impl_as_any!(ClipboardBackend);
impl CliprdrBackend for ClipboardBackend {
fn temporary_directory(&self) -> &str {
""
}
fn client_capabilities(&self) -> ClipboardGeneralCapabilityFlags {
// Text only: no file streams, no locking.
ClipboardGeneralCapabilityFlags::empty()
}
fn on_ready(&mut self) {
self.shared.announce();
}
fn on_request_format_list(&mut self) {
self.shared.announce();
}
fn on_process_negotiated_capabilities(&mut self, _capabilities: ClipboardGeneralCapabilityFlags) {}
fn on_remote_copy(&mut self, available_formats: &[ClipboardFormat]) {
// The operator copied: fetch the text now so it is on the device before they paste.
if available_formats.iter().any(|f| f.id == ClipboardFormatId::CF_UNICODETEXT) {
self.shared.send(ClipboardMessage::SendInitiatePaste(ClipboardFormatId::CF_UNICODETEXT));
}
}
fn on_format_data_request(&mut self, request: FormatDataRequest) {
let reply =
match (request.format == ClipboardFormatId::CF_UNICODETEXT).then(|| self.shared.os.read_text()).flatten() {
Some(text) if text.len() <= MAX_TEXT_BYTES => OwnedFormatDataResponse::new_unicode_string(&text),
_ => OwnedFormatDataResponse::new_error(),
};
self.shared.send(ClipboardMessage::SendFormatData(reply));
}
fn on_format_data_response(&mut self, response: FormatDataResponse<'_>) {
if response.is_error() {
return;
}
match response.to_unicode_string() {
Ok(text) if text.len() <= MAX_TEXT_BYTES => {
tracing::debug!(chars = text.chars().count(), "operator clipboard text placed on the device");
self.shared.os.write_text(&text);
}
Ok(_) => tracing::info!("operator clipboard text too large; not placed on the device"),
Err(e) => tracing::debug!(error = %e, "operator clipboard data was not text"),
}
}
fn on_file_contents_request(&mut self, request: FileContentsRequest) {
// No file copy: answer so the client does not wait.
self.shared
.send(ClipboardMessage::SendFileContentsResponse(FileContentsResponse::new_error(request.stream_id)));
}
fn on_file_contents_response(&mut self, _response: FileContentsResponse<'_>) {}
fn on_lock(&mut self, _data_id: LockDataId) {}
fn on_unlock(&mut self, _data_id: LockDataId) {}
}
#[cfg(test)]
mod tests {
use super::*;
use tokio::sync::mpsc;
#[derive(Default)]
struct FakeClipboard {
text: Mutex<Option<String>>,
watcher: Mutex<Option<Box<dyn Fn() + Send + Sync>>>,
}
impl FakeClipboard {
/// Something on the device copied.
fn local_copy(&self, text: &str) {
*self.text.lock().unwrap() = Some(text.to_owned());
if let Some(changed) = self.watcher.lock().unwrap().as_ref() {
changed();
}
}
}
impl OsClipboard for FakeClipboard {
fn read_text(&self) -> Option<String> {
self.text.lock().unwrap().clone()
}
fn write_text(&self, text: &str) {
*self.text.lock().unwrap() = Some(text.to_owned());
}
fn watch(&self, changed: Box<dyn Fn() + Send + Sync>) {
*self.watcher.lock().unwrap() = Some(changed);
}
}
fn setup() -> (Arc<FakeClipboard>, Box<dyn CliprdrBackend>, mpsc::UnboundedReceiver<ServerEvent>) {
let os = Arc::new(FakeClipboard::default());
let mut factory = ClipboardFactory::new(Arc::clone(&os) as Arc<dyn OsClipboard>);
let (tx, rx) = mpsc::unbounded_channel();
factory.set_sender(tx);
let backend = factory.build_cliprdr_backend();
// The factory must stay alive for the watcher (the server keeps it for the session).
std::mem::forget(factory);
(os, backend, rx)
}
fn next(rx: &mut mpsc::UnboundedReceiver<ServerEvent>) -> ClipboardMessage {
match rx.try_recv().expect("an event") {
ServerEvent::Clipboard(m) => m,
other => panic!("not a clipboard event: {other:?}"),
}
}
#[test]
fn device_copy_is_announced_and_served_as_text() {
let (os, mut backend, mut rx) = setup();
os.local_copy("héllo device");
assert!(
matches!(next(&mut rx), ClipboardMessage::SendInitiateCopy(f) if f[0].id == ClipboardFormatId::CF_UNICODETEXT)
);
backend.on_format_data_request(FormatDataRequest { format: ClipboardFormatId::CF_UNICODETEXT });
let ClipboardMessage::SendFormatData(reply) = next(&mut rx) else { panic!("no data") };
assert_eq!(reply.to_unicode_string().unwrap(), "héllo device");
}
#[test]
fn operator_copy_is_fetched_and_placed_on_the_device() {
let (os, mut backend, mut rx) = setup();
backend.on_remote_copy(&[ClipboardFormat::new(ClipboardFormatId::CF_UNICODETEXT)]);
assert!(
matches!(next(&mut rx), ClipboardMessage::SendInitiatePaste(id) if id == ClipboardFormatId::CF_UNICODETEXT)
);
let data = OwnedFormatDataResponse::new_unicode_string("from the operator");
backend.on_format_data_response(data);
assert_eq!(os.read_text().as_deref(), Some("from the operator"));
}
#[test]
fn text_over_the_cap_is_neither_offered_nor_taken() {
let (os, mut backend, mut rx) = setup();
let big = "x".repeat(MAX_TEXT_BYTES + 1);
os.local_copy(&big);
assert!(rx.try_recv().is_err(), "too large to offer");
backend.on_format_data_response(OwnedFormatDataResponse::new_unicode_string(&big));
assert_eq!(os.read_text().map(|t| t.len()), Some(MAX_TEXT_BYTES + 1), "the device keeps its own text");
}
#[test]
fn nothing_to_offer_and_other_formats_are_refused() {
let (_os, mut backend, mut rx) = setup();
backend.on_ready();
assert!(rx.try_recv().is_err(), "an empty clipboard is not announced");
backend.on_remote_copy(&[ClipboardFormat::new(ClipboardFormatId::new(2))]);
assert!(rx.try_recv().is_err(), "a bitmap is not fetched");
backend.on_format_data_request(FormatDataRequest { format: ClipboardFormatId::CF_UNICODETEXT });
let ClipboardMessage::SendFormatData(reply) = next(&mut rx) else { panic!("no reply") };
assert!(reply.is_error());
}
}
+12 -2
View File
@@ -6,16 +6,21 @@
pub mod capture;
pub mod cli;
pub mod clipboard;
pub mod events;
pub mod geometry;
pub mod input;
pub mod keymap;
pub mod logging;
pub mod mux;
pub mod platform;
pub mod rdcleanpath;
pub mod session;
pub mod tls;
pub mod video;
/// Initialises stderr logging at the given level.
/// Initialises stderr logging at the given level, in ExecuteR's one log format with
/// repeated warnings and errors bounded (see [`logging`]).
pub fn init_logging(level: cli::LogLevel) {
use tracing_subscriber::filter::LevelFilter;
let filter = match level {
@@ -24,5 +29,10 @@ pub fn init_logging(level: cli::LogLevel) {
cli::LogLevel::Info => LevelFilter::INFO,
cli::LogLevel::Debug => LevelFilter::DEBUG,
};
let _ = tracing_subscriber::fmt().with_writer(std::io::stderr).with_ansi(false).with_max_level(filter).try_init();
logging::init(filter);
}
/// Writes the repeat counts still open; call before the process exits.
pub fn flush_logging() {
logging::flush();
}
+515
View File
@@ -0,0 +1,515 @@
//! The host's log lines on stderr, in ExecuteR's one log format:
//!
//! ```text
//! [2026-11-16T17:53:40.653Z] - [ScreenHost] - [WARN] - hardware H.264 encoder failed; using software reason="MFT busy"
//! ```
//!
//! UTC to the millisecond; the category `ScreenHost` (or the crate an event comes from, such as
//! `ironrdp_server`); TRACE, DEBUG, INFO, WARN or ERROR; the message, then the event's fields as
//! `key=value` (a value with whitespace, `=` or `"` double-quoted). The agent reads these lines
//! from stderr and logs each again under the host's category and level, without this prefix.
//!
//! A warning or error that repeats is written once; the same one again within a minute is
//! counted, and when the minute ends with any counted ONE line says so: the last of them with
//! `repeated=N window=60s`. A quiet minute forgets it (see [`Throttle`]).
use std::collections::HashMap;
use std::fmt::{self, Write as _};
use std::io::Write as _;
use std::sync::{Arc, Mutex, OnceLock};
use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
use tracing::field::{Field, Visit};
use tracing::{Event, Level, Subscriber};
use tracing_subscriber::layer::{Context, Layer};
/// The category of the host's own lines.
pub const CATEGORY: &str = "ScreenHost";
/// How long repeats are counted before one summary line.
pub const REPEAT_WINDOW: Duration = Duration::from_secs(60);
/// How many distinct warnings and errors are tracked at once (the oldest goes first).
pub const MAX_KEYS: usize = 1000;
/// `2026-11-16T17:53:40.653Z`.
pub fn format_timestamp(time: SystemTime) -> String {
let since = time.duration_since(UNIX_EPOCH).unwrap_or_default();
let secs = since.as_secs();
let (year, month, day) = civil_from_days((secs / 86_400) as i64);
let rest = secs % 86_400;
format!(
"{year:04}-{month:02}-{day:02}T{:02}:{:02}:{:02}.{:03}Z",
rest / 3600,
rest % 3600 / 60,
rest % 60,
since.subsec_millis()
)
}
/// Days since 1970-01-01 as a proleptic Gregorian date (H. Hinnant's `civil_from_days`).
fn civil_from_days(days: i64) -> (i64, u32, u32) {
let z = days + 719_468;
let era = z.div_euclid(146_097);
let doe = z.rem_euclid(146_097);
let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365;
let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
let mp = (5 * doy + 2) / 153;
let day = (doy - (153 * mp + 2) / 5 + 1) as u32;
let month = (if mp < 10 { mp + 3 } else { mp - 9 }) as u32;
let year = yoe + era * 400 + i64::from(month <= 2);
(year, month, day)
}
/// The level as the line spells it.
pub fn level_name(level: Level) -> &'static str {
match level {
Level::TRACE => "TRACE",
Level::DEBUG => "DEBUG",
Level::INFO => "INFO",
Level::WARN => "WARN",
_ => "ERROR",
}
}
/// `ScreenHost` for the host's own code, the crate's name for a dependency's (`ironrdp_server`).
pub fn category(target: &str) -> String {
let krate = target.split("::").next().unwrap_or_default();
if krate.is_empty() || krate.to_ascii_lowercase().starts_with("executer_screen") {
CATEGORY.to_owned()
} else {
krate.to_owned()
}
}
/// A field value as a line shows it: bare, or double-quoted (escaping `"` and control
/// characters) when it is empty or holds whitespace, `=` or `"`.
pub fn quote(value: &str) -> String {
if !value.is_empty() && !value.chars().any(|c| c.is_whitespace() || c == '=' || c == '"' || c.is_control()) {
return value.to_owned();
}
let mut quoted = String::with_capacity(value.len() + 2);
quoted.push('"');
for c in value.chars() {
match c {
'"' => quoted.push_str("\\\""),
'\n' => quoted.push_str("\\n"),
'\r' => quoted.push_str("\\r"),
'\t' => quoted.push_str("\\t"),
c if c.is_control() => {
let _ = write!(quoted, "\\u{:04x}", u32::from(c));
}
c => quoted.push(c),
}
}
quoted.push('"');
quoted
}
/// What one line says, before its time is put on it.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Line {
pub level: Level,
pub category: String,
/// The message and its `key=value` fields.
pub text: String,
}
impl Line {
/// The whole line, without its newline.
pub fn format(&self, time: SystemTime) -> String {
format!("[{}] - [{}] - [{}] - {}", format_timestamp(time), self.category, level_name(self.level), self.text)
}
}
/// Collects an event's message and its fields as `key=value`.
#[derive(Default)]
struct Fields {
message: String,
rest: String,
}
impl Fields {
fn push(&mut self, field: &Field, value: &str) {
if field.name() == "message" {
self.message.push_str(value);
} else {
let _ = write!(self.rest, " {}={}", field.name(), quote(value));
}
}
fn into_text(self) -> String {
self.message + &self.rest
}
}
impl Visit for Fields {
fn record_str(&mut self, field: &Field, value: &str) {
self.push(field, value);
}
fn record_debug(&mut self, field: &Field, value: &dyn fmt::Debug) {
self.push(field, &format!("{value:?}"));
}
}
/// What tells one warning from another: its level and where it is logged (target and callsite).
pub type Key = (Level, &'static str, &'static str);
struct Entry {
start: Instant,
order: u64,
suppressed: u64,
last: Option<Line>,
}
/// Bounds repeated warnings and errors: the first is written, the same one again within the
/// window is counted, the window's end writes one summary of what was counted and starts the
/// next, and a window with nothing counted forgets the key. Time comes in as an argument.
pub struct Throttle {
window: Duration,
max_keys: usize,
entries: HashMap<Key, Entry>,
order: u64,
}
impl Throttle {
pub fn new(window: Duration, max_keys: usize) -> Self {
Self { window, max_keys: max_keys.max(1), entries: HashMap::new(), order: 0 }
}
/// How many keys are tracked now.
pub fn tracked(&self) -> usize {
self.entries.len()
}
/// A warning or error at `now`: the lines to write (summaries first, then the line itself
/// unless it is held back as a repeat).
pub fn admit(&mut self, key: Key, now: Instant, line: Line) -> Vec<Line> {
let mut out = Vec::new();
if let Some(entry) = self.entries.get_mut(&key)
&& now.saturating_duration_since(entry.start) >= self.window
{
match Self::close(entry, now, self.window) {
Some(summary) => out.push(summary),
None => {
self.entries.remove(&key);
}
}
}
if let Some(entry) = self.entries.get_mut(&key) {
entry.suppressed += 1;
entry.last = Some(line);
return out;
}
if self.entries.len() >= self.max_keys
&& let Some(oldest) = self.entries.iter().min_by_key(|(_, e)| e.order).map(|(k, _)| *k)
&& let Some(evicted) = self.entries.remove(&oldest)
&& let Some(summary) = Self::summary(&evicted, self.window)
{
out.push(summary);
}
self.order += 1;
self.entries.insert(key, Entry { start: now, order: self.order, suppressed: 0, last: None });
out.push(line);
out
}
/// Ends every window that is over at `now`: the summaries to write.
pub fn sweep(&mut self, now: Instant) -> Vec<Line> {
let window = self.window;
let mut out = Vec::new();
self.entries.retain(|_, entry| {
if now.saturating_duration_since(entry.start) < window {
return true;
}
match Self::close(entry, now, window) {
Some(summary) => {
out.push(summary);
true
}
None => false,
}
});
out
}
/// Every count still open (at exit), oldest key first; nothing is tracked afterwards.
pub fn drain(&mut self) -> Vec<Line> {
let mut entries: Vec<Entry> = self.entries.drain().map(|(_, e)| e).collect();
entries.sort_by_key(|e| e.order);
entries.iter().filter_map(|e| Self::summary(e, self.window)).collect()
}
fn close(entry: &mut Entry, now: Instant, window: Duration) -> Option<Line> {
let summary = Self::summary(entry, window)?;
entry.start = now;
entry.suppressed = 0;
entry.last = None;
Some(summary)
}
fn summary(entry: &Entry, window: Duration) -> Option<Line> {
let last = entry.last.as_ref().filter(|_| entry.suppressed > 0)?;
let mut line = last.clone();
let _ = write!(line.text, " repeated={} window={}", entry.suppressed, format_window(window));
Some(line)
}
}
/// `60s`, `1.5s`, `250ms`.
pub fn format_window(window: Duration) -> String {
if window >= Duration::from_secs(1) {
let secs = window.as_secs_f64();
if secs.fract() == 0.0 { format!("{}s", window.as_secs()) } else { format!("{secs}s") }
} else {
format!("{}ms", window.as_millis())
}
}
type LineSink = Box<dyn Fn(&str) + Send + Sync>;
/// Where lines go (stderr, or a test's sink) and the repeat throttle in front of it.
pub struct HostLog {
throttle: Mutex<Throttle>,
sink: LineSink,
}
impl HostLog {
pub fn new(sink: LineSink) -> Self {
Self { throttle: Mutex::new(Throttle::new(REPEAT_WINDOW, MAX_KEYS)), sink }
}
/// Writes to stderr, one whole line per write.
pub fn stderr() -> Self {
Self::new(Box::new(|line| {
let mut stderr = std::io::stderr().lock();
let _ = stderr.write_all(format!("{line}\n").as_bytes());
let _ = stderr.flush();
}))
}
fn throttle(&self) -> std::sync::MutexGuard<'_, Throttle> {
self.throttle.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
}
fn write(&self, lines: Vec<Line>) {
let now = SystemTime::now();
for line in lines {
(self.sink)(&line.format(now));
}
}
/// One event's line: warnings and errors through the throttle, the rest straight out.
pub fn log(&self, key: Key, line: Line) {
if matches!(line.level, Level::WARN | Level::ERROR) {
let lines = self.throttle().admit(key, Instant::now(), line);
self.write(lines);
} else {
self.write(vec![line]);
}
}
/// Writes the summaries of windows that are over.
pub fn sweep(&self) {
let lines = self.throttle().sweep(Instant::now());
self.write(lines);
}
/// Writes every count still open (before the process exits).
pub fn flush(&self) {
let lines = self.throttle().drain();
self.write(lines);
}
}
/// The `tracing` layer that writes each event through a [`HostLog`].
pub struct HostLayer(pub Arc<HostLog>);
impl<S: Subscriber> Layer<S> for HostLayer {
fn on_event(&self, event: &Event<'_>, _ctx: Context<'_, S>) {
let metadata = event.metadata();
let mut fields = Fields::default();
event.record(&mut fields);
let line = Line { level: *metadata.level(), category: category(metadata.target()), text: fields.into_text() };
self.0.log((*metadata.level(), metadata.target(), metadata.name()), line);
}
}
static HOST_LOG: OnceLock<Arc<HostLog>> = OnceLock::new();
/// Installs stderr logging at `filter`, with a thread that writes repeat summaries as windows end.
pub fn init(filter: tracing_subscriber::filter::LevelFilter) {
use tracing_subscriber::layer::SubscriberExt as _;
use tracing_subscriber::util::SubscriberInitExt as _;
let log = Arc::clone(HOST_LOG.get_or_init(|| Arc::new(HostLog::stderr())));
if tracing_subscriber::registry().with(filter).with(HostLayer(Arc::clone(&log))).try_init().is_ok() {
let _ = std::thread::Builder::new().name("log-repeats".into()).spawn(move || {
loop {
std::thread::sleep(Duration::from_secs(1));
log.sweep();
}
});
}
}
/// Writes every repeat count still open; call before the process exits.
pub fn flush() {
if let Some(log) = HOST_LOG.get() {
log.flush();
}
}
#[cfg(test)]
mod tests {
use super::*;
use tracing_subscriber::layer::SubscriberExt as _;
fn line(level: Level, text: &str) -> Line {
Line { level, category: CATEGORY.to_owned(), text: text.to_owned() }
}
fn texts(lines: &[Line]) -> Vec<&str> {
lines.iter().map(|l| l.text.as_str()).collect()
}
const A: Key = (Level::WARN, "executer_screen::video", "event src/video.rs:94");
const B: Key = (Level::WARN, "executer_screen::video", "event src/video.rs:245");
const C: Key = (Level::ERROR, "executer_screen::session", "event src/session.rs:70");
#[test]
fn timestamps_are_utc_iso_with_milliseconds() {
assert_eq!(format_timestamp(UNIX_EPOCH), "1970-01-01T00:00:00.000Z");
assert_eq!(format_timestamp(UNIX_EPOCH + Duration::from_millis(1_794_851_620_653)), "2026-11-16T17:53:40.653Z");
assert_eq!(format_timestamp(UNIX_EPOCH + Duration::from_millis(1_709_251_199_999)), "2024-02-29T23:59:59.999Z");
assert_eq!(format_timestamp(UNIX_EPOCH + Duration::from_secs(951_868_800)), "2000-03-01T00:00:00.000Z");
}
#[test]
fn a_line_is_time_category_level_message() {
let l = Line { level: Level::WARN, category: "ScreenHost".into(), text: "slow reason=\"a b\"".into() };
assert_eq!(
l.format(UNIX_EPOCH + Duration::from_millis(1_794_851_620_653)),
"[2026-11-16T17:53:40.653Z] - [ScreenHost] - [WARN] - slow reason=\"a b\""
);
assert_eq!(level_name(Level::TRACE), "TRACE");
assert_eq!(level_name(Level::DEBUG), "DEBUG");
assert_eq!(level_name(Level::INFO), "INFO");
assert_eq!(level_name(Level::ERROR), "ERROR");
}
#[test]
fn values_are_quoted_only_when_they_must_be() {
assert_eq!(quote("plain"), "plain");
assert_eq!(quote("C:\\Windows"), "C:\\Windows");
assert_eq!(quote("two words"), "\"two words\"");
assert_eq!(quote("a=b"), "\"a=b\"");
assert_eq!(quote("say \"hi\""), "\"say \\\"hi\\\"\"");
assert_eq!(quote("line\nnext"), "\"line\\nnext\"");
assert_eq!(quote(""), "\"\"");
}
#[test]
fn the_category_is_screenhost_or_the_crate() {
assert_eq!(category("executer_screen::platform::windows::dxgi"), "ScreenHost");
assert_eq!(category("ExecuteR_Screen"), "ScreenHost");
assert_eq!(category("ironrdp_server::server"), "ironrdp_server");
assert_eq!(category(""), "ScreenHost");
}
#[test]
fn the_window_reads_short() {
assert_eq!(format_window(Duration::from_secs(60)), "60s");
assert_eq!(format_window(Duration::from_millis(1500)), "1.5s");
assert_eq!(format_window(Duration::from_millis(250)), "250ms");
}
#[test]
fn the_first_is_written_repeats_are_counted_and_the_window_ends_with_one_summary() {
let mut throttle = Throttle::new(REPEAT_WINDOW, MAX_KEYS);
let t0 = Instant::now();
assert_eq!(texts(&throttle.admit(A, t0, line(Level::WARN, "slow 1"))), ["slow 1"]);
for i in 2..=5 {
assert!(throttle.admit(A, t0 + Duration::from_secs(i), line(Level::WARN, &format!("slow {i}"))).is_empty());
}
assert!(throttle.sweep(t0 + Duration::from_secs(59)).is_empty());
assert_eq!(texts(&throttle.sweep(t0 + Duration::from_secs(60))), ["slow 5 repeated=4 window=60s"]);
}
#[test]
fn it_keeps_summarizing_once_per_window_and_a_quiet_window_starts_over() {
let mut throttle = Throttle::new(REPEAT_WINDOW, MAX_KEYS);
let t0 = Instant::now();
throttle.admit(C, t0, line(Level::ERROR, "broke 1"));
throttle.admit(C, t0, line(Level::ERROR, "broke 2"));
assert_eq!(texts(&throttle.sweep(t0 + REPEAT_WINDOW)), ["broke 2 repeated=1 window=60s"]);
let t1 = t0 + REPEAT_WINDOW;
assert!(throttle.admit(C, t1, line(Level::ERROR, "broke 3")).is_empty());
assert!(throttle.admit(C, t1, line(Level::ERROR, "broke 4")).is_empty());
assert_eq!(texts(&throttle.sweep(t1 + REPEAT_WINDOW)), ["broke 4 repeated=2 window=60s"]);
let t2 = t1 + REPEAT_WINDOW;
assert!(throttle.sweep(t2 + REPEAT_WINDOW).is_empty());
assert_eq!(throttle.tracked(), 0);
assert_eq!(texts(&throttle.admit(C, t2 + REPEAT_WINDOW, line(Level::ERROR, "broke 5"))), ["broke 5"]);
}
#[test]
fn a_repeat_after_the_window_without_a_sweep_gets_its_summary_first() {
let mut throttle = Throttle::new(REPEAT_WINDOW, MAX_KEYS);
let t0 = Instant::now();
throttle.admit(A, t0, line(Level::WARN, "slow 1"));
throttle.admit(A, t0, line(Level::WARN, "slow 2"));
let later = t0 + REPEAT_WINDOW + Duration::from_secs(1);
assert_eq!(texts(&throttle.admit(A, later, line(Level::WARN, "slow 3"))), ["slow 2 repeated=1 window=60s"]);
assert_eq!(texts(&throttle.drain()), ["slow 3 repeated=1 window=60s"]);
}
#[test]
fn keys_tell_events_apart_and_the_table_is_bounded() {
let mut throttle = Throttle::new(REPEAT_WINDOW, 2);
let t0 = Instant::now();
assert_eq!(texts(&throttle.admit(A, t0, line(Level::WARN, "a 1"))), ["a 1"]);
assert!(throttle.admit(A, t0, line(Level::WARN, "a 2")).is_empty());
assert_eq!(texts(&throttle.admit(B, t0, line(Level::WARN, "b 1"))), ["b 1"]);
assert_eq!(texts(&throttle.admit(C, t0, line(Level::ERROR, "c 1"))), ["a 2 repeated=1 window=60s", "c 1"]);
assert_eq!(throttle.tracked(), 2);
}
#[test]
fn the_layer_writes_the_format_and_bounds_repeats() {
let written = Arc::new(Mutex::new(Vec::<String>::new()));
let sink = Arc::clone(&written);
let log = Arc::new(HostLog::new(Box::new(move |l| sink.lock().unwrap().push(l.to_owned()))));
let subscriber = tracing_subscriber::registry().with(HostLayer(Arc::clone(&log)));
tracing::subscriber::with_default(subscriber, || {
tracing::info!(monitor = ?Some(1), name = "DISPLAY 1", "starting screen host");
for count in 0..3 {
tracing::warn!(reason = "MFT busy", count, "hardware H.264 encoder failed; using software");
}
});
log.flush();
let lines = written.lock().unwrap().clone();
assert_eq!(lines.len(), 3, "{lines:?}");
assert!(
lines[0].ends_with("] - [ScreenHost] - [INFO] - starting screen host monitor=Some(1) name=\"DISPLAY 1\""),
"{}",
lines[0]
);
assert!(lines[0].starts_with('['));
assert!(
lines[1].ends_with(
"] - [ScreenHost] - [WARN] - hardware H.264 encoder failed; using software reason=\"MFT busy\" count=0"
),
"{}",
lines[1]
);
assert!(lines[2].ends_with(" reason=\"MFT busy\" count=2 repeated=2 window=60s"), "{}", lines[2]);
}
}
+27 -1
View File
@@ -11,6 +11,7 @@ use executer_screen::input::{CoordMap, GatedInput};
use executer_screen::platform::{self, SourceError};
use executer_screen::session::{self, SessionEnd};
use executer_screen::tls;
use executer_screen::video::{VideoControl, VideoPath};
const EXIT_OK: u8 = 0;
const EXIT_ERROR: u8 = 1;
@@ -41,6 +42,7 @@ fn main() -> ExitCode {
Command::Probe { log_level } => {
executer_screen::init_logging(log_level);
let report = platform::probe();
executer_screen::flush_logging();
match serde_json::to_string(&report) {
Ok(json) => println!("{json}"),
Err(e) => {
@@ -53,6 +55,7 @@ fn main() -> ExitCode {
Command::Serve(args) => {
executer_screen::init_logging(args.log_level);
let code = serve(&args);
executer_screen::flush_logging();
// Exit right away: a blocking stdin read must not keep the process alive.
std::process::exit(i32::from(code));
}
@@ -90,6 +93,18 @@ fn serve(args: &ServeArgs) -> u8 {
};
let ctl = PumpControl::new(ironrdp_server_size_placeholder());
// H.264 when this device has an encoder (none on Windows PE): offered to the browser, used if it asks.
let (video_control, video_path) = match platform::video_encoders() {
Some(factory) => {
let control = Arc::new(VideoControl::default());
let path = VideoPath::new(Arc::clone(&control), factory, args.max_fps);
(Some(control), Some(path))
}
None => {
tracing::info!("no H.264 encoder: the screen goes as RDP bitmaps");
(None, None)
}
};
let coords = CoordMap::default();
let (tx, rx) = tokio::sync::mpsc::channel(2);
@@ -99,7 +114,7 @@ fn serve(args: &ServeArgs) -> u8 {
let ctl = Arc::clone(&ctl);
let coords = coords.clone();
let view_only = args.view_only;
let cfg = PumpConfig { max_fps: args.max_fps };
let cfg = PumpConfig { max_fps: args.max_fps, video: video_path };
std::thread::Builder::new().name("capture".into()).spawn(move || {
capture::run_pump(
source,
@@ -123,6 +138,15 @@ fn serve(args: &ServeArgs) -> u8 {
let input = Box::new(GatedInput::new(args.view_only, coords, platform::create_input_sink()));
let display = HostDisplay::new(Arc::clone(&ctl), rx);
// Control sessions only: a view-only session shares no clipboard either way.
let clipboard: Option<Box<dyn ironrdp_server::CliprdrServerFactory>> = if args.view_only {
None
} else {
platform::create_clipboard().map(|os| {
Box::new(executer_screen::clipboard::ClipboardFactory::new(os))
as Box<dyn ironrdp_server::CliprdrServerFactory>
})
};
let runtime = match tokio::runtime::Builder::new_current_thread().enable_all().build() {
Ok(rt) => rt,
@@ -136,6 +160,8 @@ fn serve(args: &ServeArgs) -> u8 {
display,
Arc::clone(&ctl),
input,
clipboard,
video_control,
));
ctl.stop.store(true, Ordering::Relaxed);
+255
View File
@@ -0,0 +1,255 @@
//! Framing of stdin/stdout when the session carries H.264 video beside RDP.
//!
//! The browser asks for video in the RDCleanPath request's `destination` (`screen;video=h264`).
//! Hosts that do not know the hint ignore it (the field is opaque) and speak plain
//! RDCleanPath + RDP, so a new console works with an old host. A host that can encode H.264
//! answers with [`MAGIC`] before anything else; from then on both directions are frames of
//! `[channel u8][length u32 LE][payload]`: channel [`RDP`] carries the bytes the RDP client and
//! server exchange (starting with the RDCleanPath response), channel [`VIDEO`] the video
//! messages (`crate::video`). The relay (agent, server) passes the bytes through unchanged.
use std::io;
use bytes::{Buf as _, Bytes, BytesMut};
use tokio::io::{AsyncRead, AsyncReadExt as _, AsyncWrite, AsyncWriteExt as _, DuplexStream};
use tokio::sync::mpsc;
/// What the host writes first when it accepts video.
pub const MAGIC: &[u8; 8] = b"EXRMUX01";
pub const RDP: u8 = 0;
pub const VIDEO: u8 = 1;
const HEADER: usize = 5;
/// The largest frame the browser may send (RDP input and video acknowledgements are small).
pub const MAX_INBOUND: usize = 1 << 20;
/// Bytes buffered between the RDP server and the framing tasks, each way.
const PIPE: usize = 256 * 1024;
/// Whether the RDCleanPath `destination` asks for H.264 video (`<name>;video=h264`).
pub fn wants_video(destination: Option<&str>) -> bool {
destination.is_some_and(|d| d.split(';').skip(1).any(|p| p.trim().eq_ignore_ascii_case("video=h264")))
}
/// One frame: header and payload.
pub fn frame(channel: u8, payload: &[u8]) -> Vec<u8> {
let mut out = Vec::with_capacity(HEADER + payload.len());
out.push(channel);
out.extend_from_slice(&u32::try_from(payload.len()).unwrap_or(u32::MAX).to_le_bytes());
out.extend_from_slice(payload);
out
}
/// Splits the browser's bytes into frames (they arrive in any chunking).
#[derive(Default)]
pub struct Deframer {
buf: BytesMut,
}
impl Deframer {
pub fn push(&mut self, data: &[u8]) {
self.buf.extend_from_slice(data);
}
/// The next complete frame, if there is one.
pub fn next_frame(&mut self) -> io::Result<Option<(u8, Bytes)>> {
if self.buf.len() < HEADER {
return Ok(None);
}
let channel = self.buf[0];
let len = u32::from_le_bytes([self.buf[1], self.buf[2], self.buf[3], self.buf[4]]) as usize;
if channel > VIDEO || len > MAX_INBOUND {
return Err(io::Error::new(
io::ErrorKind::InvalidData,
format!("bad frame (channel {channel}, {len} bytes)"),
));
}
if self.buf.len() < HEADER + len {
return Ok(None);
}
self.buf.advance(HEADER);
Ok(Some((channel, self.buf.split_to(len).freeze())))
}
}
/// Video messages from the browser.
pub type VideoHandler = Box<dyn Fn(&[u8]) + Send>;
/// Sends frames to the browser; usable from any thread.
#[derive(Clone)]
pub struct Outbound(mpsc::Sender<(u8, Bytes)>);
impl Outbound {
/// Queues a video message, waiting while the queue is full. False once stdout is gone.
pub fn send_video(&self, payload: Vec<u8>) -> bool {
self.0.blocking_send((VIDEO, Bytes::from(payload))).is_ok()
}
#[cfg(test)]
pub fn for_tests(sender: mpsc::Sender<(u8, Bytes)>) -> Self {
Self(sender)
}
}
/// The RDP server's side of a framed stream, plus the way out for video.
pub struct Muxed {
pub reader: DuplexStream,
pub writer: DuplexStream,
pub out: Outbound,
}
/// Starts framing `reader`/`writer` (stdin/stdout) on the current runtime. `leftover` is what
/// the browser sent after its RDCleanPath request (already framed). Video messages from the
/// browser go to `on_video`. The returned reader ends when stdin does (or sends a bad frame);
/// the writer fails with a broken pipe once stdout is gone.
pub fn start<R, W>(reader: R, writer: W, leftover: Vec<u8>, on_video: VideoHandler) -> Muxed
where
R: AsyncRead + Unpin + Send + 'static,
W: AsyncWrite + Unpin + Send + 'static,
{
let (queue, outgoing) = mpsc::channel::<(u8, Bytes)>(64);
let (rdp_reader, mut to_rdp) = tokio::io::duplex(PIPE);
let (rdp_writer, mut from_rdp) = tokio::io::duplex(PIPE);
tokio::spawn(write_frames(writer, outgoing));
let rdp_out = queue.clone();
tokio::spawn(async move {
let mut buf = vec![0u8; 64 * 1024];
loop {
match from_rdp.read(&mut buf).await {
Ok(0) | Err(_) => return,
Ok(n) => {
if rdp_out.send((RDP, Bytes::copy_from_slice(&buf[..n]))).await.is_err() {
return;
}
}
}
}
});
tokio::spawn(async move {
let mut reader = reader;
let mut deframer = Deframer::default();
deframer.push(&leftover);
let mut buf = vec![0u8; 64 * 1024];
loop {
loop {
match deframer.next_frame() {
Ok(Some((RDP, payload))) => {
if to_rdp.write_all(&payload).await.is_err() {
return;
}
}
Ok(Some((_, payload))) => on_video(&payload),
Ok(None) => break,
Err(e) => {
tracing::warn!(error = %e, "the browser's stream is not framed; ending the session");
return;
}
}
}
match reader.read(&mut buf).await {
Ok(0) | Err(_) => return,
Ok(n) => deframer.push(&buf[..n]),
}
}
});
Muxed { reader: rdp_reader, writer: rdp_writer, out: Outbound(queue) }
}
async fn write_frames<W: AsyncWrite + Unpin>(mut writer: W, mut outgoing: mpsc::Receiver<(u8, Bytes)>) {
if writer.write_all(MAGIC).await.is_err() {
return;
}
while let Some((channel, payload)) = outgoing.recv().await {
let mut chunk = frame(channel, &payload);
// Whatever else is already queued goes in the same write.
while chunk.len() < 256 * 1024 {
match outgoing.try_recv() {
Ok((c, p)) => chunk.extend_from_slice(&frame(c, &p)),
Err(_) => break,
}
}
if writer.write_all(&chunk).await.is_err() || writer.flush().await.is_err() {
return;
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn the_hint_is_a_destination_parameter() {
assert!(wants_video(Some("screen;video=h264")));
assert!(wants_video(Some("screen; VIDEO=H264")));
assert!(!wants_video(Some("screen")));
assert!(!wants_video(Some("video=h264")));
assert!(!wants_video(None));
}
#[test]
fn frames_survive_any_chunking() {
let mut bytes = frame(RDP, b"hello");
bytes.extend(frame(VIDEO, &[1, 2, 3]));
bytes.extend(frame(RDP, b""));
let mut d = Deframer::default();
let mut got = Vec::new();
for b in bytes {
d.push(&[b]);
while let Some(f) = d.next_frame().unwrap() {
got.push(f);
}
}
assert_eq!(
got,
vec![(RDP, Bytes::from_static(b"hello")), (VIDEO, Bytes::from_static(&[1, 2, 3])), (RDP, Bytes::new())]
);
}
#[test]
fn bad_frames_are_refused() {
let mut d = Deframer::default();
d.push(&[7, 0, 0, 0, 0]);
assert!(d.next_frame().is_err());
let mut d = Deframer::default();
d.push(&frame(RDP, &[])[..1]);
d.push(&u32::try_from(MAX_INBOUND + 1).unwrap().to_le_bytes());
assert!(d.next_frame().is_err());
}
#[tokio::test(flavor = "current_thread")]
async fn rdp_and_video_share_the_stream() {
let (host_in, mut browser_out) = tokio::io::duplex(1 << 16);
let (mut browser_in, host_out) = tokio::io::duplex(1 << 16);
let seen = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
let sink = std::sync::Arc::clone(&seen);
let mut m = start(
host_in,
host_out,
frame(RDP, b"early"),
Box::new(move |p| sink.lock().unwrap().extend_from_slice(p)),
);
browser_out.write_all(&frame(VIDEO, b"ack")).await.unwrap();
browser_out.write_all(&frame(RDP, b"-input")).await.unwrap();
let mut got = [0u8; 11];
m.reader.read_exact(&mut got).await.unwrap();
assert_eq!(&got, b"early-input");
assert_eq!(seen.lock().unwrap().as_slice(), b"ack");
m.writer.write_all(b"rdp-out").await.unwrap();
let mut head = [0u8; 8];
browser_in.read_exact(&mut head).await.unwrap();
assert_eq!(&head, MAGIC);
let mut f = vec![0u8; HEADER + 7];
browser_in.read_exact(&mut f).await.unwrap();
assert_eq!(f, frame(RDP, b"rdp-out"));
drop(browser_out);
let mut rest = Vec::new();
m.reader.read_to_end(&mut rest).await.unwrap();
assert!(rest.is_empty(), "stdin EOF ends the RDP reader");
}
}
+29
View File
@@ -66,6 +66,35 @@ pub fn probe() -> ProbeReport {
imp::probe()
}
/// The device clipboard for Remote View's clipboard channel; None where there is none yet
/// (Linux, macOS).
pub fn create_clipboard() -> Option<std::sync::Arc<dyn crate::clipboard::OsClipboard>> {
#[cfg(windows)]
{
imp::create_clipboard()
}
#[cfg(not(windows))]
{
None
}
}
/// H.264 encoders for Remote View video, when this device has one (Windows with Media
/// Foundation; none on Windows PE, Server Core, Linux, macOS).
pub fn video_encoders() -> Option<crate::video::EncoderFactory> {
#[cfg(windows)]
{
imp::h264::available().then(|| {
Box::new(|w: u32, h: u32, fps: u32, hw: bool| imp::h264::create(w, h, fps, hw))
as crate::video::EncoderFactory
})
}
#[cfg(not(windows))]
{
None
}
}
/// The served region for a selection: the union of all monitors, or one monitor.
pub fn select_bounds(monitors: &[MonitorInfo], selection: MonitorSelection) -> Option<Rect> {
match selection {
@@ -0,0 +1,204 @@
//! The device's clipboard (Unicode text) for the Remote View clipboard channel.
//!
//! The host runs as SYSTEM on the user's desktop, so it keeps no window and no message pump
//! (README, Security). Changes are found by polling the clipboard's sequence number. A write
//! needs a window to own the clipboard after `EmptyClipboard`, so each write makes a
//! message-only window, places the text and destroys the window straight away; the text stays
//! on the clipboard (it is not delay-rendered). The clipboard belongs to the window station
//! (winsta0), so it is the same on the user's desktop, the lock screen and UAC prompts.
use std::sync::mpsc::{RecvTimeoutError, Sender, channel};
use std::sync::{Arc, Mutex};
use std::time::Duration;
use windows::Win32::Foundation::{GlobalFree, HANDLE, HGLOBAL, HWND, LPARAM, LRESULT, WPARAM};
use windows::Win32::System::DataExchange::{
CloseClipboard, EmptyClipboard, GetClipboardData, GetClipboardSequenceNumber, IsClipboardFormatAvailable,
OpenClipboard, SetClipboardData,
};
use windows::Win32::System::LibraryLoader::GetModuleHandleW;
use windows::Win32::System::Memory::{GMEM_MOVEABLE, GlobalAlloc, GlobalLock, GlobalSize, GlobalUnlock};
use windows::Win32::UI::WindowsAndMessaging::{
CreateWindowExW, DefWindowProcW, DestroyWindow, HWND_MESSAGE, RegisterClassW, WINDOW_EX_STYLE, WINDOW_STYLE,
WNDCLASSW,
};
use windows::core::{PCWSTR, w};
use crate::clipboard::OsClipboard;
/// CF_UNICODETEXT.
const CF_UNICODETEXT: u32 = 13;
/// How often the clipboard's sequence number is checked.
const POLL: Duration = Duration::from_millis(250);
const CLASS: PCWSTR = w!("ExecuteRScreenClipboardOwner");
type Watcher = Box<dyn Fn() + Send + Sync>;
pub struct WindowsClipboard {
writes: Sender<String>,
watcher: Arc<Mutex<Option<Watcher>>>,
}
impl WindowsClipboard {
/// Starts the clipboard thread (it ends with the process).
pub fn start() -> Option<Arc<Self>> {
let (writes, queue) = channel::<String>();
let watcher: Arc<Mutex<Option<Watcher>>> = Arc::new(Mutex::new(None));
let notify = Arc::clone(&watcher);
std::thread::Builder::new()
.name("clipboard".into())
.spawn(move || {
register_class();
// SAFETY: plain Win32 call.
let mut seen = unsafe { GetClipboardSequenceNumber() };
loop {
match queue.recv_timeout(POLL) {
Ok(text) => {
// Only the newest of several queued writes matters.
let text = queue.try_iter().last().unwrap_or(text);
if write_now(&text) {
// Our own change is not reported back.
// SAFETY: plain Win32 call.
seen = unsafe { GetClipboardSequenceNumber() };
}
}
Err(RecvTimeoutError::Timeout) => {}
Err(RecvTimeoutError::Disconnected) => return,
}
// SAFETY: plain Win32 call.
let now = unsafe { GetClipboardSequenceNumber() };
if now != seen {
seen = now;
if let Some(changed) = notify.lock().ok().as_ref().and_then(|w| w.as_ref()) {
changed();
}
}
}
})
.ok()?;
Some(Arc::new(Self { writes, watcher }))
}
}
unsafe extern "system" fn owner_proc(hwnd: HWND, msg: u32, wparam: WPARAM, lparam: LPARAM) -> LRESULT {
// SAFETY: default handling; the window lives only for one write and is never pumped.
unsafe { DefWindowProcW(hwnd, msg, wparam, lparam) }
}
fn register_class() {
// SAFETY: registering a window class with a static name and a default procedure.
unsafe {
let instance = GetModuleHandleW(None).ok();
let class = WNDCLASSW {
lpfnWndProc: Some(owner_proc),
hInstance: instance.map(Into::into).unwrap_or_default(),
lpszClassName: CLASS,
..Default::default()
};
RegisterClassW(&class);
}
}
/// Opens the clipboard, retrying briefly while another program holds it.
fn open(owner: Option<HWND>) -> bool {
for _ in 0..10 {
// SAFETY: plain Win32 call; closed by the caller.
if unsafe { OpenClipboard(owner) }.is_ok() {
return true;
}
std::thread::sleep(Duration::from_millis(15));
}
false
}
/// Places `text` on the clipboard through a window made and destroyed for this one write.
fn write_now(text: &str) -> bool {
let wide: Vec<u16> = text.encode_utf16().chain(Some(0)).collect();
// SAFETY: the window is created and destroyed on this thread; the clipboard is opened
// and closed here; the global block goes to the clipboard on success and is freed by us
// otherwise.
unsafe {
let instance = GetModuleHandleW(None).ok();
let Ok(hwnd) = CreateWindowExW(
WINDOW_EX_STYLE(0),
CLASS,
PCWSTR::null(),
WINDOW_STYLE(0),
0,
0,
0,
0,
Some(HWND_MESSAGE),
None,
instance.map(Into::into),
None,
) else {
tracing::info!("the operator's text could not be placed on the device clipboard (no owner window)");
return false;
};
let placed = if open(Some(hwnd)) {
let _ = EmptyClipboard();
let result = (|| -> windows::core::Result<()> {
let block = GlobalAlloc(GMEM_MOVEABLE, wide.len() * 2)?;
let target = GlobalLock(block).cast::<u16>();
if target.is_null() {
let _ = GlobalFree(Some(block));
return Err(windows::core::Error::from_thread());
}
core::ptr::copy_nonoverlapping(wide.as_ptr(), target, wide.len());
let _ = GlobalUnlock(block);
if let Err(e) = SetClipboardData(CF_UNICODETEXT, Some(HANDLE(block.0))) {
let _ = GlobalFree(Some(block));
return Err(e);
}
Ok(())
})();
let _ = CloseClipboard();
if let Err(e) = &result {
tracing::info!(error = %e, "the operator's text could not be placed on the device clipboard");
}
result.is_ok()
} else {
tracing::info!("the device clipboard is busy; the operator's text was not placed");
false
};
let _ = DestroyWindow(hwnd);
placed
}
}
impl OsClipboard for WindowsClipboard {
fn read_text(&self) -> Option<String> {
// SAFETY: plain Win32 calls; the clipboard is closed before returning and the data is
// copied out while locked, within the block's size.
unsafe {
if IsClipboardFormatAvailable(CF_UNICODETEXT).is_err() || !open(None) {
return None;
}
let text = GetClipboardData(CF_UNICODETEXT).ok().and_then(|handle| {
let block = HGLOBAL(handle.0);
let data = GlobalLock(block).cast::<u16>();
if data.is_null() {
return None;
}
let max = GlobalSize(block) / 2;
let len = (0..max).find(|&i| *data.add(i) == 0).unwrap_or(max);
let text = String::from_utf16_lossy(core::slice::from_raw_parts(data, len));
let _ = GlobalUnlock(block);
Some(text)
});
let _ = CloseClipboard();
text
}
}
fn write_text(&self, text: &str) {
let _ = self.writes.send(text.to_owned());
}
fn watch(&self, changed: Watcher) {
if let Ok(mut slot) = self.watcher.lock() {
*slot = Some(changed);
}
}
}
+601
View File
@@ -0,0 +1,601 @@
//! H.264 through Media Foundation: the GPU's encoder when there is one (an asynchronous
//! hardware MFT: NVIDIA, Intel Quick Sync, AMD), else Microsoft's software encoder.
//!
//! Media Foundation is loaded at run time (mfplat.dll, ole32.dll from System32): Windows PE
//! and Server Core have none, and the executable must still start there (README, Platforms).
//! Constrained to what the browser decodes with the least delay: Baseline profile (no
//! reordering), no B-frames, low-latency mode, constant bit rate scaled to the frame size.
use core::ffi::c_void;
use core::mem::ManuallyDrop;
use std::sync::OnceLock;
use std::time::{Duration, Instant};
use anyhow::{Context as _, Result, anyhow, bail};
use windows::Win32::Media::MediaFoundation::{
CODECAPI_AVEncCommonMeanBitRate, CODECAPI_AVEncCommonQualityVsSpeed, CODECAPI_AVEncCommonRateControlMode,
CODECAPI_AVEncMPVDefaultBPictureCount, CODECAPI_AVEncMPVGOPSize, CODECAPI_AVEncVideoForceKeyFrame,
CODECAPI_AVLowLatencyMode, ICodecAPI, IMFActivate, IMFMediaBuffer, IMFMediaEventGenerator, IMFMediaType, IMFSample,
IMFTransform, METransformHaveOutput, METransformNeedInput, MF_E_NO_EVENTS_AVAILABLE, MF_E_NOTACCEPTING,
MF_E_TRANSFORM_NEED_MORE_INPUT, MF_E_TRANSFORM_STREAM_CHANGE, MF_EVENT_FLAG_NO_WAIT, MF_LOW_LATENCY,
MF_MT_AVG_BITRATE, MF_MT_FRAME_RATE, MF_MT_FRAME_SIZE, MF_MT_INTERLACE_MODE, MF_MT_MAJOR_TYPE,
MF_MT_MPEG_SEQUENCE_HEADER, MF_MT_MPEG2_PROFILE, MF_MT_PIXEL_ASPECT_RATIO, MF_MT_SUBTYPE, MF_TRANSFORM_ASYNC,
MF_TRANSFORM_ASYNC_UNLOCK, MF_VERSION, MFMediaType_Video, MFSTARTUP_NOSOCKET, MFSampleExtension_CleanPoint,
MFT_CATEGORY_VIDEO_ENCODER, MFT_ENUM_FLAG_HARDWARE, MFT_ENUM_FLAG_LOCALMFT, MFT_ENUM_FLAG_SORTANDFILTER,
MFT_ENUM_FLAG_SYNCMFT, MFT_FRIENDLY_NAME_Attribute, MFT_MESSAGE_NOTIFY_BEGIN_STREAMING,
MFT_MESSAGE_NOTIFY_START_OF_STREAM, MFT_OUTPUT_DATA_BUFFER, MFT_OUTPUT_STREAM_CAN_PROVIDE_SAMPLES,
MFT_OUTPUT_STREAM_PROVIDES_SAMPLES, MFT_REGISTER_TYPE_INFO, MFVideoFormat_H264, MFVideoFormat_NV12,
MFVideoInterlace_Progressive, eAVEncCommonRateControlMode_CBR, eAVEncH264VProfile_Base,
};
use windows::Win32::System::LibraryLoader::{GetProcAddress, LOAD_LIBRARY_SEARCH_SYSTEM32, LoadLibraryExW};
use windows::Win32::System::Variant::VARIANT;
use windows::core::{GUID, HRESULT, Interface, PWSTR, s, w};
use crate::video::{EncodedFrame, VideoEncoder};
type MfStartupFn = unsafe extern "system" fn(u32, u32) -> HRESULT;
type MftEnumExFn = unsafe extern "system" fn(
GUID,
u32,
*const MFT_REGISTER_TYPE_INFO,
*const MFT_REGISTER_TYPE_INFO,
*mut *mut *mut c_void,
*mut u32,
) -> HRESULT;
type MfCreateFn = unsafe extern "system" fn(*mut *mut c_void) -> HRESULT;
type MfCreateMemoryBufferFn = unsafe extern "system" fn(u32, *mut *mut c_void) -> HRESULT;
type CoInitializeExFn = unsafe extern "system" fn(*const c_void, u32) -> HRESULT;
type CoTaskMemFreeFn = unsafe extern "system" fn(*const c_void);
/// The Media Foundation entry points, loaded once.
struct Api {
enum_ex: MftEnumExFn,
create_sample: MfCreateFn,
create_media_type: MfCreateFn,
create_memory_buffer: MfCreateMemoryBufferFn,
co_initialize: CoInitializeExFn,
co_free: CoTaskMemFreeFn,
}
// SAFETY: plain function pointers into system DLLs that stay loaded.
unsafe impl Send for Api {}
// SAFETY: as above.
unsafe impl Sync for Api {}
fn api() -> Option<&'static Api> {
static API: OnceLock<Option<Api>> = OnceLock::new();
API.get_or_init(|| match load() {
Ok(api) => Some(api),
Err(e) => {
tracing::info!(error = format!("{e:#}"), "no Media Foundation: no H.264 video");
None
}
})
.as_ref()
}
fn load() -> Result<Api> {
// SAFETY: System32 DLLs only; each symbol has the documented signature declared above.
unsafe {
let mf = LoadLibraryExW(w!("mfplat.dll"), None, LOAD_LIBRARY_SEARCH_SYSTEM32).context("mfplat.dll")?;
let ole = LoadLibraryExW(w!("ole32.dll"), None, LOAD_LIBRARY_SEARCH_SYSTEM32).context("ole32.dll")?;
macro_rules! symbol {
($module:expr, $name:literal, $ty:ty) => {
core::mem::transmute::<unsafe extern "system" fn() -> isize, $ty>(
GetProcAddress($module, s!($name)).ok_or_else(|| anyhow!(concat!($name, " missing")))?,
)
};
}
let startup = symbol!(mf, "MFStartup", MfStartupFn);
let api = Api {
enum_ex: symbol!(mf, "MFTEnumEx", MftEnumExFn),
create_sample: symbol!(mf, "MFCreateSample", MfCreateFn),
create_media_type: symbol!(mf, "MFCreateMediaType", MfCreateFn),
create_memory_buffer: symbol!(mf, "MFCreateMemoryBuffer", MfCreateMemoryBufferFn),
co_initialize: symbol!(ole, "CoInitializeEx", CoInitializeExFn),
co_free: symbol!(ole, "CoTaskMemFree", CoTaskMemFreeFn),
};
com(&api);
startup(MF_VERSION, MFSTARTUP_NOSOCKET).ok().context("MFStartup")?;
Ok(api)
}
}
/// COM for this thread (multithreaded apartment), once per thread.
fn com(api: &Api) {
thread_local!(static DONE: core::cell::Cell<bool> = const { core::cell::Cell::new(false) });
DONE.with(|done| {
if !done.replace(true) {
// COINIT_MULTITHREADED = 0. S_FALSE (already initialised) is fine.
// SAFETY: documented signature; never uninitialised (the thread ends with the process).
let _ = unsafe { (api.co_initialize)(core::ptr::null(), 0) };
}
});
}
/// The registered H.264 encoders that take NV12, best first.
fn encoders(api: &Api, hardware: bool) -> Vec<IMFActivate> {
com(api);
let flags = if hardware {
MFT_ENUM_FLAG_HARDWARE.0 | MFT_ENUM_FLAG_SORTANDFILTER.0
} else {
MFT_ENUM_FLAG_SYNCMFT.0 | MFT_ENUM_FLAG_LOCALMFT.0 | MFT_ENUM_FLAG_SORTANDFILTER.0
};
let input = MFT_REGISTER_TYPE_INFO { guidMajorType: MFMediaType_Video, guidSubtype: MFVideoFormat_NV12 };
let output = MFT_REGISTER_TYPE_INFO { guidMajorType: MFMediaType_Video, guidSubtype: MFVideoFormat_H264 };
let mut list: *mut *mut c_void = core::ptr::null_mut();
let mut count = 0u32;
// SAFETY: documented signature; the array and each reference it holds become ours.
unsafe {
if (api.enum_ex)(MFT_CATEGORY_VIDEO_ENCODER, flags as u32, &input, &output, &mut list, &mut count).is_err()
|| list.is_null()
{
return Vec::new();
}
let found = (0..count as usize)
.map(|i| *list.add(i))
.filter(|p| !p.is_null())
.map(|p| IMFActivate::from_raw(p))
.collect();
(api.co_free)(list.cast());
found
}
}
/// Whether an H.264 encoder is there at all (the browser is offered video only then).
pub fn available() -> bool {
api().is_some_and(|api| !encoders(api, true).is_empty() || !encoders(api, false).is_empty())
}
/// An encoder for `width` x `height` (even) at `fps`: hardware first when allowed.
pub fn create(width: u32, height: u32, fps: u32, hardware: bool) -> Result<Box<dyn VideoEncoder>> {
let api = api().ok_or_else(|| anyhow!("Media Foundation is not available"))?;
let kinds: &[bool] = if hardware { &[true, false] } else { &[false] };
let mut tried = Vec::new();
for &hw in kinds {
for activate in encoders(api, hw) {
let name = friendly_name(api, &activate).unwrap_or_else(|| "H.264 encoder".into());
match MfEncoder::new(api, activate, name.clone(), hw, width, height, fps) {
Ok(encoder) => return Ok(Box::new(encoder)),
Err(e) => {
tracing::info!(encoder = name, error = format!("{e:#}"), "H.264 encoder not usable");
tried.push(name);
}
}
}
}
if tried.is_empty() {
bail!("no H.264 encoder is installed")
} else {
bail!("no H.264 encoder took {width}x{height} (tried {})", tried.join(", "))
}
}
fn friendly_name(api: &Api, activate: &IMFActivate) -> Option<String> {
let mut text = PWSTR::null();
let mut len = 0u32;
// SAFETY: the string is allocated by the callee and freed here.
unsafe {
activate.GetAllocatedString(&MFT_FRIENDLY_NAME_Attribute, &mut text, &mut len).ok()?;
let name = text.to_string().ok();
(api.co_free)(text.0.cast());
name
}
}
/// Bits per second for a frame size: about 0.1 bit per pixel per frame, 1.5-12 Mbit/s. Only
/// frames that change are encoded, so a still screen costs next to nothing.
pub fn bitrate(width: u32, height: u32, fps: u32) -> u32 {
let bits = u64::from(width) * u64::from(height) * u64::from(fps) / 10;
u32::try_from(bits.clamp(1_500_000, 12_000_000)).unwrap_or(12_000_000)
}
struct MfEncoder {
api: &'static Api,
activate: IMFActivate,
transform: IMFTransform,
codec: Option<ICodecAPI>,
events: Option<IMFMediaEventGenerator>,
name: String,
hardware: bool,
input_id: u32,
output_id: u32,
sequence_header: Vec<u8>,
frame_duration: i64,
need_input: u32,
output_capacity: u32,
}
// SAFETY: made, used and dropped on the capture thread (a COM multithreaded apartment); the
// pump is moved to that thread before any encoder exists.
unsafe impl Send for MfEncoder {}
impl MfEncoder {
fn new(
api: &'static Api,
activate: IMFActivate,
name: String,
hardware: bool,
width: u32,
height: u32,
fps: u32,
) -> Result<Self> {
// SAFETY: COM calls on interfaces this thread owns; arguments are valid for each call.
unsafe {
let transform: IMFTransform = activate.ActivateObject().context("activate")?;
let mut encoder = Self {
api,
activate,
codec: transform.cast().ok(),
transform,
events: None,
name,
hardware,
input_id: 0,
output_id: 0,
sequence_header: Vec::new(),
frame_duration: 10_000_000 / i64::from(fps.max(1)),
need_input: 0,
output_capacity: width * height * 3 / 2,
};
encoder.configure(width, height, fps)?;
Ok(encoder)
}
}
unsafe fn configure(&mut self, width: u32, height: u32, fps: u32) -> Result<()> {
// SAFETY: as in `new`.
unsafe {
let t = self.transform.clone();
if let Ok(attributes) = t.GetAttributes() {
if attributes.GetUINT32(&MF_TRANSFORM_ASYNC).unwrap_or(0) != 0 {
attributes.SetUINT32(&MF_TRANSFORM_ASYNC_UNLOCK, 1).context("unlock async MFT")?;
self.events = Some(t.cast().context("async MFT without events")?);
}
let _ = attributes.SetUINT32(&MF_LOW_LATENCY, 1);
}
let (mut inputs, mut outputs) = ([0u32], [0u32]);
if t.GetStreamIDs(&mut inputs, &mut outputs).is_ok() {
(self.input_id, self.output_id) = (inputs[0], outputs[0]);
}
let rate = bitrate(width, height, fps);
if let Some(codec) = &self.codec {
// Best effort: an encoder that lacks a setting keeps its default.
let set = |api: &GUID, value: VARIANT| {
let _ = codec.SetValue(api, &value);
};
set(&CODECAPI_AVEncCommonRateControlMode, VARIANT::from(eAVEncCommonRateControlMode_CBR.0 as u32));
set(&CODECAPI_AVEncCommonMeanBitRate, VARIANT::from(rate));
set(&CODECAPI_AVLowLatencyMode, VARIANT::from(true));
set(&CODECAPI_AVEncMPVDefaultBPictureCount, VARIANT::from(0u32));
set(&CODECAPI_AVEncMPVGOPSize, VARIANT::from(fps.max(1) * 60));
set(&CODECAPI_AVEncCommonQualityVsSpeed, VARIANT::from(if self.hardware { 50u32 } else { 20u32 }));
}
let size = (u64::from(width) << 32) | u64::from(height);
let frame_rate = (u64::from(fps.max(1)) << 32) | 1;
let output = self.media_type()?;
output.SetGUID(&MF_MT_MAJOR_TYPE, &MFMediaType_Video)?;
output.SetGUID(&MF_MT_SUBTYPE, &MFVideoFormat_H264)?;
output.SetUINT32(&MF_MT_AVG_BITRATE, rate)?;
output.SetUINT64(&MF_MT_FRAME_SIZE, size)?;
output.SetUINT64(&MF_MT_FRAME_RATE, frame_rate)?;
output.SetUINT64(&MF_MT_PIXEL_ASPECT_RATIO, (1 << 32) | 1)?;
output.SetUINT32(&MF_MT_INTERLACE_MODE, MFVideoInterlace_Progressive.0 as u32)?;
output.SetUINT32(&MF_MT_MPEG2_PROFILE, eAVEncH264VProfile_Base.0 as u32)?;
t.SetOutputType(self.output_id, &output, 0).context("output type")?;
let input = self.media_type()?;
input.SetGUID(&MF_MT_MAJOR_TYPE, &MFMediaType_Video)?;
input.SetGUID(&MF_MT_SUBTYPE, &MFVideoFormat_NV12)?;
input.SetUINT64(&MF_MT_FRAME_SIZE, size)?;
input.SetUINT64(&MF_MT_FRAME_RATE, frame_rate)?;
input.SetUINT64(&MF_MT_PIXEL_ASPECT_RATIO, (1 << 32) | 1)?;
input.SetUINT32(&MF_MT_INTERLACE_MODE, MFVideoInterlace_Progressive.0 as u32)?;
t.SetInputType(self.input_id, &input, 0).context("input type")?;
self.read_sequence_header();
t.ProcessMessage(MFT_MESSAGE_NOTIFY_BEGIN_STREAMING, 0).context("begin streaming")?;
t.ProcessMessage(MFT_MESSAGE_NOTIFY_START_OF_STREAM, 0).context("start of stream")?;
Ok(())
}
}
fn media_type(&self) -> Result<IMFMediaType> {
let mut raw = core::ptr::null_mut();
// SAFETY: documented signature; the reference becomes ours.
unsafe {
(self.api.create_media_type)(&mut raw).ok().context("MFCreateMediaType")?;
Ok(IMFMediaType::from_raw(raw))
}
}
/// SPS/PPS from the output type, for key frames that come without them.
fn read_sequence_header(&mut self) {
// SAFETY: COM calls; the blob is copied into a buffer of its reported size.
unsafe {
if let Ok(current) = self.transform.GetOutputCurrentType(self.output_id)
&& let Ok(size) = current.GetBlobSize(&MF_MT_MPEG_SEQUENCE_HEADER)
{
let mut blob = vec![0u8; size as usize];
if current.GetBlob(&MF_MT_MPEG_SEQUENCE_HEADER, &mut blob, None).is_ok() {
self.sequence_header = blob;
}
}
}
}
fn sample(&self, data: Option<&[u8]>, capacity: u32) -> Result<IMFSample> {
// SAFETY: documented signatures; the buffer is locked only while copying into it.
unsafe {
let mut raw = core::ptr::null_mut();
(self.api.create_memory_buffer)(capacity, &mut raw).ok().context("MFCreateMemoryBuffer")?;
let buffer = IMFMediaBuffer::from_raw(raw);
if let Some(data) = data {
let mut target = core::ptr::null_mut();
buffer.Lock(&mut target, None, None)?;
core::ptr::copy_nonoverlapping(data.as_ptr(), target, data.len());
buffer.Unlock()?;
buffer.SetCurrentLength(u32::try_from(data.len())?)?;
}
let mut raw = core::ptr::null_mut();
(self.api.create_sample)(&mut raw).ok().context("MFCreateSample")?;
let sample = IMFSample::from_raw(raw);
sample.AddBuffer(&buffer)?;
Ok(sample)
}
}
/// One ProcessOutput: Ok(None) when the encoder needs more input.
fn pull(&mut self) -> Result<Option<EncodedFrame>> {
// SAFETY: COM calls; the output buffer's sample and events are taken back out of the
// ManuallyDrop fields so they are released exactly once.
unsafe {
for _ in 0..3 {
let info = self.transform.GetOutputStreamInfo(self.output_id)?;
let provides = info.dwFlags
& (MFT_OUTPUT_STREAM_PROVIDES_SAMPLES.0 | MFT_OUTPUT_STREAM_CAN_PROVIDE_SAMPLES.0) as u32
!= 0;
let ours =
if provides { None } else { Some(self.sample(None, info.cbSize.max(self.output_capacity))?) };
let mut buffers = [MFT_OUTPUT_DATA_BUFFER {
dwStreamID: self.output_id,
pSample: ManuallyDrop::new(ours),
dwStatus: 0,
pEvents: ManuallyDrop::new(None),
}];
let mut status = 0u32;
let result = self.transform.ProcessOutput(0, &mut buffers, &mut status);
let sample = buffers[0].pSample.take();
drop(buffers[0].pEvents.take());
match result {
Ok(()) => {}
Err(e) if e.code() == MF_E_TRANSFORM_NEED_MORE_INPUT => return Ok(None),
Err(e) if e.code() == MF_E_TRANSFORM_STREAM_CHANGE => {
// Hardware encoders may settle their output type once streaming.
let available = self.transform.GetOutputAvailableType(self.output_id, 0)?;
self.transform.SetOutputType(self.output_id, &available, 0)?;
self.read_sequence_header();
continue;
}
Err(e) => return Err(e).context("ProcessOutput"),
}
let Some(sample) = sample else { return Ok(None) };
let key = sample.GetUINT32(&MFSampleExtension_CleanPoint).unwrap_or(0) != 0;
let buffer = sample.ConvertToContiguousBuffer()?;
let mut data = core::ptr::null_mut();
let mut len = 0u32;
buffer.Lock(&mut data, None, Some(&mut len))?;
let bytes = core::slice::from_raw_parts(data, len as usize).to_vec();
buffer.Unlock()?;
let bytes = if key && !has_sps(&bytes) && !self.sequence_header.is_empty() {
let mut with = self.sequence_header.clone();
with.extend_from_slice(&bytes);
with
} else {
bytes
};
let key = key || has_sps(&bytes);
return Ok(Some(EncodedFrame { data: bytes, key }));
}
bail!("the encoder kept changing its output type")
}
}
/// Handles queued events of an asynchronous encoder.
fn pump_events(&mut self, out: &mut Vec<EncodedFrame>) -> Result<()> {
let Some(events) = self.events.clone() else { return Ok(()) };
loop {
// SAFETY: COM call on an interface this thread owns.
let event = match unsafe { events.GetEvent(MF_EVENT_FLAG_NO_WAIT) } {
Ok(e) => e,
Err(e) if e.code() == MF_E_NO_EVENTS_AVAILABLE => return Ok(()),
Err(e) => return Err(e).context("GetEvent"),
};
// SAFETY: as above.
let kind = unsafe { event.GetType() }?;
if kind == METransformNeedInput.0 as u32 {
self.need_input += 1;
} else if kind == METransformHaveOutput.0 as u32
&& let Some(frame) = self.pull()?
{
out.push(frame);
}
}
}
}
impl VideoEncoder for MfEncoder {
fn name(&self) -> &str {
&self.name
}
fn hardware(&self) -> bool {
self.hardware
}
fn encode(&mut self, nv12: &[u8], time: i64, key: bool) -> Result<Vec<EncodedFrame>> {
let mut out = Vec::new();
if key && let Some(codec) = &self.codec {
// SAFETY: COM call with a valid VARIANT.
let _ = unsafe { codec.SetValue(&CODECAPI_AVEncVideoForceKeyFrame, &VARIANT::from(1u32)) };
}
let sample = self.sample(Some(nv12), u32::try_from(nv12.len())?)?;
// SAFETY: COM calls on interfaces this thread owns.
unsafe {
sample.SetSampleTime(time)?;
sample.SetSampleDuration(self.frame_duration)?;
}
if self.events.is_some() {
// Asynchronous (hardware): input only when asked for; outputs as they come.
let deadline = Instant::now() + Duration::from_millis(100);
while self.need_input == 0 {
self.pump_events(&mut out)?;
if self.need_input > 0 {
break;
}
if Instant::now() >= deadline {
return Ok(out); // The encoder is busy: this picture is skipped.
}
std::thread::sleep(Duration::from_millis(1));
}
self.need_input -= 1;
// SAFETY: as above.
unsafe { self.transform.ProcessInput(self.input_id, &sample, 0) }.context("ProcessInput")?;
let deadline = Instant::now() + Duration::from_millis(40);
let before = out.len();
while out.len() == before && Instant::now() < deadline {
self.pump_events(&mut out)?;
if out.len() == before {
std::thread::sleep(Duration::from_millis(1));
}
}
return Ok(out);
}
// Synchronous (software).
// SAFETY: as above.
match unsafe { self.transform.ProcessInput(self.input_id, &sample, 0) } {
Ok(()) => {}
Err(e) if e.code() == MF_E_NOTACCEPTING => {
while let Some(frame) = self.pull()? {
out.push(frame);
}
// SAFETY: as above.
unsafe { self.transform.ProcessInput(self.input_id, &sample, 0) }.context("ProcessInput")?;
}
Err(e) => return Err(e).context("ProcessInput"),
}
while let Some(frame) = self.pull()? {
out.push(frame);
}
Ok(out)
}
}
impl Drop for MfEncoder {
fn drop(&mut self) {
// SAFETY: releases the encoder's resources; the transform is not used afterwards.
unsafe {
let _ = self.activate.ShutdownObject();
}
}
}
/// Whether Annex B data holds a sequence parameter set (NAL type 7).
fn has_sps(data: &[u8]) -> bool {
data.windows(4).any(|w| w[..3] == [0, 0, 1] && w[3] & 0x1f == 7)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn bitrate_scales_with_the_picture() {
assert_eq!(bitrate(1920, 1080, 30), 6_220_800);
assert_eq!(bitrate(640, 480, 30), 1_500_000);
assert_eq!(bitrate(3840, 2160, 30), 12_000_000);
}
#[test]
fn sps_is_found_after_any_start_code() {
assert!(has_sps(&[0, 0, 0, 1, 0x67, 0x42]));
assert!(has_sps(&[0, 0, 1, 0x27]));
assert!(!has_sps(&[0, 0, 0, 1, 0x65, 0x88]));
}
/// Throughput at 1080p with a 400x400 textured block moving (what `throughput_1080p_15fps`
/// measures for RemoteFX): `cargo test --release --lib h264_1080p -- --ignored --nocapture`.
#[test]
#[ignore = "benchmark"]
fn h264_1080p_moving_block() {
if !available() {
return;
}
let (w, h) = (1920usize, 1080usize);
let mut encoder = create(1920, 1080, 30, true).expect("an encoder");
let mut bgrx = vec![0x30u8; w * h * 4];
let mut nv12 = Vec::new();
let (mut bytes, mut frames) = (0usize, 0usize);
let start = Instant::now();
for i in 0..120usize {
bgrx.fill(0x30);
let (bx, by) = ((i * 12) % (w - 400), (i * 5) % (h - 400));
for y in 0..400 {
for x in 0..400 {
let p = ((by + y) * w + bx + x) * 4;
bgrx[p..p + 4].copy_from_slice(&[(x ^ y) as u8, (x * 2) as u8, (y * 3) as u8, 0]);
}
}
let frame = crate::capture::FrameRef { data: &bgrx, stride: w * 4, width: w, height: h };
crate::video::bgrx_to_nv12(&frame, (1920, 1080), &mut nv12);
for f in encoder.encode(&nv12, i as i64 * 333_333, i == 0).expect("encode") {
bytes += f.data.len();
frames += 1;
}
}
let secs = start.elapsed().as_secs_f64();
eprintln!(
"{} (hardware: {}): {frames} frames in {secs:.2}s = {:.1} fps max, {:.1} ms/frame, {:.2} Mbit/s at 30 fps",
encoder.name(),
encoder.hardware(),
frames as f64 / secs,
secs * 1000.0 / 120.0,
bytes as f64 * 8.0 / (120.0 / 30.0) / 1e6
);
}
/// Encodes real frames with whatever encoder this machine has (Windows only; skipped
/// where Media Foundation is missing).
#[test]
fn encodes_a_key_frame_then_deltas() {
if !available() {
eprintln!("no H.264 encoder here; skipped");
return;
}
let (width, height) = (1280u32, 720u32);
let mut encoder = create(width, height, 30, true).expect("an encoder");
let mut frames = Vec::new();
let mut nv12 = vec![0u8; (width * height * 3 / 2) as usize];
for i in 0..10u8 {
nv12[..(width * height) as usize]
.iter_mut()
.enumerate()
.for_each(|(p, v)| *v = (p as u8).wrapping_add(i * 9));
frames.extend(encoder.encode(&nv12, i64::from(i) * 333_333, i == 0).expect("encode"));
}
assert!(!frames.is_empty(), "{} produced nothing", encoder.name());
assert!(frames[0].key && has_sps(&frames[0].data), "the first frame is a key frame with SPS");
assert!(frames[1..].iter().any(|f| !f.key), "later frames are deltas");
eprintln!(
"{} (hardware: {}): {} frames, {} bytes",
encoder.name(),
encoder.hardware(),
frames.len(),
frames.iter().map(|f| f.data.len()).sum::<usize>()
);
}
}
@@ -4,10 +4,12 @@
//! to the input desktop with `SetThreadDesktop`. Optional DLLs (dxgi, d3d11, sas) are loaded
//! from System32 only.
mod clipboard;
mod cursor;
mod desktop;
mod dxgi;
mod gdi;
pub(crate) mod h264;
mod input;
mod monitors;
mod source;
@@ -108,6 +110,11 @@ pub fn create_input_sink() -> Box<dyn InputSink> {
Box::new(input::create())
}
/// The device clipboard (text), or None when its window cannot be made.
pub fn create_clipboard() -> Option<std::sync::Arc<dyn crate::clipboard::OsClipboard>> {
clipboard::WindowsClipboard::start().map(|c| c as std::sync::Arc<dyn crate::clipboard::OsClipboard>)
}
pub fn probe() -> ProbeReport {
let winpe = is_winpe();
let monitors = monitors::enumerate();
+28 -11
View File
@@ -4,12 +4,14 @@ use std::sync::Arc;
use std::sync::atomic::Ordering;
use anyhow::{Context as _, Result};
use ironrdp_server::{RdpServer, RdpServerInputHandler, TransportTls};
use ironrdp_server::{CliprdrServerFactory, RdpServer, RdpServerInputHandler, TransportTls};
use tokio::io::{AsyncRead, AsyncWrite};
use crate::capture::{HostDisplay, PumpControl};
use crate::mux;
use crate::rdcleanpath::{self, CleanPathStream};
use crate::tls::ServerIdentity;
use crate::video::VideoControl;
/// The `server_addr` field of our RDCleanPath response. The gateway reports the resolved
/// address of the RDP server it dialled; the client does not use it. The server is this
@@ -27,8 +29,14 @@ pub enum SessionEnd {
Refused(String),
}
/// Runs one session to completion. The returned future is `!Send` (ironrdp-server uses
/// `Rc` internally): drive it on a current-thread runtime.
type BoxedReader = Box<dyn AsyncRead + Unpin + Send + Sync>;
type BoxedWriter = Box<dyn AsyncWrite + Unpin + Send + Sync>;
/// Runs one session to completion. `video` is set when this host can encode H.264: a browser
/// that asks for it then gets the framed stream (`crate::mux`) and video beside RDP. The
/// returned future is `!Send` (ironrdp-server uses `Rc` internally): drive it on a
/// current-thread runtime.
#[allow(clippy::too_many_arguments)]
pub async fn run_session<R, W>(
mut reader: R,
mut writer: W,
@@ -36,6 +44,8 @@ pub async fn run_session<R, W>(
display: HostDisplay,
ctl: Arc<PumpControl>,
input: Box<dyn RdpServerInputHandler>,
clipboard: Option<Box<dyn CliprdrServerFactory>>,
video: Option<Arc<VideoControl>>,
) -> Result<SessionEnd>
where
R: AsyncRead + Unpin + Send + Sync + 'static,
@@ -63,14 +73,20 @@ where
}
};
let stream = CleanPathStream::new(
reader,
writer,
accepted,
request.leftover,
SERVER_ADDR.to_owned(),
identity.cert_chain.clone(),
);
let (reader, writer, leftover): (BoxedReader, BoxedWriter, Vec<u8>) =
match video.filter(|_| mux::wants_video(request.pdu.destination.as_deref())) {
Some(control) => {
tracing::info!("the browser takes H.264 video");
let on_video = Arc::clone(&control);
let muxed = mux::start(reader, writer, request.leftover, Box::new(move |m| on_video.on_message(m)));
control.attach(muxed.out);
(Box::new(muxed.reader), Box::new(muxed.writer), Vec::new())
}
None => (Box::new(reader), Box::new(writer), request.leftover),
};
let stream =
CleanPathStream::new(reader, writer, accepted, leftover, SERVER_ADDR.to_owned(), identity.cert_chain.clone());
let eof = stream.eof_flag();
let peer_closed = stream.peer_closed_flag();
@@ -80,6 +96,7 @@ where
.with_input_handler(InputBox(input))
.with_display_handler(display)
.with_display_suppressed_handle(Arc::clone(&ctl.suppressed))
.with_cliprdr_factory(clipboard)
.build();
let result = server.run_connection_with(stream, TransportTls::AlreadyDone).await.context("RDP connection");
+462
View File
@@ -0,0 +1,462 @@
//! H.264 video for the browser beside RDP (README, Video).
//!
//! When the browser asked for it and an encoder exists, the capture pump sends the screen as
//! H.264 on the [`crate::mux::VIDEO`] channel instead of RDP bitmaps; the browser decodes it
//! with WebCodecs (in hardware where it can) and draws it over the RDP client's canvas, which
//! keeps doing input, cursor and clipboard. Without an encoder (Windows PE, Server Core) or
//! after any encoder failure, RDP bitmaps (RemoteFX) carry the screen as before.
//!
//! Messages on the video channel (first byte is the type):
//!
//! | Type | Direction | Payload |
//! |---|---|---|
//! | 1 `START` | host -> browser | JSON `{width,height,codedWidth,codedHeight,encoder,hardware}`: a new stream; a key frame follows |
//! | 2 `FRAME` | host -> browser | flags u8 (bit 0: key frame), sequence u32 LE, H.264 Annex B |
//! | 3 `STOP` | host -> browser | JSON `{reason}`: RDP bitmaps carry the screen again |
//! | 0x81 `ACK` | browser -> host | sequence u32 LE of a frame the browser has drawn (or dropped) |
//! | 0x82 `KEY` | browser -> host | none: the decoder needs a key frame |
//! | 0x83 `OFF` | browser -> host | none: this browser cannot show the video; RDP bitmaps for the rest of the session |
use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
use std::sync::{Arc, OnceLock};
use std::time::Instant;
use anyhow::Result;
use rayon::prelude::*;
use crate::capture::FrameRef;
use crate::mux::Outbound;
pub const START: u8 = 1;
pub const FRAME: u8 = 2;
pub const STOP: u8 = 3;
pub const ACK: u8 = 0x81;
pub const KEY: u8 = 0x82;
pub const OFF: u8 = 0x83;
/// Frames the browser may have unacknowledged before the pump waits: past this the link
/// or the decoder is behind, and skipping frames keeps the picture current instead of late.
const MAX_IN_FLIGHT: u32 = 4;
/// Frames encoded after the screen stops changing, so the last picture sharpens.
const REFINE_FRAMES: u32 = 3;
/// Encodes in a row without any output before an encoder is considered broken.
const SILENT_LIMIT: u32 = 15;
/// One encoded access unit.
pub struct EncodedFrame {
/// H.264 Annex B; a key frame carries its SPS and PPS.
pub data: Vec<u8>,
pub key: bool,
}
/// An H.264 encoder for one frame size.
pub trait VideoEncoder: Send {
/// Shown to the operator (e.g. "NVIDIA H.264 Encoder MFT").
fn name(&self) -> &str;
fn hardware(&self) -> bool;
/// Encodes one NV12 picture (`coded` size) at `time` (100 ns units); returns whatever the
/// encoder has finished (usually this picture, possibly nothing yet).
fn encode(&mut self, nv12: &[u8], time: i64, key: bool) -> Result<Vec<EncodedFrame>>;
}
/// Makes an encoder for (coded width, coded height, fps, hardware allowed).
pub type EncoderFactory = Box<dyn Fn(u32, u32, u32, bool) -> Result<Box<dyn VideoEncoder>> + Send>;
/// State shared between the session (browser messages) and the capture pump.
#[derive(Default)]
pub struct VideoControl {
out: OnceLock<Outbound>,
keyframe: AtomicBool,
/// The browser gave up on the video.
off: AtomicBool,
/// One past the highest sequence the browser acknowledged.
acked: AtomicU32,
}
impl VideoControl {
/// The browser accepted video: frames can go out now.
pub fn attach(&self, out: Outbound) {
let _ = self.out.set(out);
}
pub fn attached(&self) -> bool {
self.out.get().is_some()
}
/// A message from the browser.
pub fn on_message(&self, message: &[u8]) {
match message {
[ACK, a, b, c, d, ..] => {
self.acked.fetch_max(u32::from_le_bytes([*a, *b, *c, *d]).wrapping_add(1), Ordering::Relaxed);
}
[KEY, ..] => self.keyframe.store(true, Ordering::Relaxed),
[OFF, ..] => {
tracing::warn!("the browser cannot show the H.264 video; using RDP bitmaps");
self.off.store(true, Ordering::Relaxed);
}
_ => {}
}
}
fn send(&self, message: Vec<u8>) -> bool {
self.out.get().is_some_and(|o| o.send_video(message))
}
}
/// The pump's video state: owns the encoder and decides when to encode.
pub struct VideoPath {
control: Arc<VideoControl>,
factory: EncoderFactory,
fps: u32,
encoder: Option<(Box<dyn VideoEncoder>, (u32, u32))>,
/// A frame size no encoder could take (RDP bitmaps serve it).
refused: Option<(u32, u32)>,
/// A hardware encoder failed this session: software only from now on.
software_only: bool,
nv12: Vec<u8>,
seq: u32,
pending: bool,
refine: u32,
silent: u32,
started: Instant,
}
/// Coded size for a frame: even (4:2:0 chroma), the extra row/column repeats the edge.
pub fn coded_size(width: usize, height: usize) -> (u32, u32) {
let even = |v: usize| u32::try_from(v + (v & 1)).unwrap_or(u32::MAX);
(even(width), even(height))
}
impl VideoPath {
pub fn new(control: Arc<VideoControl>, factory: EncoderFactory, fps: u32) -> Self {
Self {
control,
factory,
fps,
encoder: None,
refused: None,
software_only: false,
nv12: Vec::new(),
seq: 0,
pending: true,
refine: 0,
silent: 0,
started: Instant::now(),
}
}
/// Whether video carries a frame of this size (else RDP bitmaps do).
pub fn handles(&self, frame: &FrameRef<'_>) -> bool {
self.control.attached()
&& !self.control.off.load(Ordering::Relaxed)
&& self.refused != Some(coded_size(frame.width, frame.height))
}
/// RDP bitmaps take over: true when video was carrying the picture until now (so RDP must
/// send a complete frame).
pub fn hand_back(&mut self) -> bool {
self.encoder.take().is_some()
}
/// One pump tick with video in charge. `changed`: the screen changed since the last tick.
/// Returns false when video just gave up on this size: RDP must send a full frame now.
pub fn tick(&mut self, frame: &FrameRef<'_>, changed: bool) -> bool {
let size = coded_size(frame.width, frame.height);
if changed {
self.pending = true;
self.refine = REFINE_FRAMES;
}
let mut key = self.control.keyframe.swap(false, Ordering::Relaxed);
if self.encoder.as_ref().is_none_or(|(_, s)| *s != size) {
self.encoder = None;
match (self.factory)(size.0, size.1, self.fps, !self.software_only) {
Ok(encoder) => {
tracing::info!(
encoder = encoder.name(),
hardware = encoder.hardware(),
width = size.0,
height = size.1,
"H.264 video"
);
let start = serde_json::json!({
"width": frame.width, "height": frame.height,
"codedWidth": size.0, "codedHeight": size.1,
"encoder": encoder.name(), "hardware": encoder.hardware(),
});
let mut message = vec![START];
message.extend_from_slice(start.to_string().as_bytes());
self.control.send(message);
self.encoder = Some((encoder, size));
self.pending = true;
self.silent = 0;
key = true;
}
Err(e) => return self.give_up(size, &format!("{e:#}")),
}
}
if !self.pending && self.refine == 0 && !key {
return true;
}
let in_flight = self.seq.saturating_sub(self.control.acked.load(Ordering::Relaxed));
if in_flight >= MAX_IN_FLIGHT && !key {
// The browser is behind: skip this tick, the change stays pending.
return true;
}
bgrx_to_nv12(frame, size, &mut self.nv12);
let time = i64::try_from(self.started.elapsed().as_nanos() / 100).unwrap_or(i64::MAX);
let Some((encoder, _)) = self.encoder.as_mut() else { return true };
let hardware = encoder.hardware();
let frames = match encoder.encode(&self.nv12, time, key) {
Ok(f) => f,
Err(e) => return self.encoder_failed(size, hardware, &format!("{e:#}")),
};
if frames.is_empty() {
self.silent += 1;
if self.silent >= SILENT_LIMIT {
return self.encoder_failed(size, hardware, "the encoder produced no output");
}
} else {
self.silent = 0;
}
for f in frames {
let mut message = Vec::with_capacity(f.data.len() + 6);
message.push(FRAME);
message.push(u8::from(f.key));
message.extend_from_slice(&self.seq.to_le_bytes());
message.extend_from_slice(&f.data);
self.seq = self.seq.wrapping_add(1);
if !self.control.send(message) {
break;
}
}
if self.pending {
self.pending = false;
} else {
self.refine = self.refine.saturating_sub(1);
}
true
}
fn encoder_failed(&mut self, size: (u32, u32), hardware: bool, reason: &str) -> bool {
self.encoder = None;
if hardware {
// Try the software encoder next tick (a new stream starts with a key frame).
tracing::warn!(reason, "hardware H.264 encoder failed; using software");
self.software_only = true;
self.pending = true;
return true;
}
self.give_up(size, reason)
}
fn give_up(&mut self, size: (u32, u32), reason: &str) -> bool {
tracing::warn!(
reason,
width = size.0,
height = size.1,
"no H.264 video for this screen size; using RDP bitmaps"
);
self.encoder = None;
self.refused = Some(size);
let mut message = vec![STOP];
message.extend_from_slice(serde_json::json!({ "reason": reason }).to_string().as_bytes());
self.control.send(message);
false
}
}
/// BGRX (32 bpp) to NV12 at `coded` size (BT.709, limited range, 2x2 averaged chroma); the
/// rows and columns past the frame repeat its last row and column.
pub fn bgrx_to_nv12(frame: &FrameRef<'_>, coded: (u32, u32), out: &mut Vec<u8>) {
let (cw, ch) = (coded.0 as usize, coded.1 as usize);
out.resize(cw * ch * 3 / 2, 0);
if frame.width == 0 || frame.height == 0 {
return;
}
let (luma, chroma) = out.split_at_mut(cw * ch);
let last_x = frame.width - 1;
let last_y = frame.height - 1;
let pixel = |x: usize, y: usize| -> (i32, i32, i32) {
let i = y.min(last_y) * frame.stride + x.min(last_x) * 4;
let p = &frame.data[i..i + 3];
(i32::from(p[2]), i32::from(p[1]), i32::from(p[0]))
};
luma.par_chunks_mut(cw * 2).zip(chroma.par_chunks_mut(cw)).enumerate().for_each(|(pair, (y2, uv))| {
let y0 = pair * 2;
for (row, line) in y2.chunks_mut(cw).enumerate() {
for (x, out) in line.iter_mut().enumerate() {
let (r, g, b) = pixel(x, y0 + row);
*out = (((47 * r + 157 * g + 16 * b + 128) >> 8) + 16) as u8;
}
}
for (cx, out) in uv.as_chunks_mut::<2>().0.iter_mut().enumerate() {
let (mut r, mut g, mut b) = (0, 0, 0);
for (dx, dy) in [(0, 0), (1, 0), (0, 1), (1, 1)] {
let p = pixel(cx * 2 + dx, y0 + dy);
r += p.0;
g += p.1;
b += p.2;
}
out[0] = (((-26 * r - 86 * g + 112 * b + 512) >> 10) + 128).clamp(0, 255) as u8;
out[1] = (((112 * r - 102 * g - 10 * b + 512) >> 10) + 128).clamp(0, 255) as u8;
}
});
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::Mutex;
fn solid(width: usize, height: usize, bgrx: [u8; 4]) -> Vec<u8> {
bgrx.repeat(width * height)
}
#[test]
fn colours_convert_to_limited_range_bt709() {
for (bgrx, y, u, v) in [
([255, 255, 255, 0], 235, 128, 128),
([0, 0, 0, 0], 16, 128, 128),
([0, 0, 255, 0], 63, 102, 240), // red
([255, 0, 0, 0], 32, 240, 118), // blue
] {
let data = solid(3, 3, bgrx);
let frame = FrameRef { data: &data, stride: 12, width: 3, height: 3 };
let mut out = Vec::new();
bgrx_to_nv12(&frame, coded_size(3, 3), &mut out);
assert_eq!(out.len(), 4 * 4 * 3 / 2);
assert!(out[..16].iter().all(|&p| p == y), "{bgrx:?}: luma {:?}", &out[..16]);
assert!(out[16..].chunks(2).all(|c| c == [u, v]), "{bgrx:?}: chroma {:?}", &out[16..]);
}
}
#[test]
fn odd_sizes_are_padded_by_repeating_the_edge() {
assert_eq!(coded_size(1366, 767), (1366, 768));
let mut data = solid(3, 1, [0, 0, 0, 0]);
data[8..12].copy_from_slice(&[255, 255, 255, 0]);
let frame = FrameRef { data: &data, stride: 12, width: 3, height: 1 };
let mut out = Vec::new();
bgrx_to_nv12(&frame, coded_size(3, 1), &mut out);
assert_eq!(&out[..8], &[16, 16, 235, 235, 16, 16, 235, 235]);
}
struct FakeEncoder {
log: Arc<Mutex<Vec<bool>>>,
hardware: bool,
fail: bool,
}
impl VideoEncoder for FakeEncoder {
fn name(&self) -> &str {
"fake"
}
fn hardware(&self) -> bool {
self.hardware
}
fn encode(&mut self, _: &[u8], _: i64, key: bool) -> Result<Vec<EncodedFrame>> {
if self.fail {
anyhow::bail!("broken");
}
self.log.lock().unwrap().push(key);
Ok(vec![EncodedFrame { data: vec![0, 0, 0, 1, 0x65], key }])
}
}
type Outbox = tokio::sync::mpsc::Receiver<(u8, bytes::Bytes)>;
fn path(hardware_fails: bool) -> (VideoPath, Arc<VideoControl>, Arc<Mutex<Vec<bool>>>, Outbox) {
let control = Arc::new(VideoControl::default());
let (tx, rx) = tokio::sync::mpsc::channel(256);
control.attach(crate::mux::Outbound::for_tests(tx));
let log = Arc::new(Mutex::new(Vec::new()));
let encodes = Arc::clone(&log);
let factory: EncoderFactory = Box::new(move |_, _, _, hw| {
Ok(Box::new(FakeEncoder { log: Arc::clone(&encodes), hardware: hw, fail: hw && hardware_fails })
as Box<dyn VideoEncoder>)
});
(VideoPath::new(Arc::clone(&control), factory, 30), control, log, rx)
}
fn kinds(rx: &mut Outbox) -> Vec<u8> {
std::iter::from_fn(|| rx.try_recv().ok()).map(|(_, m)| m[0]).collect()
}
#[test]
fn starts_with_a_key_frame_refines_then_idles() {
let (mut video, control, log, mut rx) = path(false);
let data = solid(4, 2, [1, 2, 3, 0]);
let frame = FrameRef { data: &data, stride: 16, width: 4, height: 2 };
assert!(video.tick(&frame, true));
for _ in 0..10 {
control.on_message(&[ACK, 0, 0, 0, 0]);
assert!(video.tick(&frame, false));
}
assert_eq!(
*log.lock().unwrap(),
vec![true, false, false, false],
"key frame, then three refinements, then nothing"
);
assert_eq!(kinds(&mut rx), vec![START, FRAME, FRAME, FRAME, FRAME]);
control.on_message(&[KEY]);
assert!(video.tick(&frame, false));
assert_eq!(log.lock().unwrap().last(), Some(&true), "the browser's key frame request is honoured");
}
#[test]
fn waits_for_the_browser_when_too_many_frames_are_unacknowledged() {
let (mut video, control, log, _rx) = path(false);
let data = solid(4, 2, [1, 2, 3, 0]);
let frame = FrameRef { data: &data, stride: 16, width: 4, height: 2 };
for _ in 0..10 {
video.tick(&frame, true);
}
assert_eq!(log.lock().unwrap().len(), MAX_IN_FLIGHT as usize);
control.on_message(&[ACK, 1, 0, 0, 0]);
video.tick(&frame, false);
assert_eq!(
log.lock().unwrap().len(),
MAX_IN_FLIGHT as usize + 1,
"the pending change goes out once acknowledged"
);
}
#[test]
fn a_failing_hardware_encoder_falls_back_to_software() {
let (mut video, _control, log, mut rx) = path(true);
let data = solid(4, 2, [1, 2, 3, 0]);
let frame = FrameRef { data: &data, stride: 16, width: 4, height: 2 };
assert!(video.tick(&frame, true), "hardware failed, software comes next");
assert!(video.tick(&frame, false));
assert_eq!(*log.lock().unwrap(), vec![true]);
assert_eq!(kinds(&mut rx), vec![START, START, FRAME]);
}
#[test]
fn a_browser_that_cannot_decode_turns_video_off() {
let (mut video, control, _log, _rx) = path(false);
let data = solid(4, 2, [1, 2, 3, 0]);
let frame = FrameRef { data: &data, stride: 16, width: 4, height: 2 };
assert!(video.tick(&frame, true));
control.on_message(&[OFF]);
assert!(!video.handles(&frame));
assert!(video.hand_back(), "RDP sends a complete frame");
assert!(!video.hand_back(), "only once");
}
#[test]
fn no_encoder_hands_the_size_back_to_rdp() {
let control = Arc::new(VideoControl::default());
let (tx, mut rx) = tokio::sync::mpsc::channel(8);
control.attach(crate::mux::Outbound::for_tests(tx));
let mut video = VideoPath::new(Arc::clone(&control), Box::new(|_, _, _, _| anyhow::bail!("too large")), 30);
let data = solid(4, 2, [1, 2, 3, 0]);
let frame = FrameRef { data: &data, stride: 16, width: 4, height: 2 };
assert!(video.handles(&frame));
assert!(!video.tick(&frame, true));
assert!(!video.handles(&frame));
assert_eq!(kinds(&mut rx), vec![STOP]);
}
}
+3 -2
View File
@@ -129,7 +129,7 @@ async fn run_e2e(pattern: TestPattern, view_only: bool, max_fps: u32, min_update
Box::new(pattern),
tx,
ctl,
PumpConfig { max_fps },
PumpConfig { max_fps, video: None },
|_| {},
|x, y| coords.set_origin(x, y),
);
@@ -145,7 +145,8 @@ async fn run_e2e(pattern: TestPattern, view_only: bool, max_fps: u32, min_update
let (server_read, server_write) = tokio::io::split(server_side);
let start = Instant::now();
let server = session::run_session(server_read, server_write, identity, display, Arc::clone(&ctl), input);
let server =
session::run_session(server_read, server_write, identity, display, Arc::clone(&ctl), input, None, None);
let client = common::run_client(client_side, true, min_updates, Duration::from_secs(60));
let (server_result, client_result) = tokio::join!(server, client);
let elapsed = start.elapsed();
+16
View File
@@ -158,6 +158,22 @@ impl UpdateEncoder {
BitmapUpdater::Bitmap(BitmapHandler::new())
};
// ExecuteR patch: name the negotiated codec (the first thing to check when a session feels slow).
tracing::info!(
codec = match &bitmap_updater {
BitmapUpdater::None(_) => "none",
BitmapUpdater::Bitmap(_) => "bitmap",
BitmapUpdater::RemoteFx(_) => "remotefx",
#[cfg(feature = "qoi")]
BitmapUpdater::Qoi(_) => "qoi",
#[cfg(feature = "qoiz")]
BitmapUpdater::Qoiz(_) => "qoiz",
#[cfg(feature = "nscodec")]
BitmapUpdater::NsCodec(_) => "nscodec",
},
"bitmap codec"
);
Ok(Self {
desktop_size,
framebuffer: None,
+2
View File
@@ -1422,6 +1422,8 @@ impl RdpServer {
surface_flags = c.flags;
}
CapabilitySet::BitmapCodecs(BitmapCodecs(codecs)) => {
// ExecuteR patch: what the client offers, next to what the encoder picks.
debug!(offered = ?codecs.iter().map(|c| format!("{:?}", c.property).chars().take(24).collect::<String>()).collect::<Vec<_>>(), "client bitmap codecs");
for codec in codecs {
match codec.property {
// FIXME: The encoder operates in image mode only.
+15 -4
View File
@@ -348,7 +348,8 @@ public sealed record ScriptDto(
bool SetWorkingDirectory = false,
RestartAfterRun RestartAfterRun = RestartAfterRun.Off,
int RestartDelaySeconds = 0,
int RestartWarningSeconds = 0);
int RestartWarningSeconds = 0,
bool RunAsUser = false);
/// <summary>
/// POST/PUT /api/scripts request body. <c>Folder</c> places the script ("/"
@@ -358,6 +359,8 @@ public sealed record ScriptDto(
/// (0 to <see cref="RestartOptions.MaxDelaySeconds"/>) and <c>RestartWarningSeconds</c> (Warn
/// Signed-In Users: 0 for off, otherwise <see cref="RestartOptions.MinWarningSeconds"/> to
/// <see cref="RestartOptions.MaxWarningSeconds"/>) left out keep theirs too (off, 0 and off).
/// <c>RunAsUser</c> (run as the signed-in user instead of the agent's account) left out keeps
/// the stored value (off for a new script).
/// </summary>
public sealed record SaveScriptRequest(
string Name,
@@ -378,7 +381,8 @@ public sealed record SaveScriptRequest(
bool? SetWorkingDirectory = null,
RestartAfterRun? RestartAfterRun = null,
int? RestartDelaySeconds = null,
int? RestartWarningSeconds = null);
int? RestartWarningSeconds = null,
bool? RunAsUser = null);
/// <summary>A folder of a library (scripts, functions).</summary>
public sealed record FolderDto(string Path, string Name);
@@ -608,12 +612,19 @@ public sealed record JobOutputRecordDto(
DateTimeOffset TimestampUtc,
string Text);
/// <summary>POST /api/devices/{clientId}/shell request body; <c>Shell</c> is a <see cref="ShellKinds"/> value (null = automatic).</summary>
/// <summary>
/// POST /api/devices/{clientId}/shell request body; <c>Shell</c> is a <see cref="ShellKinds"/> value (null = automatic).
/// <c>AsUser</c> starts it as the device's signed-in user instead of the agent's account;
/// <c>User</c> names which of them (one the agent listed as signed in; null = the console's user,
/// else the only one).
/// </summary>
public sealed record CreateShellRequest(
string BrowserSessionId,
int Cols,
int Rows,
string? Shell = null);
string? Shell = null,
bool AsUser = false,
string? User = null);
/// <summary>POST /api/devices/{clientId}/shell response body.</summary>
public sealed record CreateShellResponse(
+21 -6
View File
@@ -101,6 +101,9 @@ public sealed record ScriptFileDelivery(
/// <see cref="RestartOptions.MinWarningSeconds"/> to <see cref="RestartOptions.MaxWarningSeconds"/>)
/// is the system's warning to signed-in users when the restart comes due and someone is signed
/// in. Older agents ignore it and hand the delay to the system as its grace period.
/// <see cref="RunAsUser"/> runs the script as the device's signed-in user (out of process,
/// whatever the engine); the server never sends it to agents older than
/// <see cref="Shared.Contracts.Models.RunAsUser.MinimumAgentVersion"/>, which would ignore it.
/// </summary>
public sealed record ScriptCommandPayload(
Guid JobId,
@@ -125,7 +128,8 @@ public sealed record ScriptCommandPayload(
JobTrigger? Trigger = null,
RestartAfterRun RestartAfterRun = RestartAfterRun.Off,
int RestartDelaySeconds = 0,
int RestartWarningSeconds = 0)
int RestartWarningSeconds = 0,
bool RunAsUser = false)
{
/// <summary>The command's Restart After Run as one record.</summary>
[System.Text.Json.Serialization.JsonIgnore]
@@ -271,7 +275,8 @@ public sealed record JobStatePayload(
int? RestartDelaySeconds = null,
string? RestartMessage = null,
DateTimeOffset? RestartBootUtc = null,
DateTimeOffset? RestartDueUtc = null);
DateTimeOffset? RestartDueUtc = null,
IReadOnlyList<GroupMembershipReport>? GroupMemberships = null);
/// <summary>
/// A job's restart: a request on the agent event subject (<see cref="MessageTypes.AgentJobRestart"/>),
@@ -331,13 +336,18 @@ public sealed record RestartCancelCommandPayload(Guid JobId, string Message, str
/// <summary>
/// Opens a remote shell; sent on <c>agent.&lt;clientId&gt;.command.shell.open</c>.
/// <c>Shell</c> is a <see cref="ShellKinds"/> value (null = automatic); unix
/// agents, and agents that predate it, ignore it.
/// agents, and agents that predate it, ignore it. <c>AsUser</c> starts the shell as the
/// signed-in user; the server refuses it for agents older than
/// <see cref="Shared.Contracts.Models.RunAsUser.MinimumAgentVersion"/>. <c>User</c> picks which
/// signed-in user (refused unless they are signed in); null applies the usual rule.
/// </summary>
public sealed record ShellOpenCommandPayload(
Guid SessionId,
int Cols,
int Rows,
string? Shell = null);
string? Shell = null,
bool AsUser = false,
string? User = null);
/// <summary>Terminal input bytes (base64) for an open shell session.</summary>
public sealed record ShellInputPayload(
@@ -363,13 +373,18 @@ public sealed record ShellOutputPayload(
/// <summary>
/// Shell session state on <c>agent.&lt;clientId&gt;.shell.&lt;sessionId&gt;.state</c>.
/// <c>Shell</c> is the <see cref="ShellKinds"/> value started (Windows agents, on <c>Open</c>).
/// <c>Shell</c> is the <see cref="ShellKinds"/> value started (Windows agents, on <c>Open</c>);
/// <c>User</c> the account it runs as when started as the signed-in user. <c>SignedInUsers</c>
/// lists who is signed in on the device (on <c>Open</c>, and on a <c>Failed</c> run-as-user open),
/// for the console to offer.
/// </summary>
public sealed record ShellStatePayload(
Guid SessionId,
ShellSessionState State,
string? Message,
string? Shell = null);
string? Shell = null,
string? User = null,
IReadOnlyList<string>? SignedInUsers = null);
/// <summary>System event: a device enrolled.</summary>
public sealed record AgentEnrolledEvent(
+37 -2
View File
@@ -2,16 +2,51 @@ namespace Shared.Contracts.Models;
/// <summary>
/// Static groups hold an explicit member list; dynamic groups evaluate rules;
/// folders hold no devices of their own and only organize nested groups.
/// Every kind also includes the devices of the groups nested under it.
/// folders hold no devices of their own and only organize nested groups;
/// script groups hold the devices whose scripts last reported them members
/// (<see cref="ScriptGroups"/>). Every kind also includes the devices of the
/// groups nested under it.
/// </summary>
public enum GroupKind
{
Static,
Dynamic,
Folder,
Script,
}
/// <summary>
/// Script groups: a script on the device says whether the device belongs (the built-in
/// <c>Set-ExecuteRGroupMembership</c>, or <c>executer_group</c> in Bash), the agent sends that with
/// the job's final state, and the server adds or removes the device, creating the group the first
/// time a device joins it. Each run says it again, so membership follows the device.
/// </summary>
public static class ScriptGroups
{
/// <summary>The line the built-ins write; the agent takes it out of the output.</summary>
public const string Marker = "::executer-group::";
/// <summary>The most groups one job may report on (the rest are ignored).</summary>
public const int MaxReportsPerJob = 25;
public const int MaxNameLength = 100;
/// <summary>Kinds whose members are rows (static, script), not rules.</summary>
public static bool HasMemberRows(GroupKind kind) => kind is GroupKind.Static or GroupKind.Script;
/// <summary>A usable group name (trimmed, no control characters or slashes, 1 to 100 long), or null.</summary>
public static string? Normalize(string? name)
{
var trimmed = name?.Trim();
return string.IsNullOrEmpty(trimmed) || trimmed.Length > MaxNameLength || trimmed.Any(c => char.IsControl(c) || c is '/' or '\\')
? null
: trimmed;
}
}
/// <summary>A device's own report that it belongs (or no longer belongs) in the named script group.</summary>
public sealed record GroupMembershipReport(string Group, bool Member);
/// <summary>How sibling conditions (or sibling groups) combine.</summary>
public enum RuleCombine
{
+19
View File
@@ -0,0 +1,19 @@
namespace Shared.Contracts.Models;
/// <summary>
/// Running a shell or a script as the device's signed-in user instead of the agent's own
/// account (LocalSystem, root). Agents older than <see cref="MinimumAgentVersion"/> ignore the
/// request and would run as the agent's account, so the server refuses it for them.
/// </summary>
public static class RunAsUser
{
/// <summary>The first agent version that honors the request.</summary>
public const string MinimumAgentVersion = "1.13.0";
/// <summary>True when an agent at <paramref name="agentVersion"/> honors the request.</summary>
public static bool Supported(string? agentVersion) => AgentVersions.Compare(agentVersion, MinimumAgentVersion) >= 0;
/// <summary>Why an agent at <paramref name="agentVersion"/> cannot run as the signed-in user.</summary>
public static string Unsupported(string? agentVersion) =>
$"The agent ({(string.IsNullOrWhiteSpace(agentVersion) ? "unknown version" : agentVersion)}) cannot run as the signed-in user; upgrade it to {MinimumAgentVersion} or later.";
}
@@ -1,25 +1,24 @@
using System.Globalization;
using Serilog.Core;
using Serilog.Events;
using Serilog.Formatting.Display;
using Shared.Contracts.Api;
namespace Shared.Infrastructure.Logging;
/// <summary>Feeds every event the logger writes into a <see cref="LiveLog"/>, rendered as the log file renders it.</summary>
public sealed class LiveLogSink(LiveLog live) : ILogEventSink
/// <summary>
/// Feeds every event the logger writes into a <see cref="LiveLog"/>, rendered as the log file
/// renders it (the message, then its unused properties as <c>key=value</c>). The source is the
/// full SourceContext, or the application when there is none; a viewer shortens it to the
/// category as <see cref="LogLineFormatter.Category(string?, string)"/> does.
/// </summary>
public sealed class LiveLogSink(LiveLog live, string? application = null) : ILogEventSink
{
private static readonly MessageTemplateTextFormatter Message = new("{Message:lj}", CultureInfo.InvariantCulture);
public void Emit(LogEvent logEvent)
{
using var text = new StringWriter(CultureInfo.InvariantCulture);
Message.Format(logEvent, text);
live.Append(
logEvent.Timestamp.ToUniversalTime(),
LevelName(logEvent.Level),
logEvent.Properties.TryGetValue("SourceContext", out var source) && source is ScalarValue { Value: string name } ? name : null,
text.ToString(),
LogLineFormatter.SourceContext(logEvent) ?? application,
LogLineFormatter.RenderMessage(logEvent),
logEvent.Exception?.ToString());
}
@@ -0,0 +1,259 @@
using System.Globalization;
using System.Text;
using System.Text.RegularExpressions;
using Serilog.Events;
using Serilog.Formatting;
using Serilog.Formatting.Json;
using Shared.Contracts.Api;
namespace Shared.Infrastructure.Logging;
/// <summary>
/// ExecuteR's one text log format, for every line any of its processes writes:
/// <c>[2026-11-16T17:53:40.653Z] - [Category] - [LEVEL] - message key=value …</c>.
/// The time is UTC to the millisecond; the category is a short component name (the
/// logging type without its namespace); the level is TRACE, DEBUG, INFO, WARN, ERROR or
/// FATAL; the message is rendered with its strings unquoted, followed by the event's
/// properties the message did not use, as <c>key=value</c> (correlation fields among
/// them; enrichment noise left out). An exception follows on the next lines.
/// </summary>
public sealed partial class LogLineFormatter(string application) : ITextFormatter
{
/// <summary>The timestamp as written: UTC, ISO 8601, milliseconds, Z.</summary>
public const string TimestampFormat = "yyyy-MM-dd'T'HH:mm:ss.fff'Z'";
/// <summary>Properties that say nothing a reader of one line needs (the file already names its machine and process).</summary>
public static readonly IReadOnlySet<string> Unlisted = new HashSet<string>(StringComparer.Ordinal)
{
"SourceContext", "MachineName", "Application", "EventId",
"RequestId", "RequestPath", "ConnectionId", "ActionId", "ActionName",
"SpanId", "TraceId", "ParentId", "Scope", "ThreadId", "ProcessId",
};
private static readonly JsonValueFormatter Json = new(typeTagName: null);
public void Format(LogEvent logEvent, TextWriter output)
{
WriteLine(
output,
logEvent.Timestamp,
Category(logEvent, application),
LevelName(logEvent.Level),
RenderMessage(logEvent));
if (logEvent.Exception is not null)
{
output.Write(logEvent.Exception.ToString());
output.Write(Environment.NewLine);
}
}
/// <summary>One whole line, its newline included.</summary>
public static void WriteLine(TextWriter output, DateTimeOffset timestamp, string category, string level, string message)
{
output.Write('[');
output.Write(timestamp.UtcDateTime.ToString(TimestampFormat, CultureInfo.InvariantCulture));
output.Write("] - [");
output.Write(category);
output.Write("] - [");
output.Write(level);
output.Write("] - ");
output.Write(message);
output.Write(Environment.NewLine);
}
/// <summary>One whole line, without its newline.</summary>
public static string Line(DateTimeOffset timestamp, string category, string level, string message)
{
using var text = new StringWriter(CultureInfo.InvariantCulture);
WriteLine(text, timestamp, category, level, message);
return text.ToString().TrimEnd('\r', '\n');
}
/// <summary>The level as the line spells it.</summary>
public static string LevelName(LogEventLevel level) => level switch
{
LogEventLevel.Verbose => "TRACE",
LogEventLevel.Debug => "DEBUG",
LogEventLevel.Information => "INFO",
LogEventLevel.Warning => "WARN",
LogEventLevel.Error => "ERROR",
_ => "FATAL",
};
/// <summary>The level as the line spells it, from a <see cref="LogLevels"/> name.</summary>
public static string LevelName(string level) => level switch
{
LogLevels.Verbose => "TRACE",
LogLevels.Debug => "DEBUG",
LogLevels.Warning => "WARN",
LogLevels.Error => "ERROR",
LogLevels.Fatal => "FATAL",
_ => "INFO",
};
/// <summary>The event's category: its SourceContext shortened, or the application.</summary>
public static string Category(LogEvent logEvent, string application)
=> Category(SourceContext(logEvent), application);
/// <summary>
/// A short component name from a logger's category: the type name without its
/// namespace or generic arguments, a nested type as <c>Outer.Inner</c>
/// (<c>Agent.Screen.ScreenHost+Session</c> is <c>ScreenHost.Session</c>). Nothing → <paramref name="fallback"/>.
/// </summary>
public static string Category(string? sourceContext, string fallback)
{
if (string.IsNullOrWhiteSpace(sourceContext))
{
return fallback;
}
var name = sourceContext.Trim();
var generic = name.IndexOfAny(['[', '<']);
if (generic > 0)
{
name = name[..generic];
}
name = Arity().Replace(name, string.Empty);
var parts = name.Split('+', StringSplitOptions.RemoveEmptyEntries);
if (parts.Length == 0)
{
return fallback;
}
parts[0] = parts[0][(parts[0].LastIndexOf('.') + 1)..];
var category = string.Join('.', parts.Where(p => p.Length > 0));
return category.Length > 0 ? category : fallback;
}
/// <summary>The SourceContext of an event, when it has one.</summary>
public static string? SourceContext(LogEvent logEvent)
=> logEvent.Properties.TryGetValue("SourceContext", out var source) && source is ScalarValue { Value: string name } ? name : null;
/// <summary>The message as rendered, then the properties it did not use as <c>key=value</c>.</summary>
public static string RenderMessage(LogEvent logEvent)
{
using var text = new StringWriter(CultureInfo.InvariantCulture);
WriteMessage(logEvent, text);
AppendProperties(logEvent, text);
return text.ToString();
}
/// <summary>
/// The message as <c>{Message:lj}</c> renders it (strings bare, structures as JSON), except
/// that other scalars are bare too: a Guid or a time reads as itself, not as a JSON string.
/// </summary>
public static void WriteMessage(LogEvent logEvent, TextWriter output)
{
foreach (var token in logEvent.MessageTemplate.Tokens)
{
if (token is not Serilog.Parsing.PropertyToken property)
{
token.Render(logEvent.Properties, output, CultureInfo.InvariantCulture);
}
else if (!logEvent.Properties.TryGetValue(property.PropertyName, out var value))
{
output.Write(property.ToString());
}
else if (value is ScalarValue { Value: string text })
{
output.Write(text);
}
else if (value is ScalarValue scalar)
{
scalar.Render(output, property.Format, CultureInfo.InvariantCulture);
}
else
{
Json.Format(value, output);
}
}
}
/// <summary>Writes <c> key=value</c> for each property of the event its message template does not name.</summary>
public static void AppendProperties(LogEvent logEvent, TextWriter output)
{
HashSet<string>? used = null;
foreach (var token in logEvent.MessageTemplate.Tokens)
{
if (token is Serilog.Parsing.PropertyToken property)
{
(used ??= new HashSet<string>(StringComparer.Ordinal)).Add(property.PropertyName);
}
}
foreach (var (name, value) in logEvent.Properties)
{
if (Unlisted.Contains(name) || (used?.Contains(name) ?? false))
{
continue;
}
output.Write(' ');
output.Write(name);
output.Write('=');
output.Write(Value(value));
}
}
/// <summary>A property value as a line shows it: bare, or double-quoted when it holds whitespace, '=' or '"'.</summary>
public static string Value(LogEventPropertyValue value)
{
var text = value switch
{
ScalarValue { Value: null } => "null",
ScalarValue { Value: string s } => Quote(s),
ScalarValue { Value: bool b } => b ? "true" : "false",
ScalarValue { Value: DateTimeOffset d } => d.ToString("O", CultureInfo.InvariantCulture),
ScalarValue { Value: DateTime d } => d.ToString("O", CultureInfo.InvariantCulture),
ScalarValue { Value: IFormattable f } => Quote(f.ToString(null, CultureInfo.InvariantCulture)),
ScalarValue { Value: var v } => Quote(v.ToString() ?? string.Empty),
_ => Quote(JsonText(value)),
};
return text;
}
/// <summary>Double-quotes a value that holds whitespace, '=' or '"' (or is empty), escaping quotes and control characters.</summary>
public static string Quote(string value)
{
if (value.Length > 0 && !value.Any(c => char.IsWhiteSpace(c) || c == '=' || c == '"' || char.IsControl(c)))
{
return value;
}
var quoted = new StringBuilder(value.Length + 2).Append('"');
foreach (var c in value)
{
switch (c)
{
case '"': quoted.Append("\\\""); break;
case '\n': quoted.Append("\\n"); break;
case '\r': quoted.Append("\\r"); break;
case '\t': quoted.Append("\\t"); break;
default:
if (char.IsControl(c))
{
quoted.Append(CultureInfo.InvariantCulture, $"\\u{(int)c:x4}");
}
else
{
quoted.Append(c);
}
break;
}
}
return quoted.Append('"').ToString();
}
private static string JsonText(LogEventPropertyValue value)
{
using var text = new StringWriter(CultureInfo.InvariantCulture);
Json.Format(value, text);
return text.ToString();
}
[GeneratedRegex(@"`\d+")]
private static partial Regex Arity();
}
@@ -0,0 +1,110 @@
using System.Diagnostics.CodeAnalysis;
using System.Globalization;
using System.Text.RegularExpressions;
using Shared.Contracts.Api;
namespace Shared.Infrastructure.Logging;
/// <summary>One log line read back: when, how severe (a <see cref="LogLevels"/> name), from which component, and what.</summary>
public sealed record ParsedLogLine(DateTimeOffset TimestampUtc, string Level, string? Category, string Message);
/// <summary>
/// Reads a text log line back into its parts. Takes ExecuteR's format
/// (<c>[2026-11-16T17:53:40.653Z] - [Category] - [INFO] - message</c>, see
/// <see cref="LogLineFormatter"/>) and what was written before it, still in files on
/// devices: the services' <c>[2026-11-06 12:00:00.000 INF] Source: message</c> (local
/// time), the watchdog's <c>2026-11-06 12:00:00.000Z [INF] message</c>, and a screen
/// host's <c>2026-11-06T12:00:00.000000Z WARN target: message</c>.
/// </summary>
public static partial class LogLineParser
{
public static bool TryParse(string? line, [NotNullWhen(true)] out ParsedLogLine? parsed)
{
parsed = null;
if (string.IsNullOrEmpty(line))
{
return false;
}
if (Current().Match(line) is { Success: true } current)
{
var category = current.Groups["category"].Value;
parsed = new ParsedLogLine(
Utc(current.Groups["time"].Value, "yyyy-MM-dd'T'HH:mm:ss.FFFFFFF'Z'", DateTimeStyles.AssumeUniversal),
Level(current.Groups["level"].Value),
category.Length > 0 ? category : null,
current.Groups["message"].Value);
return true;
}
if (Service().Match(line) is { Success: true } service)
{
var source = service.Groups["source"];
parsed = new ParsedLogLine(
Utc(service.Groups["time"].Value, "yyyy-MM-dd HH:mm:ss.fff", DateTimeStyles.AssumeLocal),
Level(service.Groups["level"].Value),
source.Success && source.Value.Length > 0 ? source.Value : null,
service.Groups["message"].Value);
return true;
}
if (Watchdog().Match(line) is { Success: true } watchdog)
{
parsed = new ParsedLogLine(
Utc(watchdog.Groups["time"].Value, "yyyy-MM-dd HH:mm:ss.fff", DateTimeStyles.AssumeUniversal),
Level(watchdog.Groups["level"].Value),
null,
watchdog.Groups["message"].Value);
return true;
}
if (Tracing().Match(line) is { Success: true } tracing)
{
parsed = new ParsedLogLine(
Utc(tracing.Groups["time"].Value, "yyyy-MM-dd'T'HH:mm:ss.FFFFFFF'Z'", DateTimeStyles.AssumeUniversal),
Level(tracing.Groups["level"].Value),
tracing.Groups["source"].Value,
tracing.Groups["message"].Value);
return true;
}
return false;
}
/// <summary>A <see cref="LogLevels"/> name from any level spelling a line may carry.</summary>
public static string Level(string level) => level.ToUpperInvariant() switch
{
"TRACE" or "VRB" or "VERBOSE" => LogLevels.Verbose,
"DEBUG" or "DBG" => LogLevels.Debug,
"WARN" or "WRN" or "WARNING" => LogLevels.Warning,
"ERROR" or "ERR" => LogLevels.Error,
"FATAL" or "FTL" => LogLevels.Fatal,
_ => LogLevels.Information,
};
private static DateTimeOffset Utc(string text, string format, DateTimeStyles style)
{
// At most 7 fractional digits parse; a screen host writes up to 9.
var dot = text.IndexOf('.', StringComparison.Ordinal);
if (dot > 0 && text.EndsWith('Z') && text.Length - dot - 2 > 7)
{
text = string.Concat(text.AsSpan(0, dot + 8), "Z");
}
return DateTimeOffset.TryParseExact(text, format, CultureInfo.InvariantCulture, style | DateTimeStyles.AdjustToUniversal, out var time)
? time.ToUniversalTime()
: DateTimeOffset.UtcNow;
}
[GeneratedRegex(@"^\[(?<time>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,7})?Z)\] - \[(?<category>[^\]]*)\] - \[(?<level>[A-Z]{4,5})\] - ?(?<message>.*)$")]
private static partial Regex Current();
[GeneratedRegex(@"^\[(?<time>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}) (?<level>[A-Z]{3})\] (?:(?<source>\S*?): )?(?<message>.*)$")]
private static partial Regex Service();
[GeneratedRegex(@"^(?<time>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3})Z \[(?<level>[A-Z]{3})\] (?<message>.*)$")]
private static partial Regex Watchdog();
[GeneratedRegex(@"^(?<time>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z)\s+(?<level>TRACE|DEBUG|INFO|WARN|ERROR) (?<source>[A-Za-z0-9_:]+): (?<message>.*)$")]
private static partial Regex Tracing();
}
@@ -1,59 +1,48 @@
using Serilog;
using Serilog.Core;
using Serilog.Events;
using Serilog.Formatting;
using Serilog.Formatting.Compact;
namespace Shared.Infrastructure.Logging;
/// <summary>
/// Builds the one Serilog pipeline every service uses: console (text or compact
/// JSON) plus a daily rolling file with size caps and retention. Correlation
/// fields (CorrelationId, ClientId, JobId, ShellSessionId, BrowserSessionId,
/// RemoteIp) flow through as structured properties from log scopes.
/// JSON) plus a daily rolling file with size caps and retention. Text lines are
/// ExecuteR's one format (<see cref="LogLineFormatter"/>):
/// <c>[2026-11-16T17:53:40.653Z] - [Category] - [INFO] - message key=value</c>.
/// Correlation fields (CorrelationId, ClientId, JobId, ShellSessionId,
/// BrowserSessionId, RemoteIp) flow through as structured properties from log
/// scopes and show as <c>key=value</c>. A warning or error that repeats is written
/// once and then counted (<see cref="RepeatThrottleSink"/>).
/// Secret material is never logged — see <see cref="Redaction"/>.
/// </summary>
public static class LoggingSetup
{
/// <summary>Human-readable console/file template including correlation context.</summary>
private const string TextTemplate =
"[{Timestamp:yyyy-MM-dd HH:mm:ss.fff} {Level:u3}] {Message:lj}" +
"{#if CorrelationId is not null} correlation={CorrelationId}{#end}" +
"{NewLine}{Exception}";
private const string SimpleTemplate =
"[{Timestamp:yyyy-MM-dd HH:mm:ss.fff} {Level:u3}] {SourceContext}: {Message:lj}{NewLine}{Exception}";
/// <summary>
/// The pipeline for <paramref name="application"/>. With <paramref name="live"/>, every
/// event written also lands in that in-memory ring, for the console's live log views.
/// The pipeline for <paramref name="application"/> (also the category of a line
/// without a SourceContext: <c>Agent</c>, <c>Server</c>). With <paramref name="live"/>,
/// every event written also lands in that in-memory ring, for the console's live log
/// views. Events pass the level filter, the enrichers (redaction last) and the repeat
/// throttle before any sink sees them.
/// </summary>
public static Logger CreateLogger(LogSettings settings, string application, LiveLog? live = null)
public static Logger CreateLogger(LogSettings settings, string application, LiveLog? live = null, TimeProvider? clock = null)
{
var configuration = new LoggerConfiguration()
.MinimumLevel.Is(ParseLevel(settings.Level))
// Framework noise stays at Warning regardless of the app level.
.MinimumLevel.Override("Microsoft", LogEventLevel.Warning)
.MinimumLevel.Override("Microsoft.Hosting.Lifetime", LogEventLevel.Information)
.MinimumLevel.Override("Microsoft.EntityFrameworkCore", LogEventLevel.Warning)
.MinimumLevel.Override("System.Net.Http.HttpClient", LogEventLevel.Warning)
.Enrich.FromLogContext()
.Enrich.WithMachineName()
.Enrich.WithProperty("Application", application)
// Last, so it also sees what log scopes added.
.Enrich.With<RedactionEnricher>();
var sinks = new LoggerConfiguration().MinimumLevel.Verbose();
var text = new LogLineFormatter(application);
if (live is not null)
{
configuration.WriteTo.Sink(new LiveLogSink(live));
sinks.WriteTo.Sink(new LiveLogSink(live, application));
}
if (settings.Json)
{
configuration.WriteTo.Console(new CompactJsonFormatter());
sinks.WriteTo.Console(new CompactJsonFormatter());
}
else
{
configuration.WriteTo.Console(outputTemplate: SimpleTemplate);
sinks.WriteTo.Console(text);
}
if (settings.FileEnabled)
@@ -67,28 +56,14 @@ public static class LoggingSetup
{
Directory.CreateDirectory(settings.Directory!);
if (settings.Json)
{
configuration.WriteTo.File(
new CompactJsonFormatter(),
path,
rollingInterval: RollingInterval.Day,
rollOnFileSizeLimit: true,
fileSizeLimitBytes: settings.FileSizeLimitBytes,
retainedFileCountLimit: settings.RetainedFileCount,
shared: true);
}
else
{
configuration.WriteTo.File(
path,
outputTemplate: SimpleTemplate,
rollingInterval: RollingInterval.Day,
rollOnFileSizeLimit: true,
fileSizeLimitBytes: settings.FileSizeLimitBytes,
retainedFileCountLimit: settings.RetainedFileCount,
shared: true);
}
sinks.WriteTo.File(
settings.Json ? new CompactJsonFormatter() : (ITextFormatter)text,
path,
rollingInterval: RollingInterval.Day,
rollOnFileSizeLimit: true,
fileSizeLimitBytes: settings.FileSizeLimitBytes,
retainedFileCountLimit: settings.RetainedFileCount,
shared: true);
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
@@ -98,7 +73,24 @@ public static class LoggingSetup
}
}
return configuration.CreateLogger();
// The sinks sit behind the repeat throttle, which is behind the filters and
// enrichers: what is counted is already redacted, and disposing the logger
// writes any count still open before the sinks close.
var throttle = new RepeatThrottleSink(sinks.CreateLogger(), clock);
return new LoggerConfiguration()
.MinimumLevel.Is(ParseLevel(settings.Level))
// Framework noise stays at Warning regardless of the app level.
.MinimumLevel.Override("Microsoft", LogEventLevel.Warning)
.MinimumLevel.Override("Microsoft.Hosting.Lifetime", LogEventLevel.Information)
.MinimumLevel.Override("Microsoft.EntityFrameworkCore", LogEventLevel.Warning)
.MinimumLevel.Override("System.Net.Http.HttpClient", LogEventLevel.Warning)
.Enrich.FromLogContext()
.Enrich.WithMachineName()
.Enrich.WithProperty("Application", application)
// Last, so it also sees what log scopes added.
.Enrich.With<RedactionEnricher>()
.WriteTo.Sink(throttle)
.CreateLogger();
}
private static LogEventLevel ParseLevel(string level)
@@ -0,0 +1,286 @@
using System.Globalization;
using Serilog.Core;
using Serilog.Events;
using Serilog.Parsing;
namespace Shared.Infrastructure.Logging;
/// <summary>
/// Keeps a warning, error or fatal that repeats from flooding the log. An event is the
/// same as another when its level, SourceContext and message template are (a template
/// that is only placeholders, such as a relayed <c>{Line}</c>, compares by its rendered
/// text instead). The first is written at once; the same event again within the window
/// is counted, not written; when the window ends with any counted, ONE line is written:
/// the last of them with <c>repeated=N window=60s</c> appended, and a new window starts.
/// A window with none counted forgets the event, so the next one is written at once.
/// At most <see cref="DefaultMaxKeys"/> events are tracked (the oldest goes first, its
/// count written); disposing writes every count still open. Information and below pass
/// straight through.
/// </summary>
public sealed class RepeatThrottleSink : ILogEventSink, IDisposable
{
public static readonly TimeSpan DefaultWindow = TimeSpan.FromSeconds(60);
public const int DefaultMaxKeys = 1000;
/// <summary>The property a summary line carries: how many more times the event happened.</summary>
public const string RepeatedProperty = "repeated";
/// <summary>The property a summary line carries: the window it counts (<c>60s</c>).</summary>
public const string WindowProperty = "window";
private const int RenderedKeyChars = 256;
private readonly ILogEventSink target;
private readonly bool ownsTarget;
private readonly TimeProvider clock;
private readonly TimeSpan window;
private readonly int maxKeys;
private readonly string windowText;
private readonly Lock gate = new();
private readonly Dictionary<Key, Entry> entries = [];
private readonly ITimer? timer;
private long order;
private bool disposed;
/// <param name="target">Where events go (the logger holding the console, file and live sinks).</param>
/// <param name="clock">Time, injectable for tests.</param>
/// <param name="window">How long repeats are counted before one summary line.</param>
/// <param name="maxKeys">How many distinct events are tracked at once.</param>
/// <param name="sweepEvery">How often ended windows are looked for; <see cref="Timeout.InfiniteTimeSpan"/> for never (tests call <see cref="Sweep"/>).</param>
/// <param name="ownsTarget">Dispose <paramref name="target"/> along with this sink.</param>
public RepeatThrottleSink(
ILogEventSink target,
TimeProvider? clock = null,
TimeSpan? window = null,
int maxKeys = DefaultMaxKeys,
TimeSpan? sweepEvery = null,
bool ownsTarget = true)
{
ArgumentNullException.ThrowIfNull(target);
ArgumentOutOfRangeException.ThrowIfLessThan(maxKeys, 1);
this.target = target;
this.ownsTarget = ownsTarget;
this.clock = clock ?? TimeProvider.System;
this.window = window ?? DefaultWindow;
ArgumentOutOfRangeException.ThrowIfLessThanOrEqual(this.window, TimeSpan.Zero, nameof(window));
this.maxKeys = maxKeys;
windowText = FormatWindow(this.window);
var every = sweepEvery ?? TimeSpan.FromSeconds(1);
if (every != Timeout.InfiniteTimeSpan)
{
timer = this.clock.CreateTimer(_ => SweepQuietly(), null, every, every);
}
}
/// <summary>How many distinct events are being tracked now.</summary>
public int Tracked
{
get
{
lock (gate)
{
return entries.Count;
}
}
}
public void Emit(LogEvent logEvent)
{
if (logEvent.Level < LogEventLevel.Warning)
{
target.Emit(logEvent);
return;
}
var key = KeyOf(logEvent);
LogEvent? evicted = null;
LogEvent? summary = null;
var write = true;
lock (gate)
{
if (!disposed)
{
var now = clock.GetUtcNow();
if (entries.TryGetValue(key, out var entry) && now - entry.Start >= window)
{
summary = Close(key, entry, now);
if (summary is null)
{
entry = null;
}
}
if (entry is null)
{
evicted = MakeRoom();
entries[key] = new Entry(now, ++order);
}
else
{
entry.Suppressed++;
entry.Last = logEvent;
write = false;
}
}
}
if (evicted is not null)
{
target.Emit(evicted);
}
if (summary is not null)
{
target.Emit(summary);
}
if (write)
{
target.Emit(logEvent);
}
}
/// <summary>Ends every window that is over: a summary line for each that counted repeats; the quiet ones are forgotten.</summary>
public void Sweep()
{
List<LogEvent>? summaries = null;
lock (gate)
{
if (disposed || entries.Count == 0)
{
return;
}
var now = clock.GetUtcNow();
foreach (var (key, entry) in entries.Where(e => now - e.Value.Start >= window).ToList())
{
if (Close(key, entry, now) is { } summary)
{
(summaries ??= []).Add(summary);
}
}
}
foreach (var summary in summaries ?? [])
{
target.Emit(summary);
}
}
/// <summary>Writes every count still open, then stops (events after this pass straight through).</summary>
public void Dispose()
{
List<LogEvent> summaries;
lock (gate)
{
if (disposed)
{
return;
}
disposed = true;
summaries = [.. entries.Values.Where(e => e.Suppressed > 0).OrderBy(e => e.Order).Select(Summary)];
entries.Clear();
}
timer?.Dispose();
foreach (var summary in summaries)
{
target.Emit(summary);
}
if (ownsTarget)
{
(target as IDisposable)?.Dispose();
}
}
/// <summary><c>60s</c>, <c>1.5s</c>, <c>250ms</c>.</summary>
public static string FormatWindow(TimeSpan window)
=> window.TotalSeconds >= 1
? window.TotalSeconds.ToString("0.###", CultureInfo.InvariantCulture) + "s"
: window.TotalMilliseconds.ToString("0", CultureInfo.InvariantCulture) + "ms";
private static Key KeyOf(LogEvent logEvent)
{
var template = logEvent.MessageTemplate;
var text = template.Tokens.Any(t => t is TextToken token && !string.IsNullOrWhiteSpace(token.Text))
? template.Text
: logEvent.RenderMessage(CultureInfo.InvariantCulture);
if (text.Length > RenderedKeyChars)
{
text = text[..RenderedKeyChars];
}
return new Key(logEvent.Level, LogLineFormatter.SourceContext(logEvent), text);
}
/// <summary>The window of <paramref name="entry"/> is over: its summary (and a new window), or nothing (and it is forgotten).</summary>
private LogEvent? Close(Key key, Entry entry, DateTimeOffset now)
{
if (entry.Suppressed == 0)
{
entries.Remove(key);
return null;
}
var summary = Summary(entry);
entry.Start = now;
entry.Suppressed = 0;
entry.Last = null;
return summary;
}
private LogEvent? MakeRoom()
{
if (entries.Count < maxKeys)
{
return null;
}
var oldest = entries.MinBy(e => e.Value.Order);
entries.Remove(oldest.Key);
return oldest.Value.Suppressed > 0 ? Summary(oldest.Value) : null;
}
private LogEvent Summary(Entry entry)
{
var last = entry.Last!;
var summary = new LogEvent(
clock.GetUtcNow(),
last.Level,
last.Exception,
last.MessageTemplate,
last.Properties.Select(p => new LogEventProperty(p.Key, p.Value)));
summary.AddOrUpdateProperty(new LogEventProperty(RepeatedProperty, new ScalarValue(entry.Suppressed)));
summary.AddOrUpdateProperty(new LogEventProperty(WindowProperty, new ScalarValue(windowText)));
return summary;
}
private void SweepQuietly()
{
try
{
Sweep();
}
catch (Exception exception)
{
// A sink that throws must never take the timer (or the process) down with it.
Serilog.Debugging.SelfLog.WriteLine("Repeat summary failed: {0}", exception);
}
}
private readonly record struct Key(LogEventLevel Level, string? Source, string Template);
private sealed class Entry(DateTimeOffset start, long order)
{
public DateTimeOffset Start { get; set; } = start;
public long Order { get; } = order;
public int Suppressed { get; set; }
public LogEvent? Last { get; set; }
}
}
+5 -2
View File
@@ -110,6 +110,7 @@ export interface SaveScriptBody {
runFromFile?: boolean;
cleanUpAfterRun?: boolean;
setWorkingDirectory?: boolean;
runAsUser?: boolean;
restartAfterRun?: RestartAfterRun;
restartDelaySeconds?: number;
restartWarningSeconds?: number;
@@ -298,8 +299,10 @@ export const api = {
devices: () => request<DeviceDto[]>('/api/devices'),
device: (clientId: string) => request<DeviceDetailDto>(`/api/devices/${enc(clientId)}`),
refreshInventory: (clientId: string) => request<void>(`/api/devices/${enc(clientId)}/inventory`, { method: 'POST' }),
openShell: (clientId: string, body: { browserSessionId: string; cols: number; rows: number; shell?: string }) =>
request<CreateShellResponse>(`/api/devices/${enc(clientId)}/shell`, json('POST', body)),
openShell: (
clientId: string,
body: { browserSessionId: string; cols: number; rows: number; shell?: string; asUser?: boolean; user?: string }
) => request<CreateShellResponse>(`/api/devices/${enc(clientId)}/shell`, json('POST', body)),
/** Remote View: a session and its first one-time socket ticket. */
openScreen: (clientId: string, body: { viewOnly: boolean; monitor?: number }) =>
request<CreateScreenResponse>(`/api/devices/${enc(clientId)}/screen`, json('POST', body)),
+7 -1
View File
@@ -53,7 +53,7 @@ export type AgentInstallKind = 'msi' | 'portable';
// ── Device grouping ───────────────────────────────────────────────────
/** Folders hold no devices of their own; every kind includes its nested groups' devices. */
export type GroupKind = 'static' | 'dynamic' | 'folder';
export type GroupKind = 'static' | 'dynamic' | 'folder' | 'script';
export type RuleCombine = 'and' | 'or';
export type RuleOperator =
| 'equals'
@@ -1198,6 +1198,8 @@ export interface ScriptDto {
cleanUpAfterRun?: boolean;
/** Start a file-run script in its job folder. */
setWorkingDirectory?: boolean;
/** Run as the device's signed-in user instead of the agent's account. */
runAsUser?: boolean;
restartAfterRun?: RestartAfterRun;
/** Seconds before the restart (0 to 3600). */
restartDelaySeconds?: number;
@@ -1763,6 +1765,10 @@ export interface ShellStatePayload {
message?: string;
/** The shell the agent started (a ShellKind; Windows agents, on open). */
shell?: string;
/** The account it runs as, when started as the signed-in user. */
user?: string;
/** Who is signed in on the device (on open, and when a run-as-user open failed). */
signedInUsers?: string[];
}
export interface DeviceFileRoot {
+29 -11
View File
@@ -40,12 +40,12 @@ interface Props {
}
const LEVELS: { level: LogLevel; tag: string; label: string; color: string; text: string }[] = [
{ level: 'verbose', tag: 'VRB', label: 'Verbose', color: 'text.disabled', text: 'text.secondary' },
{ level: 'debug', tag: 'DBG', label: 'Debug', color: 'text.disabled', text: 'text.secondary' },
{ level: 'information', tag: 'INF', label: 'Information', color: 'info.main', text: 'text.primary' },
{ level: 'warning', tag: 'WRN', label: 'Warning', color: 'warning.main', text: 'warning.dark' },
{ level: 'error', tag: 'ERR', label: 'Error', color: 'error.main', text: 'error.main' },
{ level: 'fatal', tag: 'FTL', label: 'Fatal', color: 'error.dark', text: 'error.dark' }
{ level: 'verbose', tag: 'TRACE', label: 'Verbose', color: 'text.disabled', text: 'text.secondary' },
{ level: 'debug', tag: 'DEBUG', label: 'Debug', color: 'text.disabled', text: 'text.secondary' },
{ level: 'information', tag: 'INFO', label: 'Information', color: 'info.main', text: 'text.primary' },
{ level: 'warning', tag: 'WARN', label: 'Warning', color: 'warning.main', text: 'warning.dark' },
{ level: 'error', tag: 'ERROR', label: 'Error', color: 'error.main', text: 'error.main' },
{ level: 'fatal', tag: 'FATAL', label: 'Fatal', color: 'error.dark', text: 'error.dark' }
];
const LEVEL = Object.fromEntries(LEVELS.map((l) => [l.level, l])) as Record<LogLevel, (typeof LEVELS)[number]>;
@@ -68,10 +68,28 @@ const sleep = (ms: number, signal: AbortSignal) =>
});
});
const lineText = (line: LogLineDto) =>
`${line.timestampUtc} ${LEVEL[line.level]?.tag ?? line.level} ${line.source ? `${line.source}: ` : ''}${line.message}${line.exception ? `\n${line.exception}` : ''}`;
/**
* The short component name a line shows, as the log files write it: the type name without its
* namespace or generic arguments, a nested type as Outer.Inner (Agent.Screen.ScreenHost+Session → ScreenHost.Session).
*/
function logCategory(source?: string | null): string {
const trimmed = source?.trim() ?? '';
if (!trimmed) return '';
const generic = trimmed.search(/[[<]/);
const parts = (generic > 0 ? trimmed.slice(0, generic) : trimmed).replace(/`\d+/g, '').split('+').filter(Boolean);
if (parts.length === 0) return trimmed;
parts[0] = parts[0].slice(parts[0].lastIndexOf('.') + 1);
return parts.filter(Boolean).join('.') || trimmed;
}
const shortSource = (source?: string) => (source ? source.slice(source.lastIndexOf('.') + 1) : '');
const isoTime = (value: string) => {
const date = new Date(value);
return Number.isNaN(date.getTime()) ? value : date.toISOString();
};
/** A line as the log files write it: [time] - [Category] - [LEVEL] - message. */
const lineText = (line: LogLineDto) =>
`[${isoTime(line.timestampUtc)}] - [${logCategory(line.source)}] - [${LEVEL[line.level]?.tag ?? line.level.toUpperCase()}] - ${line.message}${line.exception ? `\n${line.exception}` : ''}`;
// ==============================|| LOG VIEWER ||============================== //
@@ -341,12 +359,12 @@ function LogLine({ line }: { line: LogLineDto }) {
<Box component="span" sx={{ color: 'text.disabled', mr: 1.5 }}>
{formatLogTime(line.timestampUtc)}
</Box>
<Box component="span" sx={{ color: level.color, fontWeight: 600, mr: 1.5 }}>
<Box component="span" sx={{ color: level.color, fontWeight: 600, mr: 1.5, display: 'inline-block', minWidth: '5ch' }}>
{level.tag}
</Box>
{line.source && (
<Box component="span" sx={{ color: 'text.secondary', mr: 1 }}>
{shortSource(line.source)}:
{logCategory(line.source)}:
</Box>
)}
{line.message}
+4 -2
View File
@@ -80,7 +80,7 @@ const removalRow = (removal: DeviceRemovalDto): ListRow => ({
const listRowId = (row: ListRow) => (row.removal ? `removal:${row.removal.id}` : row.clientId);
const KIND_LABEL = { static: 'Static Group', dynamic: 'Dynamic Group', folder: 'Folder' } as const;
const KIND_LABEL = { static: 'Static Group', dynamic: 'Dynamic Group', folder: 'Folder', script: 'Script Group' } as const;
function matches(device: ListRow, query: string): boolean {
return [
@@ -739,7 +739,9 @@ export default function DevicesPage() {
? 'No device matches the rules right now.'
: selectedGroup?.kind === 'folder'
? 'Shows devices of nested groups.'
: undefined
: selectedGroup?.kind === 'script'
? 'Devices appear when their scripts report they belong.'
: undefined
}
/>
) : (
+9
View File
@@ -23,6 +23,7 @@ import useSession from 'hooks/useSession';
import DeviceToolFrame, { useToolSurface } from 'sections/deviceTools/DeviceToolFrame';
import { useIsPopOut } from 'sections/deviceTools/popOut';
import RemoteScreenView, { type RemoteScreenHandle, type ScreenScale, type ViewPhase } from 'sections/screen/RemoteScreenView';
import type { VideoInfo } from 'sections/screen/videoChannel';
import { screenGates } from 'sections/screen/screenGate';
import { api, errorMessage, isUnsupported, keys } from 'api/client';
import type { DeviceDetailDto, ScreenMonitor, ScreenSessionDto, ScreenTicketDto } from 'api/types';
@@ -92,6 +93,7 @@ function ScreenView({ clientId, viewOnly }: { clientId: string; viewOnly: boolea
const [reason, setReason] = useState<string>();
const [scale, setScale] = useState<ScreenScale>('fit');
const [desktop, setDesktop] = useState<{ width: number; height: number }>();
const [video, setVideo] = useState<VideoInfo | null>(null);
const [monitor, setMonitor] = useState(-1);
const [openError, setOpenError] = useState<unknown>();
const view = useRef<RemoteScreenHandle>(null);
@@ -262,6 +264,11 @@ function ScreenView({ clientId, viewOnly }: { clientId: string; viewOnly: boolea
!gate && (
<Stack direction="row" component="span" sx={{ gap: 1, alignItems: 'center' }}>
<StatusChip status={status.status} label={status.label} tooltip={reason} />
{video && (
<Tooltip title={`${video.hardware ? 'GPU' : 'Software'} encoder on the device: ${video.encoder}`}>
<Chip size="small" variant="light" color="success" label={video.hardware ? 'H.264 GPU' : 'H.264'} />
</Tooltip>
)}
{viewOnly && (
<Tooltip title="Keyboard and mouse are not sent to the device.">
<Chip size="small" variant="light" color="info" icon={<EyeOutlined />} label="View Only" />
@@ -362,6 +369,7 @@ function ScreenView({ clientId, viewOnly }: { clientId: string; viewOnly: boolea
<Box ref={frame} sx={{ bgcolor: '#000', ...(hug ? hugging(hug) : surface.body) }}>
{showing && (
<RemoteScreenView
clipboard={!viewOnly}
ref={view}
key={ticket.token}
ticket={ticket}
@@ -369,6 +377,7 @@ function ScreenView({ clientId, viewOnly }: { clientId: string; viewOnly: boolea
scale={scale}
onPhase={onPhase}
onDesktopSize={setDesktop}
onVideo={setVideo}
/>
)}
</Box>
+103 -8
View File
@@ -21,7 +21,9 @@ import useApi from 'hooks/useApi';
import useSession, { useGate } from 'hooks/useSession';
import DeviceToolFrame, { useToolSurface } from 'sections/deviceTools/DeviceToolFrame';
import { useIsPopOut } from 'sections/deviceTools/popOut';
import useRemoteShell, { SHELL_KINDS, shellLabel, ShellKind, ShellState, TERMINAL_THEME } from 'sections/shell/useRemoteShell';
import useRemoteShell, { SHELL_KINDS, shellLabel, ShellKind, ShellState } from 'sections/shell/useRemoteShell';
import TerminalSettings from 'sections/shell/TerminalSettings';
import { themeOf, useTerminalPrefs } from 'sections/shell/terminalPrefs';
import { keys } from 'api/client';
import type { DeviceDetailDto } from 'api/types';
@@ -77,6 +79,74 @@ function ShellPicker({ value, started, onChange }: { value: ShellKind; started?:
);
}
/** A Run As choice: the agent's account, the usual signed-in user, or one named user. */
const USER_PREFIX = 'user:';
/** Whose account the shell runs as; picking another opens a new session. */
function RunAsPicker({
asUser,
user,
started,
signedIn,
onChange
}: {
asUser: boolean;
user?: string;
started?: string;
signedIn?: string[];
onChange: (asUser: boolean, user?: string) => void;
}) {
// A chosen user stays listed even if the last report did not include them.
const names = [...new Set([...(signedIn ?? []), ...(user ? [user] : [])])];
return (
<TextField
select
size="small"
label="Run As"
value={!asUser ? 'agent' : user ? USER_PREFIX + user : 'user'}
onChange={(e) => {
const value = e.target.value;
if (value === 'agent') onChange(false);
else if (value === 'user') onChange(true);
else onChange(true, value.slice(USER_PREFIX.length));
}}
sx={{ minWidth: 190 }}
slotProps={{
select: {
// Signed-In User shows who once the session is open.
renderValue: (value) =>
value === 'agent'
? 'Agent Account'
: value === 'user'
? (started ?? 'Signed-In User')
: (value as string).slice(USER_PREFIX.length)
}
}}
>
<MenuItem value="agent">
<Tooltip title="LocalSystem on Windows, root on Linux and macOS." placement="right">
<span style={{ flex: 1 }}>Agent Account</span>
</Tooltip>
</MenuItem>
<MenuItem value="user">
<Tooltip
title="The person signed in on the device: the console's user, else the only one signed in; the names below pick one. Needs agent 1.13.0 or later."
placement="right"
>
<span style={{ flex: 1 }}>Signed-In User</span>
</Tooltip>
</MenuItem>
{names.map((name) => (
<MenuItem key={name} value={USER_PREFIX + name} sx={{ pl: 4 }}>
<Tooltip title={`Signed in on the device. Opens as ${name}.`} placement="right">
<span style={{ flex: 1 }}>{name}</span>
</Tooltip>
</MenuItem>
))}
</TextField>
);
}
function ShellView({ clientId }: { clientId: string }) {
const { can } = useSession();
const popout = useIsPopOut();
@@ -84,8 +154,24 @@ function ShellView({ clientId }: { clientId: string }) {
const gate = useGate('shell.use', 'Remote Shell');
const allowed = !gate;
const { data: detail } = useApi<DeviceDetailDto>(can('devices.view') ? keys.device(clientId) : null);
const { hostRef, state, message, poppedOut, shell, startedShell, controller, close, reconnect, focusWindow, chooseShell } =
useRemoteShell(clientId, allowed);
const {
hostRef,
state,
message,
poppedOut,
shell,
startedShell,
asUser,
user,
startedUser,
signedInUsers,
controller,
close,
reconnect,
focusWindow,
chooseShell,
chooseRunAs
} = useRemoteShell(clientId, allowed);
// The shell choice applies to Windows devices only (unix agents start the login shell).
const windows = platformOf(detail?.device.osCaption) === 'windows';
@@ -96,6 +182,7 @@ function ShellView({ clientId }: { clientId: string }) {
const active = ACTIVE.includes(state);
const status = STATUS[state];
const { theme } = themeOf(useTerminalPrefs());
// Bringing it back from this page never needs to navigate.
const bringBack = () => controller?.dock(() => {});
@@ -113,6 +200,10 @@ function ShellView({ clientId }: { clientId: string }) {
allowed && (
<>
{windows && controller && <ShellPicker value={shell} started={startedShell} onChange={chooseShell} />}
{controller && (
<RunAsPicker asUser={asUser} user={user} started={startedUser} signedIn={signedInUsers} onChange={chooseRunAs} />
)}
<TerminalSettings />
{poppedOut && !popout && (
<Button variant="outlined" color="secondary" startIcon={<ImportOutlined />} onClick={bringBack}>
Bring Back
@@ -143,7 +234,7 @@ function ShellView({ clientId }: { clientId: string }) {
{(state === 'failed' || state === 'noResponse') && message && (
<Alert severity={state === 'failed' ? 'error' : 'warning'}>{message}</Alert>
)}
<MainCard content={false} sx={{ bgcolor: TERMINAL_THEME.background, overflow: 'hidden', ...surface.card }}>
<MainCard content={false} sx={{ bgcolor: theme.background, overflow: 'hidden', ...surface.card }}>
<Box sx={{ position: 'relative', p: 1.5, ...surface.body }}>
{/* xterm sizes itself to this element (the padding lives on the parent so fitting stays exact).
It stays mounted while popped out so closing the window can dock the terminal straight back. */}
@@ -152,13 +243,13 @@ function ShellView({ clientId }: { clientId: string }) {
<Stack
sx={{ position: 'absolute', inset: 0, alignItems: 'center', justifyContent: 'center', gap: 2, p: 3, textAlign: 'center' }}
>
<ExportOutlined style={{ fontSize: '2rem', color: TERMINAL_THEME.cursor }} />
<ExportOutlined style={{ fontSize: '2rem', color: theme.cursor }} />
<Stack
direction="row"
sx={{
alignItems: 'center',
color: TERMINAL_THEME.foreground,
'& [tabindex]': { color: TERMINAL_THEME.foreground, opacity: 0.7 }
color: theme.foreground,
'& [tabindex]': { color: theme.foreground, opacity: 0.7 }
}}
>
<Typography variant="h5">This Shell Is In Its Own Window</Typography>
@@ -168,7 +259,11 @@ function ShellView({ clientId }: { clientId: string }) {
<Button variant="contained" startIcon={<ImportOutlined />} onClick={bringBack}>
Bring Back
</Button>
<Button variant="outlined" onClick={focusWindow} sx={{ color: TERMINAL_THEME.foreground, borderColor: '#2a3b5c' }}>
<Button
variant="outlined"
onClick={focusWindow}
sx={{ color: theme.foreground, borderColor: theme.selectionBackground }}
>
Show Window
</Button>
</Stack>
+20 -5
View File
@@ -41,7 +41,7 @@ import MoreOutlined from '@ant-design/icons/MoreOutlined';
import PlayCircleOutlined from '@ant-design/icons/PlayCircleOutlined';
import PlusOutlined from '@ant-design/icons/PlusOutlined';
const KIND_LABEL = { static: 'Static', dynamic: 'Dynamic', folder: 'Folder' } as const;
const KIND_LABEL = { static: 'Static', dynamic: 'Dynamic', folder: 'Folder', script: 'Script' } as const;
// ==============================|| GROUPS ||============================== //
@@ -295,9 +295,18 @@ export default function GroupsPage() {
)}
</Stack>
)}
{group.kind === 'static' && (
{(group.kind === 'static' || group.kind === 'script') && (
<Stack sx={{ gap: 1 }}>
<Typography variant="subtitle1">Listed Devices</Typography>
<Typography variant="subtitle1">
{group.kind === 'script' ? 'Reported Devices' : 'Listed Devices'}
{group.kind === 'script' && (
<HoverHelp
title={
"Scripts add a device with Set-ExecuteRGroupMembership '<name>' <result> (true, above 0, or any results piped in), or executer_group in Bash; each run decides again."
}
/>
)}
</Typography>
<Stack direction="row" sx={{ gap: 0.75, flexWrap: 'wrap' }}>
{members
.filter((d) => d.groupIds?.includes(group.id))
@@ -316,8 +325,14 @@ export default function GroupsPage() {
{group.directMemberCount > 24 && <Chip size="small" label={`+${group.directMemberCount - 24} more`} />}
{group.directMemberCount === 0 && (
<Typography variant="body2" color="text.secondary">
None listed.
<HoverHelp title="Use Edit, or Add to Group on the Devices page." />
{group.kind === 'script' ? 'None reported.' : 'None listed.'}
<HoverHelp
title={
group.kind === 'script'
? "Scripts add a device with Set-ExecuteRGroupMembership '<name>' <result> (true, above 0, or any results piped in), or executer_group in Bash; each run decides again."
: 'Use Edit, or Add to Group on the Devices page.'
}
/>
</Typography>
)}
</Stack>
+36 -11
View File
@@ -22,6 +22,7 @@ import { useGate } from 'hooks/useSession';
// assets
import DownloadOutlined from '@ant-design/icons/DownloadOutlined';
import PlayCircleOutlined from '@ant-design/icons/PlayCircleOutlined';
import ReloadOutlined from '@ant-design/icons/ReloadOutlined';
// types
import type { ExecutionDetailDto } from 'api/types';
@@ -62,16 +63,16 @@ export default function RunPage() {
{ replace: !jobId }
);
// The same script on the same devices (skipped ones included: they may be back).
const runAgain = () =>
// The same script on these devices (every target, skipped ones included: they may be back).
const runAgainOn = (clientIds: string[]) =>
run &&
openRun({
scriptId: run.scriptId,
targets: [...run.targets.map((t) => t.clientId), ...(run.skipped ?? []).map((s) => s.clientId)].map((id) => ({
kind: 'device' as const,
id
}))
targets: [...new Set(clientIds)].map((id) => ({ kind: 'device' as const, id }))
});
const runAgain = () => run && runAgainOn([...run.targets.map((t) => t.clientId), ...(run.skipped ?? []).map((s) => s.clientId)]);
// Failed and timed out: the ones that ran and did not succeed.
const failedTargets = (run?.targets ?? []).filter((t) => t.state === 'failed' || t.state === 'timedOut').map((t) => t.clientId);
return (
<Stack sx={{ gap: 3 }}>
@@ -108,11 +109,34 @@ export default function RunPage() {
)
}
secondaryActions={
<Tooltip title="Every target's output in one .log file.">
<Button variant="outlined" color="secondary" startIcon={<DownloadOutlined />} href={downloads.executionOutput(runId)} download>
Download Output
</Button>
</Tooltip>
<>
<Tooltip title="Every target's output in one .log file.">
<Button
variant="outlined"
color="secondary"
startIcon={<DownloadOutlined />}
href={downloads.executionOutput(runId)}
download
>
Download Output
</Button>
</Tooltip>
{failedTargets.length > 0 && (
<Tooltip title={runGate ? '' : 'The same script again on the devices that failed or timed out.'}>
<span>
<GatedButton
variant="outlined"
color="error"
startIcon={<ReloadOutlined />}
gate={runGate}
onClick={() => runAgainOn(failedTargets)}
>
{`Run Again on ${failedTargets.length} Failed`}
</GatedButton>
</span>
</Tooltip>
)}
</>
}
primaryAction={
<GatedButton variant="contained" startIcon={<PlayCircleOutlined />} gate={runGate} disabled={!run} onClick={runAgain}>
@@ -131,6 +155,7 @@ export default function RunPage() {
refreshing={execution.validating && !execution.loading}
openJobId={openJobId}
onOpenJob={setJob}
onRunAgain={runGate ? undefined : runAgainOn}
/>
)}
+13 -4
View File
@@ -117,7 +117,7 @@ function OptionSwitch(props: { label: string; help: string; checked: boolean; di
/** How the script runs on the device: from a staged file, cleanup and working directory. */
function RunOptions({ draft, edit, readOnly }: { draft: ScriptDraft; edit: (patch: Partial<ScriptDraft>) => void; readOnly: boolean }) {
const pwsh7 = draft.engine === 'PowerShell';
const staged = stagesFile(draft.engine, draft.runFromFile);
const staged = stagesFile(draft.engine, draft.runFromFile, draft.runAsUser);
return (
<Stack direction="row" sx={{ flexWrap: 'wrap', rowGap: 0.5 }}>
<OptionSwitch
@@ -127,17 +127,26 @@ function RunOptions({ draft, edit, readOnly }: { draft: ScriptDraft; edit: (patc
? 'Saves the script in its job folder and runs it by path, so $PSScriptRoot is set.'
: 'PowerShell 5 and Bash always run from a file.'
}
checked={staged}
checked={stagesFile(draft.engine, draft.runFromFile)}
disabled={readOnly || !pwsh7}
onChange={(runFromFile) => edit(runFromFile ? { runFromFile } : { runFromFile, setWorkingDirectory: false })}
onChange={(runFromFile) => edit(runFromFile || draft.runAsUser ? { runFromFile } : { runFromFile, setWorkingDirectory: false })}
/>
<OptionSwitch
label="Set Working Directory to Script Folder"
help={staged ? 'Starts the script in its job folder.' : 'Needs Run From File.'}
help={staged ? 'Starts the script in its job folder.' : 'Needs Run From File or Run As Signed-In User.'}
checked={staged && draft.setWorkingDirectory}
disabled={readOnly || !staged}
onChange={(setWorkingDirectory) => edit({ setWorkingDirectory })}
/>
<OptionSwitch
label="Run As Signed-In User"
help="Runs as the person signed in on the device (the console's user, else the only one) instead of the agent's account, out of sight. Fails when nobody is signed in, or on agents before 1.13.0."
checked={draft.runAsUser}
disabled={readOnly}
onChange={(runAsUser) =>
edit(runAsUser || stagesFile(draft.engine, draft.runFromFile) ? { runAsUser } : { runAsUser, setWorkingDirectory: false })
}
/>
<OptionSwitch
label="Clean Up After Run"
help="Deletes the job folder when the run ends. Off keeps it for 7 days; secrets never stay."
+1 -1
View File
@@ -49,7 +49,7 @@ const TABS: { id: string; label: string; icon: ReactElement; Section: ComponentT
{ id: 'secrets', label: 'Secrets Providers', icon: <SafetyCertificateOutlined />, Section: SecretsProviders, permission: 'secrets.use' },
{
id: 'storage',
label: 'Storage & Agent Package',
label: 'Storage & Agent Packages',
icon: <CloudServerOutlined />,
Section: StorageSettings,
permission: 'settings.manage'
@@ -359,7 +359,7 @@ function AddDeviceContent({ open, onClose }: Props) {
<Step
n={3}
title="Install"
help={`The agent downloads from this server, installs as a ${SERVICE_KIND[platform]} and enrolls automatically.`}
help={`The agent downloads from this server, installs as a ${SERVICE_KIND[platform]} and enrolls automatically. Safe to run again: it leaves a healthy agent alone, upgrades an older one and repairs a broken one, keeping its enrollment.`}
/>
{error && (
<Alert severity="error" sx={{ mb: 1.5 }}>
+115 -2
View File
@@ -30,6 +30,7 @@ import useApi from 'hooks/useApi';
import useSession, { useGate } from 'hooks/useSession';
import { api, errorMessage, keys, request } from 'api/client';
import type { DeviceDto, DeviceFileEntry, DeviceFileReply, DeviceFileRoot } from 'api/types';
import { copyText } from 'utils/clipboard';
import { formatAbsolute, formatBytes, plural } from 'utils/format';
import SendFromS3Dialog from './SendFromS3Dialog';
import TextFileDialog from './TextFileDialog';
@@ -39,6 +40,7 @@ import UploadsCard, { UploadConflictDialog } from 'sections/uploads/UploadsCard'
// assets
import CloudDownloadOutlined from '@ant-design/icons/CloudDownloadOutlined';
import CopyOutlined from '@ant-design/icons/CopyOutlined';
import CloudServerOutlined from '@ant-design/icons/CloudServerOutlined';
import CloudUploadOutlined from '@ant-design/icons/CloudUploadOutlined';
import DeleteOutlined from '@ant-design/icons/DeleteOutlined';
@@ -90,7 +92,11 @@ export default function DeviceFiles({ device }: { device: DeviceDto }) {
const [take, setTake] = useState(PAGE);
const [chosen, setChosen] = useState<ReadonlySet<string>>(new Set());
const [address, setAddress] = useState<string | null>(null);
const [menu, setMenu] = useState<{ anchor: HTMLElement; entries: DeviceFileEntry[] } | null>(null);
// A row's "…" or Actions button anchors the menu; a right-click opens it where the pointer is.
const [menu, setMenu] = useState<{ anchor?: HTMLElement; position?: { top: number; left: number }; entries: DeviceFileEntry[] } | null>(
null
);
const [folderMenu, setFolderMenu] = useState<{ top: number; left: number } | null>(null);
const [uploadMenu, setUploadMenu] = useState<HTMLElement | null>(null);
const [nameDialog, setNameDialog] = useState<NameDialog | null>(null);
const [nameValue, setNameValue] = useState('');
@@ -285,6 +291,23 @@ export default function DeviceFiles({ device }: { device: DeviceDto }) {
});
}
items.push({ kind: 'divider' });
items.push({
kind: 'item',
id: 'copy-path',
label: one ? 'Copy Path' : 'Copy Paths',
icon: <CopyOutlined />,
onSelect: close(() => void copyText(targets.map((t) => t.path).join('\n'), one ? 'Path' : 'Paths'))
});
if (one) {
items.push({
kind: 'item',
id: 'copy-name',
label: 'Copy Name',
icon: <CopyOutlined />,
onSelect: close(() => void copyText(one.name, 'Name'))
});
}
items.push({ kind: 'divider' });
items.push({
kind: 'item',
id: 'delete',
@@ -300,6 +323,67 @@ export default function DeviceFiles({ device }: { device: DeviceDto }) {
return items;
};
/** Right-click on the folder itself (not on a row). */
const folderEntries = (): MenuEntry[] => {
const close = (action: () => void) => () => {
setFolderMenu(null);
action();
};
const items: MenuEntry[] = [];
if (path)
items.push({
kind: 'item',
id: 'copy-folder',
label: 'Copy Folder Path',
icon: <CopyOutlined />,
onSelect: close(() => void copyText(path, 'Folder Path'))
});
items.push(
{ kind: 'divider' },
{
kind: 'item',
id: 'new-file',
label: 'New File…',
icon: <FileAddOutlined />,
disabledReason: manageGate,
onSelect: close(() => {
setNameValue('');
setNameDialog({ kind: 'file' });
})
},
{
kind: 'item',
id: 'new-folder',
label: 'New Folder…',
icon: <FolderAddOutlined />,
disabledReason: manageGate,
onSelect: close(() => {
setNameValue('');
setNameDialog({ kind: 'folder' });
})
},
{
kind: 'item',
id: 'upload-files',
label: 'Upload Files…',
icon: <UploadOutlined />,
disabledReason: manageGate,
onSelect: close(() => fileInput.current?.click())
},
{
kind: 'item',
id: 'upload-folder',
label: 'Upload Folder…',
icon: <FolderOutlined />,
disabledReason: manageGate,
onSelect: close(() => folderInput.current?.click())
},
{ kind: 'divider' },
{ kind: 'item', id: 'refresh', label: 'Refresh', icon: <ReloadOutlined />, onSelect: close(() => void reload()) }
);
return items;
};
const submitName = async () => {
if (!nameDialog || !path) return;
const name = nameValue.trim();
@@ -612,6 +696,18 @@ export default function DeviceFiles({ device }: { device: DeviceDto }) {
<EditOutlined />
</IconButton>
</Tooltip>
{path && (
<Tooltip title="Copy Folder Path">
<IconButton
size="small"
color="secondary"
aria-label="Copy folder path"
onClick={() => void copyText(path, 'Folder Path')}
>
<CopyOutlined />
</IconButton>
</Tooltip>
)}
<Tooltip title="Refresh">
<IconButton size="small" color="secondary" aria-label="Refresh" onClick={() => void reload()}>
<ReloadOutlined />
@@ -631,6 +727,12 @@ export default function DeviceFiles({ device }: { device: DeviceDto }) {
if (!e.currentTarget.contains(e.relatedTarget as Node)) setDragging(false);
}}
onDrop={onDrop}
onContextMenu={(e) => {
// A row's own right-click already opened its menu.
if (e.defaultPrevented || (e.target as HTMLElement).closest('input, textarea')) return;
e.preventDefault();
setFolderMenu({ top: e.clientY, left: e.clientX });
}}
sx={{ outline: dragging ? '2px dashed' : 'none', outlineColor: 'primary.main', outlineOffset: -4 }}
>
<DataTable
@@ -644,6 +746,9 @@ export default function DeviceFiles({ device }: { device: DeviceDto }) {
paged={false}
dense
onRowClick={open}
onRowContextMenu={(row, position) =>
setMenu({ position, entries: chosen.has(row.path) && chosenEntries.length > 1 ? chosenEntries : [row] })
}
rowLabel={(e) => `Choose ${e.name}`}
selection={{
selected: chosen,
@@ -725,7 +830,15 @@ export default function DeviceFiles({ device }: { device: DeviceDto }) {
/>
)}
{menu && <ActionMenu anchorEl={menu.anchor} onClose={() => setMenu(null)} entries={menuEntries(menu.entries)} />}
{menu && (
<ActionMenu
anchorEl={menu.anchor}
anchorPosition={menu.position}
onClose={() => setMenu(null)}
entries={menuEntries(menu.entries)}
/>
)}
{folderMenu && <ActionMenu anchorPosition={folderMenu} onClose={() => setFolderMenu(null)} entries={folderEntries()} />}
<ConfirmDialog
open={!!nameDialog}
@@ -29,6 +29,7 @@ import TreeList, { type TreeMenuAnchor, type TreeNode } from 'components/TreeLis
import { useGate } from 'hooks/useSession';
import { api, downloads, errorMessage, isUnsupported, keys, request } from 'api/client';
import type { DeviceDto, RegistryKeyEntry, RegistryReply, RegistryValue, RegistryView } from 'api/types';
import { copyText } from 'utils/clipboard';
import { formatAbsolute } from 'utils/format';
import RegistryImportDialog from './RegistryImportDialog';
import RegistryValueDialog from './RegistryValueDialog';
@@ -52,6 +53,7 @@ import {
} from './registryModel';
// assets
import CopyOutlined from '@ant-design/icons/CopyOutlined';
import DeleteOutlined from '@ant-design/icons/DeleteOutlined';
import EditOutlined from '@ant-design/icons/EditOutlined';
import ExportOutlined from '@ant-design/icons/ExportOutlined';
@@ -260,6 +262,23 @@ export default function DeviceRegistry({ device }: { device: DeviceDto }) {
downloads.registryExport(clientId, keyPath, view).catch((e) => setNotice(errorMessage(e, 'The export failed.')));
};
/** The value's data as text: strings as they are, multi-strings one per line, numbers as shown, binary as hex. */
const copyValueData = async (value: RegistryValue) => {
let whole = value;
if (value.truncated) {
try {
whole = (await api.registryValue(clientId, current, view, value.name)).value ?? value;
} catch (e) {
setNotice(errorMessage(e, 'The value could not be read.'));
return;
}
}
const text = whole.lines
? whole.lines.join('\n')
: (whole.text ?? displayData({ ...whole, truncated: false }, Number.MAX_SAFE_INTEGER));
await copyText(text, 'Data');
};
const openValue = async (value: RegistryValue) => {
setNotice('');
let whole = value;
@@ -303,6 +322,21 @@ export default function DeviceRegistry({ device }: { device: DeviceDto }) {
},
{ kind: 'item', id: 'export', label: 'Export…', icon: <ExportOutlined />, onSelect: () => exportKey(target.path) },
{ kind: 'divider' },
{
kind: 'item',
id: 'copy-path',
label: 'Copy Key Path',
icon: <CopyOutlined />,
onSelect: () => void copyText(target.path, 'Key Path')
},
{
kind: 'item',
id: 'copy-name',
label: 'Copy Key Name',
icon: <CopyOutlined />,
onSelect: () => void copyText(nameOf(target.path), 'Key Name')
},
{ kind: 'divider' },
{
kind: 'item',
id: 'delete',
@@ -339,6 +373,23 @@ export default function DeviceRegistry({ device }: { device: DeviceDto }) {
}
},
{ kind: 'divider' },
{
kind: 'item',
id: 'copy-name',
label: 'Copy Name',
icon: <CopyOutlined />,
disabledReason: value.name === '' ? 'The default value has no name.' : undefined,
onSelect: () => void copyText(value.name, 'Name')
},
{ kind: 'item', id: 'copy-data', label: 'Copy Data', icon: <CopyOutlined />, onSelect: () => void copyValueData(value) },
{
kind: 'item',
id: 'copy-path',
label: 'Copy Value Path',
icon: <CopyOutlined />,
onSelect: () => void copyText(`${current}\\${value.name || '(Default)'}`, 'Value Path')
},
{ kind: 'divider' },
{
kind: 'item',
id: 'delete',
@@ -613,6 +664,11 @@ export default function DeviceRegistry({ device }: { device: DeviceDto }) {
<EditOutlined />
</IconButton>
</Tooltip>
<Tooltip title="Copy Key Path">
<IconButton size="small" color="secondary" aria-label="Copy key path" onClick={() => void copyText(current, 'Key Path')}>
<CopyOutlined />
</IconButton>
</Tooltip>
<Tooltip title="Refresh">
<IconButton
size="small"
+21 -3
View File
@@ -48,7 +48,9 @@ interface Props {
const KIND_HELP: Record<GroupKind, string> = {
dynamic: 'Members are the devices matching the rules, re-evaluated as inventory, tags and status change.',
static: 'Members are the devices you list.',
folder: 'Holds no devices of its own; organizes groups nested under it.'
folder: 'Holds no devices of its own; organizes groups nested under it.',
script:
"Members are the devices whose scripts report they belong. Scripts add a device with Set-ExecuteRGroupMembership '<name>' <result> (true, above 0, or any results piped in), or executer_group in Bash; each run decides again."
};
const EMPTY_RULES: GroupRuleSet = { combine: 'and', groups: [] };
@@ -155,7 +157,10 @@ export default function GroupEditor({ open, onClose, group, preset, onSaved }: P
[groups, group]
);
const droppingMembers = group?.kind === 'static' && kind !== 'static' && initialMembers.length > 0;
// Static and script groups keep rows; saving as a kind without them drops them.
const keepsRows = (k: GroupKind) => k === 'static' || k === 'script';
const droppedCount = group?.kind === 'static' ? initialMembers.length : (group?.directMemberCount ?? 0);
const droppingMembers = Boolean(group) && keepsRows(group!.kind) && !keepsRows(kind) && droppedCount > 0;
const deviceById = useMemo(() => new Map((devices ?? []).map((d) => [d.clientId, d])), [devices]);
const save = async () => {
@@ -242,11 +247,13 @@ export default function GroupEditor({ open, onClose, group, preset, onSaved }: P
<ToggleButtonGroup exclusive size="small" value={kind} onChange={(_, value) => value && setKind(value)}>
<ToggleButton value="dynamic">Dynamic (Rules)</ToggleButton>
<ToggleButton value="static">Static (Listed)</ToggleButton>
<ToggleButton value="script">Script (Reported)</ToggleButton>
<ToggleButton value="folder">Folder</ToggleButton>
</ToggleButtonGroup>
{droppingMembers && (
<Alert severity="warning">
Saving as {kind === 'folder' ? 'a folder' : 'a dynamic group'} drops the {plural(initialMembers.length, 'listed device')}.
Saving as {kind === 'folder' ? 'a folder' : 'a dynamic group'} drops the{' '}
{plural(droppedCount, group?.kind === 'script' ? 'reported device' : 'listed device')}.
</Alert>
)}
</Stack>
@@ -340,6 +347,17 @@ export default function GroupEditor({ open, onClose, group, preset, onSaved }: P
</Stack>
)}
{kind === 'script' && (
<Typography variant="body2" color="text.secondary">
Scripts add and remove its devices.
<HoverHelp
title={
"Scripts add a device with Set-ExecuteRGroupMembership '<name>' <result> (true, above 0, or any results piped in), or executer_group in Bash; each run decides again."
}
/>
</Typography>
)}
{kind === 'folder' && (
<Typography variant="body2" color="text.secondary">
Add groups to it after saving.
@@ -19,6 +19,7 @@ import ApartmentOutlined from '@ant-design/icons/ApartmentOutlined';
import ClusterOutlined from '@ant-design/icons/ClusterOutlined';
import DisconnectOutlined from '@ant-design/icons/DisconnectOutlined';
import FilterOutlined from '@ant-design/icons/FilterOutlined';
import CodeOutlined from '@ant-design/icons/CodeOutlined';
import FolderOutlined from '@ant-design/icons/FolderOutlined';
import NodeCollapseOutlined from '@ant-design/icons/NodeCollapseOutlined';
import NodeExpandOutlined from '@ant-design/icons/NodeExpandOutlined';
@@ -30,7 +31,7 @@ export const UNGROUPED_NODE = 'ungrouped';
const EXPANDED_KEY = 'executer-group-tree-expanded';
const KIND_ICON = { folder: FolderOutlined, dynamic: FilterOutlined, static: ApartmentOutlined } as const;
const KIND_ICON = { folder: FolderOutlined, dynamic: FilterOutlined, static: ApartmentOutlined, script: CodeOutlined } as const;
function loadExpanded(): Set<string> {
try {
+132 -55
View File
@@ -8,8 +8,11 @@ import Button from '@mui/material/Button';
import ButtonBase from '@mui/material/ButtonBase';
import Chip from '@mui/material/Chip';
import CircularProgress from '@mui/material/CircularProgress';
import IconButton from '@mui/material/IconButton';
import InputAdornment from '@mui/material/InputAdornment';
import Link from '@mui/material/Link';
import Menu from '@mui/material/Menu';
import MenuItem from '@mui/material/MenuItem';
import Stack from '@mui/material/Stack';
import TextField from '@mui/material/TextField';
import Tooltip from '@mui/material/Tooltip';
@@ -33,6 +36,8 @@ import { BAR_ORDER, PENDING, RunFilter, runCounts, runFinished, Segment, segment
// assets
import DownloadOutlined from '@ant-design/icons/DownloadOutlined';
import EllipsisOutlined from '@ant-design/icons/EllipsisOutlined';
import PlayCircleOutlined from '@ant-design/icons/PlayCircleOutlined';
import SearchOutlined from '@ant-design/icons/SearchOutlined';
// types
@@ -129,7 +134,8 @@ function Counter({
help,
tone,
active,
onClick
onClick,
onRunAgain
}: {
label: string;
value: number;
@@ -137,40 +143,86 @@ function Counter({
tone?: SegmentTone;
active: boolean;
onClick: () => void;
/** Run Again on the tile's devices (right-click, or the ⋯ on hover). */
onRunAgain?: () => void;
}) {
const [menu, setMenu] = useState<{ top: number; left: number } | null>(null);
const actionable = Boolean(onRunAgain) && value > 0;
const openMenu = (event: MouseEvent<HTMLElement>, at?: { top: number; left: number }) => {
event.preventDefault();
event.stopPropagation();
const box = event.currentTarget.getBoundingClientRect();
setMenu(at ?? { top: box.bottom, left: box.left });
};
return (
<Tooltip title={help} enterDelay={500} disableInteractive>
<ButtonBase
onClick={onClick}
aria-pressed={active}
sx={(theme) => {
const color = tone ? theme.palette[tone].main : theme.palette.text.primary;
return {
flex: '1 1 96px',
minWidth: 96,
px: 1.75,
py: 1.25,
gap: 0.25,
flexDirection: 'column',
alignItems: 'flex-start',
borderRadius: 1.5,
border: '1px solid',
borderColor: active ? color : 'divider',
bgcolor: active ? alpha(color, 0.08) : 'transparent',
transition: 'border-color 120ms, background-color 120ms',
'&:hover': { borderColor: color, bgcolor: alpha(color, 0.05) },
'&.Mui-focusVisible': { outline: `2px solid ${theme.palette.primary.main}`, outlineOffset: 1 }
};
}}
>
<Typography variant="h4" sx={{ lineHeight: 1.1, color: tone && value ? `${tone}.main` : 'text.primary' }}>
{value.toLocaleString()}
</Typography>
<Typography variant="caption" color="text.secondary" sx={{ fontWeight: 500 }}>
{label}
</Typography>
</ButtonBase>
</Tooltip>
<Box
sx={{
position: 'relative',
flex: '1 1 96px',
minWidth: 96,
display: 'flex',
'&:hover .counter-more, & .counter-more.Mui-focusVisible': { opacity: 1 }
}}
>
<Tooltip title={help} enterDelay={500} disableInteractive>
<ButtonBase
onClick={onClick}
onContextMenu={actionable ? (e) => openMenu(e, { top: e.clientY, left: e.clientX }) : undefined}
aria-pressed={active}
sx={(theme) => {
const color = tone ? theme.palette[tone].main : theme.palette.text.primary;
return {
flex: 1,
px: 1.75,
py: 1.25,
gap: 0.25,
flexDirection: 'column',
alignItems: 'flex-start',
borderRadius: 1.5,
border: '1px solid',
borderColor: active ? color : 'divider',
bgcolor: active ? alpha(color, 0.08) : 'transparent',
transition: 'border-color 120ms, background-color 120ms',
'&:hover': { borderColor: color, bgcolor: alpha(color, 0.05) },
'&.Mui-focusVisible': { outline: `2px solid ${theme.palette.primary.main}`, outlineOffset: 1 }
};
}}
>
<Typography variant="h4" sx={{ lineHeight: 1.1, color: tone && value ? `${tone}.main` : 'text.primary' }}>
{value.toLocaleString()}
</Typography>
<Typography variant="caption" color="text.secondary" sx={{ fontWeight: 500 }}>
{label}
</Typography>
</ButtonBase>
</Tooltip>
{actionable && (
<>
<Tooltip title={`${label} Actions`}>
<IconButton
className="counter-more"
size="small"
aria-label={`${label} Actions`}
onClick={(e) => openMenu(e)}
sx={{ position: 'absolute', top: 4, right: 4, opacity: { xs: 1, md: 0 }, transition: 'opacity 120ms' }}
>
<EllipsisOutlined />
</IconButton>
</Tooltip>
<Menu open={Boolean(menu)} onClose={() => setMenu(null)} anchorReference="anchorPosition" anchorPosition={menu ?? undefined}>
<MenuItem
onClick={() => {
setMenu(null);
onRunAgain?.();
}}
>
<PlayCircleOutlined style={{ marginRight: 8 }} />
{value === 1 ? 'Run Again on This Device' : `Run Again on These ${value.toLocaleString()}`}
</MenuItem>
</Menu>
</>
)}
</Box>
);
}
@@ -178,11 +230,14 @@ function Counter({
export function RunCounters({
counts,
filter,
onFilter
onFilter,
onRunAgain
}: {
counts: RunCountsDto;
filter: RunFilter;
onFilter: (filter: RunFilter) => void;
/** Run Again on a tile's devices; without it the tiles have no actions. */
onRunAgain?: (filter: RunFilter) => void;
}) {
const toggle = (next: RunFilter) => onFilter(filter === next ? 'all' : next);
return (
@@ -193,6 +248,7 @@ export function RunCounters({
help="Every device this run reached."
active={filter === 'all'}
onClick={() => onFilter('all')}
onRunAgain={onRunAgain && (() => onRunAgain('all'))}
/>
<Counter
label="Online"
@@ -200,6 +256,7 @@ export function RunCounters({
help="Targets online now."
active={filter === 'online'}
onClick={() => toggle('online')}
onRunAgain={onRunAgain && (() => onRunAgain('online'))}
/>
{SEGMENTS.map((s) => (
<Counter
@@ -210,6 +267,7 @@ export function RunCounters({
tone={s.tone}
active={filter === s.key}
onClick={() => toggle(s.key)}
onRunAgain={onRunAgain && (() => onRunAgain(s.key))}
/>
))}
</Stack>
@@ -382,6 +440,8 @@ interface Props {
initialFilter?: RunFilter;
/** Shows the charts above the table (a page of its own), not only the counters in its toolbar. */
dashboard?: boolean;
/** The same script again on some of these devices (a status tile's, or the checked ones). */
onRunAgain?: (clientIds: string[]) => void;
}
/**
@@ -399,7 +459,8 @@ export default function RunProgress({
onOpenJob,
toolbarStart,
initialFilter = 'all',
dashboard
dashboard,
onRunAgain
}: Props) {
const [filter, setFilterState] = useState<RunFilter>(initialFilter);
const [detail, setDetail] = useState<RunDetailFilter | null>(null);
@@ -482,6 +543,13 @@ export default function RunProgress({
);
}, [rows, filter, detail, search]);
// A tile's devices (skipped ones included: they may be back), or the checked rows'.
const devicesOf = (rule: RunFilter) => [
...new Set((rows ?? []).filter((r) => rule === 'all' || (rule === 'online' ? r.online : segmentOf(r) === rule)).map((r) => r.clientId))
];
const runAgainOn = onRunAgain && ((rule: RunFilter) => onRunAgain(devicesOf(rule)));
const checkedDevices = [...new Set((rows ?? []).filter((r) => chosen.has(r.id)).map((r) => r.clientId))];
const starts = useMemo(() => (rows ?? []).flatMap((r) => (r.startsAt === undefined ? [] : [r.startsAt])).sort((a, b) => a - b), [rows]);
const jobCount = counts ? counts.targets - counts.skipped : 0;
@@ -500,7 +568,7 @@ export default function RunProgress({
</Stack>
<RunProgressBar counts={counts} />
</Stack>
<RunCounters counts={counts} filter={filter} onFilter={setFilter} />
<RunCounters counts={counts} filter={filter} onFilter={setFilter} onRunAgain={runAgainOn} />
</Stack>
);
@@ -544,25 +612,34 @@ export default function RunProgress({
/>
{detail && <Chip size="small" variant="light" color="primary" label={detail.label} onDelete={() => setDetail(null)} />}
</Stack>
<Tooltip
title={
chosen.size
? 'A zip with the checked devices’ logs, one .log each.'
: 'A zip with every device’s log, one .log each. Check devices to narrow it.'
}
>
<span>
<Button
variant="outlined"
size="small"
startIcon={saving ? <CircularProgress size={14} color="inherit" /> : <DownloadOutlined />}
disabled={saving || jobsInRun === 0}
onClick={() => void saveLogs()}
>
{chosen.size ? `Download ${chosen.size} ${chosen.size === 1 ? 'Log' : 'Logs'}` : 'Download All Logs'}
</Button>
</span>
</Tooltip>
<Stack direction="row" sx={{ gap: 1, alignItems: 'center' }}>
{onRunAgain && checkedDevices.length > 0 && (
<Tooltip title="The same script again on the checked devices.">
<Button variant="outlined" size="small" startIcon={<PlayCircleOutlined />} onClick={() => onRunAgain(checkedDevices)}>
{`Run Again on ${checkedDevices.length}`}
</Button>
</Tooltip>
)}
<Tooltip
title={
chosen.size
? 'A zip with the checked devices’ logs, one .log each.'
: 'A zip with every device’s log, one .log each. Check devices to narrow it.'
}
>
<span>
<Button
variant="outlined"
size="small"
startIcon={saving ? <CircularProgress size={14} color="inherit" /> : <DownloadOutlined />}
disabled={saving || jobsInRun === 0}
onClick={() => void saveLogs()}
>
{chosen.size ? `Download ${chosen.size} ${chosen.size === 1 ? 'Log' : 'Logs'}` : 'Download All Logs'}
</Button>
</span>
</Tooltip>
</Stack>
</Stack>
</Stack>
}
@@ -8,6 +8,8 @@ import type { UserInteraction } from '@devolutions/iron-remote-desktop';
import type { ScreenTicketDto } from 'api/types';
import { h264Supported, routeSocket, VIDEO_DESTINATION, VideoSink, type VideoInfo } from './videoChannel';
/** What the toolbar can do to a running view. */
export interface RemoteScreenHandle {
ctrlAltDel: () => void;
@@ -36,6 +38,10 @@ div:has(> .screen-wrapper) { width: 100%; height: 100%; }
width: var(--rv-w) !important; height: var(--rv-h) !important;
min-width: var(--rv-w) !important; min-height: var(--rv-h) !important;
max-width: var(--rv-w) !important; max-height: var(--rv-h) !important;
}
.screen-viewer { position: relative !important; }
.screen-viewer canvas.exr-video {
position: absolute; inset: 0; width: 100% !important; height: 100% !important; pointer-events: none;
}`;
/** Sizes the screen to the container: Fit scales the desktop into it, Real keeps its pixels (and scrolls). */
@@ -61,11 +67,28 @@ interface Props {
sessionId: string;
scale: ScreenScale;
onPhase: (phase: ViewPhase, reason?: string) => void;
/** Text clipboard both ways (control sessions); read when the connection starts. */
clipboard?: boolean;
/** The device's H.264 encoder while video carries the screen; null when RDP bitmaps do. */
onVideo?: (info: VideoInfo | null) => void;
/** The device's desktop size once connected, and again whenever it changes. */
onDesktopSize?: (size: { width: number; height: number }) => void;
ref?: Ref<RemoteScreenHandle>;
}
/** Waits out the component's own clipboard set-up: the same permission query it makes, then a beat. */
async function clipboardSetUp() {
try {
await Promise.race([
navigator.permissions.query({ name: 'clipboard-read' as PermissionName }),
new Promise((resolve) => setTimeout(resolve, 1000))
]);
} catch {
// Not a permission this browser knows (Firefox): the component falls back the same way.
}
await new Promise((resolve) => setTimeout(resolve, 100));
}
/** An IronError (kind/backtrace), an Error, or anything else, as one line. */
function describe(error: unknown): string {
if (error && typeof error === 'object' && 'backtrace' in error && typeof error.backtrace === 'function') {
@@ -81,14 +104,18 @@ function describe(error: unknown): string {
* imported here, dynamically, so they load only with this view (the RDP backend
* inlines its WASM as a data URL: no asset to serve, and nothing in the main bundle).
*/
export default function RemoteScreenView({ ticket, sessionId, scale, onPhase, onDesktopSize, ref }: Props) {
export default function RemoteScreenView({ ticket, sessionId, scale, clipboard = false, onPhase, onDesktopSize, onVideo, ref }: Props) {
const hostRef = useRef<HTMLDivElement>(null);
const interaction = useRef<UserInteraction | null>(null);
const phase = useRef(onPhase);
phase.current = onPhase;
const desktopSize = useRef(onDesktopSize);
desktopSize.current = onDesktopSize;
const videoInfo = useRef(onVideo);
videoInfo.current = onVideo;
const scaleRef = useRef(scale);
const clipboardRef = useRef(clipboard);
clipboardRef.current = clipboard;
scaleRef.current = scale;
const elementRef = useRef<IronElement | null>(null);
@@ -114,6 +141,7 @@ export default function RemoteScreenView({ ticket, sessionId, scale, onPhase, on
let element: IronElement | null = null;
let connected = false;
const observers: { disconnect: () => void }[] = [];
let sink: VideoSink | undefined;
// The canvas holds 800x600 until the session sizes it: only a connected session's size is the device's.
const reportSize = (canvas: HTMLCanvasElement) => {
if (connected && canvas.width && canvas.height) desktopSize.current?.({ width: canvas.width, height: canvas.height });
@@ -121,9 +149,15 @@ export default function RemoteScreenView({ ticket, sessionId, scale, onPhase, on
phase.current('loading');
(async () => {
const [, rdp] = await Promise.all([import('@devolutions/iron-remote-desktop'), import('@devolutions/iron-remote-desktop-rdp')]);
const [, rdp, video] = await Promise.all([
import('@devolutions/iron-remote-desktop'),
import('@devolutions/iron-remote-desktop-rdp'),
h264Supported()
]);
await rdp.init('WARN');
if (stopped) return;
// H.264 from hosts that can encode it, drawn over the RDP canvas (RDP keeps input, cursor, clipboard).
if (video) sink = new VideoSink((info) => videoInfo.current?.(info));
element = document.createElement('iron-remote-desktop') as IronElement;
// Set before it is attached: the component reads its backend when it mounts.
@@ -145,6 +179,7 @@ export default function RemoteScreenView({ ticket, sessionId, scale, onPhase, on
const style = document.createElement('style');
style.textContent = SHADOW_CSS;
shadow.appendChild(style);
if (sink) canvas.after(sink.canvas);
const relayout = () => element && layout(element, host, scaleRef.current);
// The desktop size arrives (and changes) as the canvas' width and height.
const resized = new MutationObserver(() => {
@@ -159,20 +194,32 @@ export default function RemoteScreenView({ ticket, sessionId, scale, onPhase, on
void (async () => {
try {
const scheme = window.location.protocol === 'https:' ? 'wss' : 'ws';
const proxy = `${scheme}://${window.location.host}${ticket.socketPath}`;
const config = ui
.configBuilder()
.withUsername('remote-view')
.withPassword('-')
.withDestination('screen')
.withDestination(sink ? VIDEO_DESTINATION : 'screen')
.withServerDomain('')
.withProxyAddress(`${scheme}://${window.location.host}${ticket.socketPath}`)
.withProxyAddress(proxy)
.withAuthToken(sessionId)
.withDesktopSize({ width: Math.max(640, host.clientWidth), height: Math.max(480, host.clientHeight) })
.build();
// The screen host has no clipboard in v1.
ui.setEnableClipboard(false);
// Copy on either side, paste on the other: the component reads this browser's clipboard when the tab
// regains focus and writes the device's copies to it (Chromium asks the operator once).
ui.setEnableClipboard(clipboardRef.current);
phase.current('connecting');
const session = await ui.connect(config);
// The component fires "ready" before it sets up its clipboard handling (a permission query), and a
// connection made before that asks for no clipboard channel at all.
if (clipboardRef.current) await clipboardSetUp();
if (stopped) return;
const unroute = sink ? routeSocket(proxy, sink) : undefined;
let session: Awaited<ReturnType<typeof ui.connect>>;
try {
session = await ui.connect(config);
} finally {
unroute?.();
}
if (stopped) return;
phase.current('connected');
connected = true;
@@ -201,6 +248,8 @@ export default function RemoteScreenView({ ticket, sessionId, scale, onPhase, on
// Already down.
}
interaction.current = null;
sink?.close();
videoInfo.current?.(null);
observers.forEach((observer) => observer.disconnect());
elementRef.current = null;
element?.remove();
@@ -0,0 +1,407 @@
/**
* H.264 video beside the RDP client (ScreenHost README, Video).
*
* The browser asks for video in the RDCleanPath destination (`screen;video=h264`). A screen host
* that can encode answers `EXRMUX01` first and frames the stream from then on
* (`[channel u8][length u32 LE][payload]`: 0 RDP, 1 video); an older host, or one without an
* encoder (Windows PE), answers plain RDCleanPath and nothing changes. The RDP client (IronRDP,
* WASM) opens its own WebSocket, so {@link routeSocket} hands it a stand-in that unframes channel 0
* for it and gives channel 1 to a {@link VideoSink}: WebCodecs decodes the frames (in hardware
* where it can) onto a canvas over the RDP canvas, which keeps input, cursor and clipboard.
*/
const MAGIC = new TextEncoder().encode('EXRMUX01');
const RDP = 0;
const VIDEO = 1;
const HEADER = 5;
const START = 1;
const FRAME = 2;
const STOP = 3;
const ACK = 0x81;
const KEY = 0x82;
const OFF = 0x83;
/** No picture this long after the stream starts: this browser cannot show it. */
const FIRST_PICTURE_MS = 5000;
/** Decoder failures in a row (without a picture between) before giving up. */
const MAX_RECOVERIES = 3;
/** The destination hint the host understands. */
export const VIDEO_DESTINATION = 'screen;video=h264';
/** What the device encodes with, once video is on. */
export interface VideoInfo {
encoder: string;
hardware: boolean;
}
/** Whether this browser can show the host's H.264 (WebCodecs needs a secure context). */
export async function h264Supported(): Promise<boolean> {
if (!window.isSecureContext || typeof VideoDecoder === 'undefined' || typeof EncodedVideoChunk === 'undefined') return false;
try {
const result = await VideoDecoder.isConfigSupported({ codec: 'avc1.42E033', optimizeForLatency: true });
return Boolean(result.supported);
} catch {
return false;
}
}
/** The `avc1.PPCCLL` codec string from a key frame's SPS (profile, constraints, level). */
export function codecOf(annexB: Uint8Array): string {
for (let i = 0; i + 6 < annexB.length; i++) {
if (annexB[i] === 0 && annexB[i + 1] === 0 && annexB[i + 2] === 1 && (annexB[i + 3] & 0x1f) === 7) {
const hex = (v: number) => v.toString(16).padStart(2, '0').toUpperCase();
return `avc1.${hex(annexB[i + 4])}${hex(annexB[i + 5])}${hex(annexB[i + 6])}`;
}
}
return 'avc1.42E033';
}
function header(channel: number, length: number): Uint8Array<ArrayBuffer> {
const out = new Uint8Array(HEADER);
out[0] = channel;
new DataView(out.buffer).setUint32(1, length, true);
return out;
}
function frame(channel: number, payload: Uint8Array): Uint8Array<ArrayBuffer> {
const out = new Uint8Array(HEADER + payload.length);
out.set(header(channel, payload.length));
out.set(payload, HEADER);
return out;
}
/** Splits the host's bytes into frames (they arrive in any chunking). */
export class Deframer {
private buf = new Uint8Array(0);
private start = 0;
push(bytes: Uint8Array) {
const kept = this.buf.length - this.start;
const next = new Uint8Array(kept + bytes.length);
next.set(this.buf.subarray(this.start));
next.set(bytes, kept);
this.buf = next;
this.start = 0;
}
next(): { channel: number; payload: Uint8Array } | undefined {
const available = this.buf.length - this.start;
if (available < HEADER) return undefined;
const view = new DataView(this.buf.buffer, this.buf.byteOffset + this.start);
const length = view.getUint32(1, true);
if (available < HEADER + length) return undefined;
const channel = this.buf[this.start];
const payload = this.buf.subarray(this.start + HEADER, this.start + HEADER + length);
this.start += HEADER + length;
return { channel, payload };
}
}
/** Draws the host's video; made per connection. */
export class VideoSink {
readonly canvas: HTMLCanvasElement;
private readonly context: CanvasRenderingContext2D | null;
private decoder?: VideoDecoder;
private codec?: string;
private waitingForKey = true;
private lastSubmitted = -1;
private info?: VideoInfo;
private shown = false;
private off = false;
private recoveries = 0;
private watchdog?: ReturnType<typeof setTimeout>;
private send?: (message: Uint8Array) => void;
constructor(private readonly onInfo: (info: VideoInfo | null) => void) {
this.canvas = document.createElement('canvas');
this.canvas.className = 'exr-video';
this.canvas.style.display = 'none';
this.context = this.canvas.getContext('2d', { alpha: false, desynchronized: true });
}
/** The way back to the host (framed on channel 1). */
attach(send: (message: Uint8Array) => void) {
this.send = send;
}
message(payload: Uint8Array) {
if (this.off) return;
switch (payload[0]) {
case START:
this.start(payload.subarray(1));
break;
case FRAME:
this.frame(payload);
break;
case STOP:
this.stop();
break;
default:
}
}
close() {
clearTimeout(this.watchdog);
this.closeDecoder();
this.send = undefined;
}
private start(json: Uint8Array) {
try {
const start = JSON.parse(new TextDecoder().decode(json)) as { width: number; height: number; encoder: string; hardware: boolean };
this.canvas.width = start.width;
this.canvas.height = start.height;
this.info = { encoder: start.encoder, hardware: start.hardware };
} catch {
this.info = { encoder: 'H.264', hardware: false };
}
this.closeDecoder();
this.waitingForKey = true;
clearTimeout(this.watchdog);
this.watchdog = setTimeout(() => {
if (!this.shown) this.giveUp();
}, FIRST_PICTURE_MS);
}
private frame(payload: Uint8Array) {
const key = (payload[1] & 1) === 1;
const seq = new DataView(payload.buffer, payload.byteOffset).getUint32(2, true);
const data = payload.slice(6);
if (this.waitingForKey && !key) {
this.ack(seq);
return;
}
try {
if (key) {
const codec = codecOf(data);
if (!this.decoder || this.decoder.state === 'closed' || codec !== this.codec) this.configure(codec);
this.waitingForKey = false;
}
this.decoder!.decode(new EncodedVideoChunk({ type: key ? 'key' : 'delta', timestamp: seq, data }));
this.lastSubmitted = seq;
} catch {
this.ack(seq);
this.recover();
}
}
private configure(codec: string) {
this.closeDecoder();
this.codec = codec;
this.decoder = new VideoDecoder({ output: (picture) => this.draw(picture), error: () => this.recover() });
this.decoder.configure({
codec,
optimizeForLatency: true,
// What the host's NV12 conversion uses (BT.709, limited range).
colorSpace: { primaries: 'bt709', transfer: 'bt709', matrix: 'bt709', fullRange: false }
});
}
private draw(picture: VideoFrame) {
const seq = picture.timestamp;
try {
this.context?.drawImage(picture, 0, 0);
} finally {
picture.close();
}
this.recoveries = 0;
if (!this.shown) {
this.shown = true;
this.canvas.style.display = 'block';
this.onInfo(this.info ?? null);
}
this.ack(seq);
}
/** The decoder failed: start again from a key frame (and release the host's frames in flight). */
private recover() {
if (++this.recoveries > MAX_RECOVERIES) {
this.giveUp();
return;
}
this.closeDecoder();
this.waitingForKey = true;
if (this.lastSubmitted >= 0) this.ack(this.lastSubmitted);
this.send?.(new Uint8Array([KEY]));
}
/** This browser cannot show the video: the host goes back to RDP bitmaps for the session. */
private giveUp() {
if (this.off) return;
this.off = true;
this.stop();
this.send?.(new Uint8Array([OFF]));
}
private stop() {
clearTimeout(this.watchdog);
this.closeDecoder();
this.waitingForKey = true;
this.shown = false;
this.canvas.style.display = 'none';
this.onInfo(null);
}
private closeDecoder() {
if (this.decoder && this.decoder.state !== 'closed') {
try {
this.decoder.close();
} catch {
// Already closed.
}
}
this.decoder = undefined;
this.codec = undefined;
}
private ack(seq: number) {
const message = new Uint8Array(5);
message[0] = ACK;
new DataView(message.buffer).setUint32(1, seq >>> 0, true);
this.send?.(message);
}
}
function bytesOf(data: unknown): Uint8Array | undefined {
if (data instanceof ArrayBuffer) return new Uint8Array(data);
if (ArrayBuffer.isView(data)) return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
return undefined;
}
function startsWith(bytes: Uint8Array, prefix: Uint8Array, length = prefix.length) {
for (let i = 0; i < Math.min(length, bytes.length); i++) if (bytes[i] !== prefix[i]) return false;
return true;
}
/**
* Stands in for the RDP client's WebSocket: what the WASM glue uses of one (events through
* addEventListener, send, close, readyState, binaryType), passing RDP bytes through and video to the sink.
*/
class MuxSocket extends EventTarget {
binaryType: BinaryType = 'blob';
private mode: 'detect' | 'raw' | 'mux' = 'detect';
private head = new Uint8Array(0);
private readonly inbound = new Deframer();
constructor(
private readonly socket: WebSocket,
private readonly sink: VideoSink
) {
super();
socket.binaryType = 'arraybuffer';
socket.addEventListener('open', () => this.dispatchEvent(new Event('open')));
socket.addEventListener('error', () => this.dispatchEvent(new Event('error')));
socket.addEventListener('close', (e) => {
sink.close();
this.dispatchEvent(new CloseEvent('close', { code: e.code, reason: e.reason, wasClean: e.wasClean }));
});
socket.addEventListener('message', (e: MessageEvent<ArrayBuffer | string>) => this.receive(e.data));
sink.attach((message) => {
if (this.mode === 'mux' && socket.readyState === WebSocket.OPEN) socket.send(frame(VIDEO, message));
});
}
get readyState() {
return this.socket.readyState;
}
get url() {
return this.socket.url;
}
get bufferedAmount() {
return this.socket.bufferedAmount;
}
send(data: string | ArrayBufferLike | Blob | ArrayBufferView) {
if (this.mode !== 'mux') {
this.socket.send(data as string | ArrayBuffer | Blob | ArrayBufferView<ArrayBuffer>);
} else if (data instanceof Blob) {
// The RDP client sends Blobs: framed without reading them, so the order stays.
this.socket.send(new Blob([header(RDP, data.size), data]));
} else {
const bytes = bytesOf(data);
if (bytes) this.socket.send(frame(RDP, bytes));
}
}
close(code?: number, reason?: string) {
this.socket.close(code, reason);
}
private receive(data: ArrayBuffer | string) {
if (typeof data === 'string') {
this.deliver(data);
return;
}
let bytes = new Uint8Array(data);
if (this.mode === 'detect') {
const joined = new Uint8Array(this.head.length + bytes.length);
joined.set(this.head);
joined.set(bytes, this.head.length);
if (!startsWith(joined, MAGIC)) {
this.mode = 'raw';
this.deliver(joined);
return;
}
if (joined.length < MAGIC.length) {
this.head = joined;
return;
}
this.mode = 'mux';
bytes = joined.subarray(MAGIC.length);
}
if (this.mode === 'raw') {
this.deliver(bytes);
return;
}
this.inbound.push(bytes);
for (let f = this.inbound.next(); f; f = this.inbound.next()) {
if (f.channel === RDP) this.deliver(f.payload);
else if (f.channel === VIDEO) this.sink.message(f.payload);
}
}
private deliver(payload: Uint8Array | string) {
let data: string | ArrayBuffer | Blob = payload as string;
if (payload instanceof Uint8Array) {
const copy = payload.slice().buffer;
data = this.binaryType === 'blob' ? new Blob([copy]) : copy;
}
this.dispatchEvent(new MessageEvent('message', { data }));
}
}
const routes = new Map<string, VideoSink>();
let installed = false;
/** Replaces `window.WebSocket` once with a constructor that hands routed URLs a {@link MuxSocket}. */
function install() {
if (installed) return;
installed = true;
const Native = window.WebSocket;
function Routing(url: string | URL, protocols?: string | string[]) {
const target = String(url);
for (const [prefix, sink] of routes) {
if (target.startsWith(prefix)) {
routes.delete(prefix);
return new MuxSocket(new Native(url, protocols), sink);
}
}
return new Native(url, protocols);
}
Object.assign(Routing, { CONNECTING: 0, OPEN: 1, CLOSING: 2, CLOSED: 3 });
Routing.prototype = Native.prototype;
window.WebSocket = Routing as unknown as typeof WebSocket;
}
/** The next WebSocket opened to `url` carries video for `sink`; returns a function that withdraws the route. */
export function routeSocket(url: string, sink: VideoSink): () => void {
install();
routes.set(url, sink);
return () => {
if (routes.get(url) === sink) routes.delete(url);
};
}
@@ -18,6 +18,8 @@ import RunProgress, { useRun } from 'sections/runs/RunProgress';
import { runColumns } from 'sections/runs/RecentRuns';
import { downloads, keys } from 'api/client';
import useApi from 'hooks/useApi';
import useAutomation from 'hooks/useAutomation';
import { useGate } from 'hooks/useSession';
import useLiveRefresh from 'hooks/useLiveRefresh';
import { formatAbsolute } from 'utils/format';
@@ -43,6 +45,11 @@ export default function ExecutionsPanel({ scriptId }: { scriptId: string }) {
const executions = useApi<ExecutionSummaryDto[]>(keys.scriptExecutions(scriptId));
const execution = useRun(runId);
const runGate = useGate('jobs.run', 'Run Jobs');
const automation = useAutomation();
// The same script again on some of the run's devices (a status tile's, or the checked ones).
const runAgainOn = (clientIds: string[]) =>
automation.openRun({ scriptId, targets: clientIds.map((id) => ({ kind: 'device' as const, id })) });
const run = execution.data;
const { mutate: mutateExecutions } = executions;
const refresh = useCallback(() => void mutateExecutions(), [mutateExecutions]);
@@ -66,6 +73,7 @@ export default function ExecutionsPanel({ scriptId }: { scriptId: string }) {
error={execution.error && !run ? execution.error.message : undefined}
openJobId={jobId}
onOpenJob={setJobId}
onRunAgain={runGate ? undefined : runAgainOn}
toolbarStart={
<Stack direction={{ xs: 'column', md: 'row' }} sx={{ gap: 1.5, alignItems: { md: 'center' }, justifyContent: 'space-between' }}>
<Breadcrumbs separator={<RightOutlined style={{ fontSize: '0.6rem' }} />} aria-label="Execution">
@@ -55,6 +55,7 @@ export interface ScriptDraft {
runFromFile: boolean;
cleanUpAfterRun: boolean;
setWorkingDirectory: boolean;
runAsUser: boolean;
restartAfterRun: RestartAfterRun;
restartDelaySeconds: number;
/** Warn Signed-In Users: 0 is off. */
@@ -80,6 +81,7 @@ export const NEW_SCRIPT_DRAFT: ScriptDraft = {
runFromFile: false,
cleanUpAfterRun: true,
setWorkingDirectory: false,
runAsUser: false,
restartAfterRun: 'off',
restartDelaySeconds: 0,
restartWarningSeconds: 0
@@ -102,6 +104,7 @@ export function draftFromScript(script: ScriptDto): ScriptDraft {
runFromFile: script.runFromFile ?? false,
cleanUpAfterRun: script.cleanUpAfterRun ?? true,
setWorkingDirectory: script.setWorkingDirectory ?? false,
runAsUser: script.runAsUser ?? false,
restartAfterRun: script.restartAfterRun ?? 'off',
restartDelaySeconds: script.restartDelaySeconds ?? 0,
restartWarningSeconds: script.restartWarningSeconds ?? 0
@@ -138,15 +141,17 @@ export function saveBody(draft: ScriptDraft, name = draft.name): SaveScriptBody
cleanUpFiles: stored.cleanUpFiles,
runFromFile: stored.runFromFile,
cleanUpAfterRun: stored.cleanUpAfterRun,
setWorkingDirectory: stagesFile(stored.engine, stored.runFromFile) && stored.setWorkingDirectory,
setWorkingDirectory: stagesFile(stored.engine, stored.runFromFile, stored.runAsUser) && stored.setWorkingDirectory,
runAsUser: stored.runAsUser,
restartAfterRun: stored.restartAfterRun,
restartDelaySeconds: stored.restartAfterRun === 'off' ? 0 : stored.restartDelaySeconds,
restartWarningSeconds: stored.restartAfterRun === 'off' ? 0 : stored.restartWarningSeconds
};
}
/** Windows PowerShell 5.1 and Bash always run from a staged file; PowerShell 7 only with Run From File. */
export const stagesFile = (engine: ScriptEngine, runFromFile: boolean) => engine !== 'PowerShell' || runFromFile;
/** Windows PowerShell 5.1 and Bash always run from a staged file; PowerShell 7 with Run From File or as the signed-in user. */
export const stagesFile = (engine: ScriptEngine, runFromFile: boolean, runAsUser = false) =>
engine !== 'PowerShell' || runFromFile || runAsUser;
/** Body for a copy of a stored script ("Name (copy)"). */
export const duplicateBody = (script: ScriptDto | ScriptDraft) => {
@@ -25,7 +25,6 @@ import useApi from 'hooks/useApi';
import useNow from 'hooks/useNow';
import { useGate } from 'hooks/useSession';
import Field from './Field';
import AgentDownloadsCard from './AgentDownloads';
import { CommandBox, PlatformPicker } from './InstallControls';
import { installCommand, InstallPlatform, msiexecCommand } from './installCommands';
import { SETTINGS_KEYS, SETTINGS_PERMISSION, SETTINGS_PERMISSION_LABEL } from './keys';
@@ -315,8 +314,6 @@ export default function EnrollmentTokens() {
onClose={() => setRevoking(null)}
/>
<AgentDownloadsCard />
<AddDeviceDialog open={addDeviceOpen} onClose={() => setAddDeviceOpen(false)} />
</Stack>
);
@@ -28,6 +28,7 @@ import { api, errorMessage } from 'api/client';
import useApi from 'hooks/useApi';
import { useGate } from 'hooks/useSession';
import { formatBytes } from 'utils/format';
import AgentDownloadsCard from './AgentDownloads';
import DeviceUploadsCard from './DeviceUploadsCard';
import Field from './Field';
import TestSteps from './TestSteps';
@@ -560,6 +561,8 @@ export default function StorageSettings() {
)}
</MainCard>
<AgentDownloadsCard />
<DeviceUploadsCard gate={gate} />
</Stack>
);
@@ -38,6 +38,12 @@ const LIFETIMES = [
// ==============================|| AUTHENTICATION › BUILT-IN ||============================== //
/** The card's hover: what the break-glass account is, and which one this server keeps. */
function breakGlassHelp(userName: string | null | undefined) {
const account = userName ? `The break-glass account (${userName})` : 'The break-glass account (removed)';
return `Accounts kept by this server. ${account} has full access through no binding, for recovery; the auth-reset verb on the server turns Built-In on and gives it a new one-time password.`;
}
export default function BuiltInSignInTab({ dirtyKey }: { dirtyKey: string }) {
const form = useSettingsForm<BuiltInSettings, Draft>(IdentityRoutes.builtIn, toDraft);
useReportDirty(dirtyKey, form.dirty);
@@ -49,7 +55,7 @@ export default function BuiltInSignInTab({ dirtyKey }: { dirtyKey: string }) {
return (
<Stack sx={{ gap: 3 }}>
<MainCard title={<CardTitle title="Built-In Sign-In" help="Accounts kept by this server, the break-glass account among them." />}>
<MainCard title={<CardTitle title="Built-In Sign-In" help={breakGlassHelp(view?.breakGlassUserName)} />}>
{form.loading ? (
<Skeleton variant="rounded" height={72} />
) : form.loadError ? (
@@ -63,33 +69,22 @@ export default function BuiltInSignInTab({ dirtyKey }: { dirtyKey: string }) {
summary={summary}
help="Off: only the other methods that are on can sign people in. Turning a method on or off asks you to confirm it is you."
/>
<Properties
labelWidth={170}
items={[
{
label: 'Break-Glass Account',
value: (
<>
{view.breakGlassUserName ?? 'Removed'}
<HoverHelp title="Full access through no binding, for recovery. The auth-reset verb on the server turns Built-In on and gives it a new one-time password." />
</>
)
},
...(view.forcedByEnvironment
? [
{
label: 'Built-In Form',
value: (
<>
{`Offered: ${view.forceVariable} is set`}
<HoverHelp title="The way back in when a provider fails. Remove the variable once sign-in works again." />
</>
)
}
]
: [])
]}
/>
{view.forcedByEnvironment && (
<Properties
labelWidth={170}
items={[
{
label: 'Built-In Form',
value: (
<>
{`Offered: ${view.forceVariable} is set`}
<HoverHelp title="The way back in when a provider fails. Remove the variable once sign-in works again." />
</>
)
}
]}
/>
)}
</Stack>
) : null}
</MainCard>
@@ -4,6 +4,7 @@ import { useNavigate } from 'react-router-dom';
// project imports
import { shellLabel, shells, TERMINAL_THEME, type ShellController, type ShellState } from './shellSessions';
import { FONT_SIZE, TERMINAL_THEMES, terminalPrefs, useTerminalPrefs } from './terminalPrefs';
// assets
import ImportOutlined from '@ant-design/icons/ImportOutlined';
@@ -55,6 +56,11 @@ const CHROME_CSS = `
button.primary { border-color: #2a3b5c; }
button.danger:hover { background: rgba(248, 81, 73, 0.14); color: #ff7b72; }
.anticon { display: inline-flex; font-size: 14px; }
.prefs { display: flex; align-items: center; gap: 2px; padding-right: 6px; margin-right: 2px; border-right: 1px solid #1f2b40; }
.prefs button { padding: 0 8px; }
.prefs .size { min-width: 34px; text-align: center; color: #c9d4e5; font-variant-numeric: tabular-nums; }
select { height: 28px; border-radius: 4px; border: 1px solid #2a3b5c; background: #111a29; color: ${TERMINAL_THEME.foreground}; font: inherit; padding: 0 6px; }
select:focus-visible { outline: 2px solid ${TERMINAL_THEME.cursor}; outline-offset: 1px; }
`;
function Chrome({ controller }: { controller: ShellController }) {
@@ -63,6 +69,7 @@ function Chrome({ controller }: { controller: ShellController }) {
const started = shellLabel(startedShell);
const name = hostname || controller.clientId.slice(0, 12);
const active = ACTIVE.includes(state);
const prefs = useTerminalPrefs();
return (
<>
@@ -80,6 +87,37 @@ function Chrome({ controller }: { controller: ShellController }) {
)}
</div>
<div className="actions">
<div className="prefs">
<select
aria-label="Terminal Theme"
title="Terminal Theme"
value={prefs.themeId}
onChange={(e) => terminalPrefs.set({ themeId: e.target.value })}
>
{TERMINAL_THEMES.map((t) => (
<option key={t.id} value={t.id}>
{t.label}
</option>
))}
</select>
<button
type="button"
title="Smaller Text (Ctrl + -)"
disabled={prefs.fontSize <= FONT_SIZE.min}
onClick={() => terminalPrefs.zoom(-1)}
>
A−
</button>
<span className="size">{prefs.fontSize}</span>
<button
type="button"
title="Larger Text (Ctrl + =)"
disabled={prefs.fontSize >= FONT_SIZE.max}
onClick={() => terminalPrefs.zoom(1)}
>
A+
</button>
</div>
{active ? (
<button type="button" className="danger" onClick={() => controller.close()}>
<PoweroffOutlined /> Close Session
@@ -0,0 +1,135 @@
import { useState } from 'react';
// material-ui
import Box from '@mui/material/Box';
import Button from '@mui/material/Button';
import ButtonBase from '@mui/material/ButtonBase';
import IconButton from '@mui/material/IconButton';
import MenuItem from '@mui/material/MenuItem';
import Popover from '@mui/material/Popover';
import Stack from '@mui/material/Stack';
import TextField from '@mui/material/TextField';
import Tooltip from '@mui/material/Tooltip';
import Typography from '@mui/material/Typography';
// project imports
import HoverHelp from 'components/HoverHelp';
import { MONO_FONT_FAMILY } from 'config';
import { FONT_SIZE, SCROLLBACK_OPTIONS, TERMINAL_THEMES, terminalPrefs, useTerminalPrefs } from './terminalPrefs';
// assets
import FontSizeOutlined from '@ant-design/icons/FontSizeOutlined';
import MinusOutlined from '@ant-design/icons/MinusOutlined';
import PlusOutlined from '@ant-design/icons/PlusOutlined';
/** Theme, text size and scrollback of every terminal in this browser. */
export default function TerminalSettings() {
const prefs = useTerminalPrefs();
const [anchor, setAnchor] = useState<HTMLElement | null>(null);
return (
<>
<Tooltip title="Terminal Settings">
<Button
variant="outlined"
color="secondary"
aria-label="Terminal Settings"
onClick={(e) => setAnchor(e.currentTarget)}
sx={{ minWidth: 0, px: 1.25 }}
>
<FontSizeOutlined />
</Button>
</Tooltip>
<Popover
open={Boolean(anchor)}
anchorEl={anchor}
onClose={() => setAnchor(null)}
anchorOrigin={{ vertical: 'bottom', horizontal: 'right' }}
transformOrigin={{ vertical: 'top', horizontal: 'right' }}
slotProps={{ paper: { sx: { p: 2, width: 336 } } }}
>
<Stack sx={{ gap: 2 }}>
<Stack sx={{ gap: 1 }}>
<Typography variant="subtitle2">Theme</Typography>
<Stack direction="row" sx={{ gap: 1, flexWrap: 'wrap' }}>
{TERMINAL_THEMES.map(({ id, label, theme }) => (
<Tooltip key={id} title={label}>
<ButtonBase
aria-label={label}
aria-pressed={prefs.themeId === id}
onClick={() => terminalPrefs.set({ themeId: id })}
sx={{
width: 44,
height: 32,
borderRadius: 1,
bgcolor: theme.background,
color: theme.foreground,
fontFamily: MONO_FONT_FAMILY,
fontSize: 13,
border: 2,
borderColor: prefs.themeId === id ? 'primary.main' : 'divider'
}}
>
<Box component="span" sx={{ color: theme.green ?? theme.cursor }}>
&gt;
</Box>
_
</ButtonBase>
</Tooltip>
))}
</Stack>
</Stack>
<Stack sx={{ gap: 1 }}>
<Stack direction="row" sx={{ alignItems: 'center' }}>
<Typography variant="subtitle2">Text Size</Typography>
<HoverHelp title="In the terminal: Ctrl + = and Ctrl + - (or Ctrl + mouse wheel) change the size, Ctrl + 0 resets it." />
</Stack>
<Stack direction="row" sx={{ alignItems: 'center', gap: 1 }}>
<IconButton
size="small"
aria-label="Smaller"
onClick={() => terminalPrefs.zoom(-1)}
disabled={prefs.fontSize <= FONT_SIZE.min}
>
<MinusOutlined />
</IconButton>
<Typography sx={{ minWidth: 48, textAlign: 'center', fontVariantNumeric: 'tabular-nums' }}>{prefs.fontSize} px</Typography>
<IconButton size="small" aria-label="Larger" onClick={() => terminalPrefs.zoom(1)} disabled={prefs.fontSize >= FONT_SIZE.max}>
<PlusOutlined />
</IconButton>
<Button
size="small"
onClick={() => terminalPrefs.zoom(0)}
disabled={prefs.fontSize === FONT_SIZE.default}
sx={{ ml: 'auto' }}
>
Reset
</Button>
</Stack>
</Stack>
<Stack sx={{ gap: 1 }}>
<Stack direction="row" sx={{ alignItems: 'center' }}>
<Typography variant="subtitle2">Scrollback</Typography>
<HoverHelp title="Output lines kept above the screen; older lines drop off as new output arrives." />
</Stack>
<TextField
select
size="small"
aria-label="Scrollback"
value={prefs.scrollback}
onChange={(e) => terminalPrefs.set({ scrollback: Number(e.target.value) })}
>
{SCROLLBACK_OPTIONS.map((lines) => (
<MenuItem key={lines} value={lines}>
{lines.toLocaleString()} Lines
</MenuItem>
))}
</TextField>
</Stack>
</Stack>
</Popover>
</>
);
}

Some files were not shown because too many files have changed in this diff Show More