Opt-in Network Endpoints (LAN)

This page describes Darling v3.13.0. The source of this page is on GitHub at that version.

Audience: operators.

This page covers the opt-in LAN endpoints for the store, MCP and the web dashboard. It moved here from the Darling operator guide.

By default all three network surfaces bind loopback only — the store to 127.0.0.1, the MCP server and the web dashboard to localhost — exactly as they always have. Three optional, independent opt-ins let a remote viewer, MCP client, or browser on your trusted LAN reach them. This is a home-lab / trusted-subnet feature: never expose any of these endpoints to the internet. The store endpoint is managed-mode only, and the MCP and web endpoints are managed-mode or container only (a container’s port mapping is its exposure boundary, #1804); elsewhere in bring-your-own mode your own PostgreSQL / reverse proxy governs exposure and the config is ignored with a warning. All three are fail-closed — any invalid or incomplete field degrades that endpoint back to loopback and logs a critical line rather than exposing it. Removing the config on the next restart closes the box again.

Guided setup (--configure-network)

The fastest path is the interactive wizard — run it on the service host:

PerformanceMonitor.Darling.Service.exe --configure-network

It shows the current exposure (read from the service’s own resolvers), then walks you through the store, MCP, the web dashboard, any comma combination (e.g. 1,3), or all three at once (or a disable that removes all exposure). Every answer is validated by delegation to the exact checks the running service fail-closes on, so the wizard can never write a config the service would refuse — it re-prompts with the resolver’s own reason. It generates the MCP bearer / web access tokens for you (DPAPI-protected; each plaintext is printed once, so save it then), edits darling.json in place preserving every comment behind a timestamped darling.json.bak-<timestamp> backup, replaces only the keys it asks about when a network block already exists (every other key in that block, such as the tls and hostName of the MCP block and the tls and oidc of the web block, is kept as written and named on a Kept ... from the existing darling.json. line), prints the scoped firewall command(s), the --export-viewer-config handoff, and the web dashboard’s browser login URL (http://<listen>:<port>/?token=..., or https:// when web.network.tls is set), and offers to restart the service to apply. install-darling.ps1 -Network runs it automatically right after the install reaches Running. The manual field reference below documents exactly what it writes.

For the MCP and web endpoints, the allowFrom prompt takes one range or a comma list. The wizard writes the list as one comma string. When an MCP or web endpoint is exposed, the summary adds a TLS: line under it. The line says whether HTTPS is on, off, or misconfigured, and it names the mcp.network.tls or web.network.tls setting. The wizard does not ask for a certificate. The tls blocks are file settings, and a restart applies them.

Firewall rules (--configure-firewall)

The service runs as NT SERVICE\PerformanceMonitor Darling, an unprivileged virtual account that cannot create Windows Firewall rules — and should not be able to. So the rules are managed from the elevated install instead: install-darling.ps1 runs --configure-firewall for you (before the first start, and again after -Network), and uninstall-darling.ps1 removes them. Run it by hand after any edit to a network block:

PerformanceMonitor.Darling.Service.exe --configure-firewall

Run elevated. It reconciles all three scoped rules — store, MCP, web dashboard — against darling.json in one pass: it opens the port for every surface that really is exposed and removes the rule for every surface that is not, so it also cleans up after an exposure you turned back off. It is idempotent (safe on every upgrade).

The port each rule is named for comes from the control plane, not from the file. mcp.port / web.port in darling.json are only a first-run seed; config.config_service.mcp_port / web_port is what the endpoint actually binds, so a rule named from the file after someone moved the port in the Viewer’s Settings would open a port nothing is listening on and leave the served port shut. The verb therefore reads those two columns before it plans. That read is best effort — the verb still has to run at install time, before the store exists, where darling.json‘s port is the value the store will be seeded with — and it is never silent: when the store cannot be reached it names the port it used, why it could not do better, and the one case in which that port is wrong (a port that has since been changed in the Viewer), so re-running it once the service is up moves the rule. --enable-mcp / --enable-web have no such window: they take the port back from the store write they already perform, so they cannot open a port on a guessed number at all.

Because the port is part of the rule’s name, changing a port does not update a rule — it makes a different one and leaves the old one standing as an inbound allow on a port nothing serves. Every removal here therefore sweeps PerformanceMonitor Darling <surface> (port *) rather than one exact name, so the stale rule goes with it. The wildcard is derived from a rule name this product built; a name that does not parse degrades to the exact-name removal, so a sweep can never reach a rule that is not ours.

“Really exposed” is decided by the same resolvers the running service fail-closes on, not by reading listen at face value. A network block the service would degrade to loopback — an unparseable listen, a missing allowFrom, an allowFrom list with one invalid entry, an address family that disagrees, a missing token, BYO mode — gets no open port, and the verb tells you why.

The running service never touches these rules. It checks them on start and logs what it finds: nothing at all for the normal loopback-only install, one INFO line when an exposed endpoint’s rule is present, and one WARN naming the exact command when an exposed endpoint’s rule is missing or when a loopback-only endpoint still has a stale rule open. It states each verdict once, not once per retry.

Headless enable/disable + firewall (--enable-mcp / --enable-web)

On a box with no Viewer, two things are otherwise awkward: the enabled flags in the mcp / web blocks below are only a first-run seed — after the first run the store (config.config_service.mcp_enabled / web_enabled) is authoritative and is normally flipped only from the Viewer’s Settings — and the service account (NT SERVICE\PerformanceMonitor Darling) cannot open the firewall itself. Four verbs, run on the service host, close both in one elevated action:

PerformanceMonitor.Darling.Service.exe --enable-mcp
PerformanceMonitor.Darling.Service.exe --disable-mcp
PerformanceMonitor.Darling.Service.exe --enable-web
PerformanceMonitor.Darling.Service.exe --disable-web

Each flips only its endpoint’s live store flag with a targeted config_service write; the service hot-reloads within one collection sweep — no restart. If that endpoint’s network block opts into LAN exposure (a non-loopback listen), the verb also reconciles that endpoint’s scoped, idempotent-by-name firewall rule: run elevated, it opens (or, on --disable-*, removes) the rule; run non-elevated, the store toggle still succeeds and it prints the exact elevated firewall command to run by hand (a loopback-only endpoint needs no rule and says so). Managed-mode only, Windows only. So the headless bring-up is: write the network block (the wizard above or the manual reference below), then --enable-mcp / --enable-web from an elevated shell.

After --enable-web the verb prints the address to open, for example http://localhost:5153/. After --enable-mcp it prints the claude mcp add command, the same one the Viewer’s Settings copies, with <token> in place of the token. When darling.json sets a token, the verb also names the command that shows it: --print-web-token or --print-mcp-token. The verb never prints the token itself.

Verify it’s actually reachable (and the two failures that look like bugs)

Enabling an endpoint is not the same as reaching it, and both common failures leave the store flag reading true, so “it says enabled” is not proof. After --enable-mcp / --enable-web, verify on the service host:

  1. The listener is on the LAN address, not loopback. Get-NetTCPConnection -State Listen | Where-Object LocalPort -eq 5152 (or 5153 for web) must show the box’s LAN IP, e.g. 10.0.0.5:5152 — not only ::1 / 127.0.0.1. Enabled but still loopback-bound is the single most common failure: the store flag is on, but the service loaded darling.json before the network block existed. The block is read once at service start — the enable toggle stops/starts the endpoint with the already-loaded config and does not reload the file. Restart the service (Restart-Service 'PerformanceMonitor Darling') so it re-reads the block, then re-check the listener; after the restart run --configure-firewall elevated if the firewall rule is missing (the service account cannot create it, so the service only tells you it is missing).
  2. The scoped firewall rule exists and covers the client. Get-NetFirewallRule -DisplayName 'PerformanceMonitor Darling MCP (port 5152)' (or ... Web (port 5153)) should be Enabled=True, Action=Allow, scoped to the network.allowFrom ranges. If it is absent, the service’s own start-up log already says so and names the command; --configure-firewall elevated is the one-step fix. After you edit allowFrom, run --configure-firewall again. The service checks that the rule exists. It does not check which ranges the rule covers. Reading rules needs no elevation, so this check works from any shell.

Then from the client host:

  1. Connect to the box’s LAN IP, never localhost. Use http://<box-LAN-IP>:5152/, or https://<hostName>:5152/ when mcp.network.tls is set (the name must be the one on the certificate). localhost / 127.0.0.1 only resolves on the box itself, so an off-box MCP client pointed at localhost fails silently — this is the number-one “MCP won’t connect” cause. Send Authorization: Bearer <token> (the network.token), and do a fresh initialize + tools/list rather than trusting a cached tool list from a previous version.

After a reinstall: the installer replaces binaries but does not touch darling.json (the zip ships only darling.sample.json) or the store, so the network block and both live flags survive the upgrade — and the reinstall restarts the service, which re-reads the block. If MCP stops connecting afterward it is almost always failure 3 (the client pointed at localhost) or a missing firewall rule, not lost config: run --configure-firewall elevated to re-open the rule if check 2 comes up empty (the installer already does this, so an in-place upgrade normally leaves the rules correct). A stale loopback bind is unlikely after a restart unless the block itself is invalid, in which case the endpoint fail-closes to loopback and logs a critical line saying why — fix the block and restart again. A full --configure-network re-run is only needed if the network block itself is gone.

Store endpoint (viewer over the LAN)

Add a network block to postgres (managed mode):

"postgres": {
  "managed": true,
  "port": 5641,
  "network": {
    "listen": "192.168.1.205",
    "allowFrom": "192.168.1.0/24",
    "role": "viewer"
  }
}

On every start the service reconciles this against the live cluster: it adds the bind IP to listen_addresses, generates a self-signed TLS certificate (server.crt / server.key beside the data directory, with both an IP SAN for listen and a DNS SAN for the machine hostname), writes a marked hostssl darling <role> <allowFrom> scram-sha-256 rule into pg_hba.conf for each admitted role and reloads, and checks (never creates — see Firewall rules) that the store’s scoped firewall rule matches.

  • allowFrom: one range in CIDR form, with each IPv4 address written as four plain decimal numbers (no leading zeros) and no IPv6 zone index. The store takes ONE range and never a list, because the value feeds the pg_hba.conf rule that the service reconciles. Host bits are masked, so 192.168.1.5/24 means 192.168.1.0/24.

  • role — the pg_hba login role(s) the rule names: "viewer" (default, read-only — the secure default, covering a laptop reading every dashboard, chart, and finding; it writes nothing, and the web dashboard does not use it, because the web dashboard has its own web login that never gets a network line), "admin" (full remote writes; the service logs a warning because admin holds the config_command / config_monitored_servers / config_notification service-credential pivot), "sources" (the external alert source logins, through the darling_alert_sources group: the line reads hostssl darling +darling_alert_sources <allowFrom> scram-sha-256; see Alert sources on another machine), or several at once — "admin,viewer" or "viewer,sources", separated by a comma, a +, or whitespace. Blank still means "viewer" alone, and one unknown element rejects the whole value. Both writes one hostssl line per role inside the managed block, so an admin seat and any number of read-only ones reach the same store. Never the superuser, and never all: every generated line still names exactly one role and one CIDR, so narrowing allowFrom later tightens all of them together — unlike a second line hand-added outside the markers, which the reconciler preserves verbatim and therefore leaves on the old, wider CIDR. A value naming anything else is rejected whole, including a typo in one half of a pair: the store degrades to loopback with the reason logged rather than opening with the half that parsed. Absent or blank still means viewer alone. This is distinct from postgres.connectAs (the local VM viewer’s loopback role, default admin): network.role is the remote role and defaults to viewer, so the two have opposite defaults — the local seat is writable, the remote seat is read-only, unless you say otherwise.

  • TLS is verify-full, not require. Because Darling generates the cert, the client can pin it, so the connection string below uses SSL Mode=VerifyFull — which actually defends against an on-path MITM (require verifies nothing). The store’s network pg_hba line is hostssl, so a non-TLS network client is refused.

  • The firewall is defense-in-depth, not the boundary — pg_hba + TLS are. --configure-firewall (elevated) creates the store’s scoped rule for you along with the other two; the equivalent by hand is:

    New-NetFirewallRule -DisplayName "PerformanceMonitor Darling store (port 5641)" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 5641 -RemoteAddress 192.168.1.0/24
    

That is the service side. The viewer side is Connect a Remote Viewer — --export-viewer-config on this host writes the viewer machine’s whole configuration folder (config, certificate, and a plain-text field reference), and that section covers copying it over, the certificate’s placement and rotation, and the manual --print-viewer-connection fallback.

MCP endpoint (assistant over the LAN)

Add a network block to mcp (managed mode, or the compose container; mcp.enabled must be true):

"mcp": {
  "enabled": true,
  "port": 5152,
  "network": {
    "listen": "192.168.1.205",
    "allowFrom": "192.168.1.0/24",
    "encryptedToken": "<output of --encrypt-password>"
  }
}

When listen is a network address and a token is present and allowFrom is a valid CIDR list, the MCP host binds that interface behind two gates: an in-app CIDR check on the remote address (checked first; loopback is always allowed, so local clients keep working) and a required bearer token (constant-time, no loopback exemption). An address outside allowFrom gets a 403 whatever token it sends. Any missing precondition keeps MCP loopback-only. A token configured with no network listen also keeps MCP loopback-only and gates the loopback listener: every local client sends Authorization: Bearer <token>, and a token that cannot be decrypted stops the MCP server from starting rather than serving it open. With no token configured, an enabled MCP server does not start unless mcp.allowTokenlessLoopback is true, which serves local clients with no token and with the write and investigation tools off. A POST to MCP whose Content-Type is not application/json is refused with 415. Prefer encryptedToken (a DPAPI blob from --encrypt-password); a plaintext token works for dev but is warned. env:NAME and file:PATH references are for the compose and Linux setups. A Windows service uses encryptedToken. Set the same scoped firewall rule for the MCP port:

Lost the token? --print-mcp-token (elevated) reprints it from darling.json — --print-web-token does the same for the dashboard. Both write the live token to STDOUT with every warning on STDERR, so ... --print-mcp-token | clip captures the value and still shows the warning. This discloses nothing new: the blob is DPAPI at LocalMachine scope with an entropy constant published in this repository, and darling.json is readable by members of the local group PerformanceMonitor Darling Operators by design (see Security & Least-Privilege Roles), so any member of that group could already decrypt it. The elevation requirement makes reprinting a deliberate act; the token’s actual protection is the file’s ACL. If the token has leaked rather than been mislaid, reprinting is not the fix — --configure-network generates a new one, and every client configured against the old one must be updated.

New-NetFirewallRule -DisplayName "Darling MCP" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 5152 -RemoteAddress 192.168.1.0/24

The token must have at least 16 characters, at least 6 of them different (--configure-network generates 32 random ones). A shorter or more repetitive token keeps MCP loopback-only. On the loopback bind such a token still gates every request, but the MCP write and investigation tools stay off with it, and the web dashboard serves reads only with one. The service log says why. The log says the token is shorter than the minimum, or uses too few different characters; it does not give its length. To make a strong token yourself, run this in PowerShell, which uses the system’s cryptographic random generator and prints 64 hex characters: $b = New-Object byte[] 32; [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($b); -join ($b | ForEach-Object { $_.ToString('x2') }).

One address can send three wrong bearer tokens without delay. The fourth starts a wait of 2 seconds, and each further wrong token doubles the wait, up to 5 minutes. During the wait the host answers every request from that address with 429 and a Retry-After header. It compares no token during the wait, so a correct token is refused too. A request with no bearer token does not count as a wrong one. The same wait applies on the loopback bind, where every local client is one address. Each token is counted before it is compared, so a burst of parallel requests is counted one by one. A request that is held up only by requests from the same address that are still being compared (a client that sends several requests at once) waits for them, at most 5 seconds, instead of getting 429; if they were right tokens it goes through, and if they were wrong it is held without a comparison. At most four wrong tokens are compared per address before its wait starts, however many requests arrive at once. A correct token gives back only its own attempt. IPv6 addresses are counted by their /64, and every loopback address (127.0.0.0/8, ::1) is one address. One total budget of 60 attempts an hour holds across all addresses that have not presented a correct token during the last hour; an address that did is not held by it, though its own wait still applies. When the total budget holds, the 429 says so: the wrong tokens came from other addresses, and restarting the service clears the hold. The MCP host reads no forwarded headers, so behind a proxy every client is one address. The wait is kept in memory: restarting the service clears it.

allowFrom takes one range or a list. Write a list as one string with commas, for example "10.8.0.0/16,192.168.1.0/24". Each entry must be in CIDR form (use /32 for one address), with each IPv4 address written as four plain decimal numbers (no leading zeros) and no IPv6 zone index, and must match the address family of listen. A :: listen takes IPv6 entries only. IPv4 clients can still reach a :: listener, but the service never admits them there, apart from loopback, which is always allowed. For IPv4 clients, listen on 0.0.0.0 or a specific IPv4 address. The service masks host bits, so 192.168.1.5/24 means 192.168.1.0/24. One bad entry keeps MCP loopback-only.

The wizard accepts a list and writes one comma string. --configure-firewall opens the port for exactly those ranges. web.network.allowFrom follows the same rules. postgres.network.allowFrom still takes one range.

A JSON array of strings also loads, but only on this version or later. An older version refuses to start on an array. It reads a comma string as an invalid range, so that listener stays loopback-only. For that reason the wizard never writes an array.

MCP can serve HTTPS itself (#5288). Without it, the bearer token and every tool result cross the segment in clear text. An exposed MCP server with no tls block logs a warning about that at every start. The tls block has the same settings as web.network.tls. Add it to mcp.network:

"network": {
  "listen": "192.168.1.205",
  "allowFrom": "192.168.1.0/24",
  "encryptedToken": "<output of --encrypt-password>",
  "hostName": "darling.example.com",
  "tls": {
    "pfxPath": "C:\\ProgramData\\PerformanceMonitorDarling\\certs\\mcp.pfx",
    "encryptedPfxPassword": "<output of --encrypt-password>"
    // ...or a PEM pair instead: "certPath" + "keyPath"
  }
}

Give one form, a PKCS#12 bundle, a PEM pair or a Windows certificate store entry, and never more than one. The password can sit in encryptedPfxPassword (DPAPI), in pfxPassword as a file: or env: reference, or nowhere if the bundle has no password. With a specific listen IP, only the network listener serves HTTPS. The two loopback listeners stay plain HTTP, and they still require the token. With 0.0.0.0 or ::, the one listener serves HTTPS to everyone, loopback included. There is no redirect from HTTP and no second port, so a plain-HTTP client fails the handshake.

The service reads the certificate file when MCP starts. After you renew the certificate, restart the service. The product consumes a certificate and does not manage a PKI: there is no ACME and no self-signed fallback. Loading fails closed. A certificate that is missing, unreadable, ambiguous, expired, or not yet valid keeps MCP loopback-only and logs a Critical line. It never falls back to plain HTTP. The token is still required on that loopback listener. Only SYSTEM, Administrators and the service account should be able to read the key file (the PEM key, or a PKCS#12 bundle), for web.network.tls and mcp.network.tls alike, and on Windows the service logs a warning at start that names the file when ordinary users can read it.

The self-alert MCP TLS Certificate Expiring warns for the last 30 days before the certificate expires, and MCP TLS Certificate Renewed resolves it. It is separate from Web TLS Certificate Expiring, so one certificate shared by both endpoints raises two alerts.

Set mcp.network.hostName to the DNS name that clients use, for example darling.example.com. Write the name only, with no scheme, port, path, or wildcard. While MCP is exposed on the LAN, the Host header must name the listen address, localhost, or this name, plus loopback addresses, and any IP address when listen is 0.0.0.0 or ::. The name is admitted only while MCP is exposed. The service refuses every other name with a 400. A value that is not a valid DNS name is ignored, with one warning at start. Clients then connect to https://darling.example.com:5152/, and the certificate must name that host.

What a token-holder can — and cannot — do. Start with the boundary: no MCP tool runs SQL an AI client wrote against your monitored servers. No such tool exists, and a stored custom view cannot become one either — a composed query names only collect.* collector tables in the monitoring store. The only live contact with a monitored SQL Server is analyze_server‘s plan fetch and add_servers‘ one-time connection probe, and both run the product’s own fixed, read-only queries under the same least-privilege monitoring login the collectors use — the ceiling on what they can see is the ceiling you granted that login, and it has no write grants to hit. Everything else answers from the monitoring store.

What the token does gate is the monitor’s own configuration and collected data: the entire read surface, analyze_server, the Custom Views tools (create / modify / delete the saved dashboards and notebooks in config.custom_views), the alert-tuning tools (update_alert_settings / create_mute_rule / update_mute_rule / delete_mute_rule / set_mute_rule_enabled), update_notification_channels (which sets the SMTP password, the webhook URLs and the keys, sealed and never shown back), and the server-onboarding tools (add_servers / remove_server), which edit the monitored-server registry in config.config_monitored_servers — including storing a SQL-auth credential for a server they add. On a managed store and on the compose store, the store-side identity is still the least-privilege mcp role: read, the two analysis-table INSERTs, INSERT/UPDATE/DELETE on the single config.custom_views table (the same narrow write the web composer’s viewer role has), the narrow alert-config writes (config.config_mute_rules CRUD + a single-row config.config_alert_settings UPDATE + a single-column config.config_notification UPDATE for the delivery cooldown, EXECUTE on the config.set_notification_channels function, plus the config_service reload-beacon columns), and the single-table config.config_monitored_servers CRUD. So a token-holder can read everything collected, trigger analysis, author custom views, tune alerting, and onboard/offboard servers — and can never reach the config_command service-credential pivot or a service flag like paused, and can never READ a carved secret column back (the SMTP password, the webhook URLs and keys, and the monitored-server encrypted_password blob). It can WRITE some of them without reading them: onboarding stores a server’s password and update_notification_channels stores the SMTP password, webhook URLs and keys, each sealed and never shown back. Custom-view JSON and alert config carry no secrets. Guard the token like the keys to your monitoring configuration — that is what it opens; your SQL Servers are not behind it. On any other bring-your-own store the MCP server’s store identity is whatever postgres.mcpConnectionString names — the mcp role provision-roles.sql creates holds exactly the grants above — and with that setting unset it is the store OWNER: every limit in this paragraph is then the tools’ own behaviour and none of it is enforced by the store, so a token-holder’s reach is bounded only by what the tools do, not by what the login could (#3914). The service warns at every start while that is the case.

add_servers and update_notification_channels carry credentials in their requests. A SQL-auth password (add_servers), or the SMTP password, webhook URLs and keys (update_notification_channels), ride the request JSON; the service encrypts them at rest (the server password with DPAPI, the channel values sealed) and never returns them, but on the wire it is only as protected as the endpoint — the same plaintext HTTP the token rides unless mcp.network.tls is set. On a segment you do not fully trust, set mcp.network.tls or front the MCP port with a TLS reverse proxy, and prefer Windows/integrated auth for onboarded servers where you can — then no per-server secret crosses the wire at all. With writes on, use TLS or loopback for the MCP endpoint, because the request carries these values.

generate_webhook_signing_key carries a credential in its answer. The new signing key is returned once in the tool’s answer, so the request and the answer need TLS or loopback like any call that carries a credential: on plain HTTP over a network the key is readable by anyone on the path. The tool enforces it: a generate over plain HTTP from a non-loopback address is refused and writes nothing, so set mcp.network.tls before you generate a key from a remote client. A TLS-terminating reverse proxy on the same machine as the service reaches it from loopback and works. Treat the answer like a password (the receiver needs the key; nothing else does).

If your segment is not fully trusted, serve MCP over HTTPS with mcp.network.tls (see above). You can also put a TLS-terminating reverse proxy in front of the MCP port and point clients at that. The in-app CIDR bounds who can route to the port, but it does not protect the wire. Without TLS the bearer token travels in clear text on the segment. An active on-path attacker (ARP spoof, rogue DHCP, compromised switch) can capture and replay it. The store endpoint needs neither: it has verify-full TLS built in.

Output format (GCF). By default the MCP tools return JSON. Setting DARLING_OUTPUT_FORMAT=gcf makes the server return Graph Compact Format instead: the repeated field names of the record arrays these tools return (blocking pairs, wait stats, index bloat, config rows, …) are factored into a single header and the indentation dropped. The saving is payload-shaped: about a quarter across a mixed real workload, more than half on the most uniform tools, and less on text-dominated ones (multi-line query text, plan or deadlock XML) where the field names are a smaller share of the bytes. In the wire a null field is written as - and an absent field (a key some rows omit) as ~. It is opt-in and conservative: applied per result, and only when the GCF wire is both smaller than the JSON and decodes back to it exactly; a result carrying a number GCF cannot represent exactly (a non-integer beyond double precision) stays JSON, as does any result where the wire would be larger, so no result is ever grown, dropped, or garbled. BlackwellSystems.Gcf is a zero-dependency package.

Web endpoint (browser over the LAN)

Add a network block to web (managed mode, or the compose container; web.enabled must be true):

"web": {
  "enabled": true,
  "port": 5153,
  "network": {
    "listen": "192.168.1.205",
    "allowFrom": "192.168.1.0/24",
    "encryptedToken": "<output of --encrypt-password>"
  }
}

When listen is a network address and a token is present and allowFrom is a valid CIDR list, the web host binds that interface behind two gates: an in-app CIDR check on the remote address and an access token. A browser presents the token ONCE through the login form (open http://192.168.1.205:5153/ and paste it); the form POSTs it to /auth/login, the host validates it constant-time, sets an HMAC-signed, HttpOnly, SameSite=Strict session cookie, and 302-redirects to the page you were opening. Subsequent requests ride the cookie. A token in the address (?token=) signs no one in, whatever its value, because an address lands in history, bookmarks, proxy logs and Referer headers: a bookmark or link that carries one opens the login form, and the service log says why. The dashboard takes no bearer header either (that is the MCP endpoint). A script signs in the way the form does, by posting the token to /auth/login and then presenting the session cookie it gets back: curl -c jar -d "token=<token>" http://192.168.1.205:5153/auth/login, then curl -b jar .../api/fleet. A wrong token shows the login form again and keeps the page you were opening, so a right token on the next try lands there. Failed sign-ins are throttled per source address: three wrong tokens go without delay, the fourth starts a wait of 2 seconds, and each further wrong token doubles it, up to 5 minutes. During the wait every attempt from that address answers 429 with Retry-After, right token or wrong, and no token is compared. Each attempt is counted before its token is compared, so attempts that arrive together are counted one by one, and a sign-in that is held up only by attempts from the same address that are still being compared waits for them (at most 5 seconds) instead of being refused. A success gives back only its own attempt: other clients behind the same address keep their count. IPv6 addresses are counted by their /64, and every loopback address (127.0.0.0/8, ::1) is one address. One total budget of 60 attempts an hour holds across all addresses that have not signed in during the last hour; an address that signed in during the last hour is not held by it, though its own wait still applies. When the total budget holds, the 429 says so: the wrong tokens came from other addresses, and restarting the service clears the hold. The wait is kept in memory, so restarting the service clears it. The sign-in POST must come from the dashboard’s own page: a POST whose Origin (or Referer, when there is no Origin) names another host is refused with 403 and does not count. The body is read up to 4 KB whatever its framing, and only as application/x-www-form-urlencoded. The token itself must be at least 16 characters, at least 6 of them different — --configure-network generates 32 random ones — or the service refuses to expose the dashboard at start (Critical line, loopback-only) rather than gate a network on a short one. On loopback a shorter token still signs a browser in, and the dashboard serves reads only until a longer one is set. Loopback is exempt from the CIDR check only — while the dashboard is exposed, a request from the box itself still has to present the token or a valid cookie. It used to pass tokenless on the grounds that the surface was read-only; the Custom Views composer’s create / update / delete and /api/compose/run ended that, so in exposed mode the token is the loopback guard for any local process and sandboxed local sockets (#1649). A dashboard with no token configured does not start unless web.allowTokenlessLoopback is true, which serves local browsers with no token for reads only (a change gets 403 and a message naming the token setting); a token / encryptedToken with no network listen keeps it loopback-only and puts the same token gate on it, and a token that cannot be decrypted stops the dashboard from starting rather than serving it open. An out-of-CIDR request is refused with 403, cookie or no cookie; an in-CIDR request with no credential gets the login form back as a 200, not a 401. The cookie signing key is per-process, so a service restart invalidates open sessions (just re-present the token). Prefer encryptedToken (a DPAPI blob from --encrypt-password); a plaintext token works for dev but is warned. env:NAME and file:PATH references are for the compose and Linux setups. A Windows service uses encryptedToken. Set the same scoped firewall rule for the web port:

New-NetFirewallRule -DisplayName "Darling Web" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 5153 -RemoteAddress 192.168.1.0/24

web.network.allowFrom takes one range or a comma list in the same way as mcp.network.allowFrom (see the MCP section above).

What a web token can reach. On a managed store and on the compose store the web dashboard connects as its own least-privilege web role (on any other bring-your-own store, see the end of this paragraph), and it is read-only over the collected data, with a small, enumerated set of config-plane write routes, each a narrow single-table grant at the store and each refused to a read-only OIDC seat by the host’s method-based write gate: the Custom Views composer (/api/views + /api/compose/run → config.custom_views), the custom alert rules (/api/alerts → config.custom_alert_rules, #3285), and the mute-rule endpoints (/api/mute-rules — create, partial update with explicit-null clears, enable/disable, delete — → config.config_mute_rules, #3450), and alert-history dismiss (/api/alert-history/dismiss → the single dismissed column of config.config_alert_log, through a column-level UPDATE (dismissed) grant, #4843), and server onboarding (POST /api/servers runs the same add_servers core the MCP tool runs — at most 20 servers per request, one add at a time, the password never echoed or logged — through INSERT on config.config_monitored_servers, whose encrypted_password column stays unreadable to the role, #4843); the mute writes run the SAME cores the MCP verbs run, so created_at_utc — the clock the Stale Mute Rules self-alert ages a rule from — never moves through any of them, and every response reports the rule as stored. One operational caveat rides every mute-rule surface: alert rows can spell server_name two ways (the monitor’s own self-alert family uses the display-short name, engine alerts use the registry name), so scope a rule by copying the spelling off the alert rows being muted — a retyped name can leave the rule in force while matching nothing. (The web role holds one further narrow grant — INSERT/UPDATE/DELETE on config.database_state_expected, for the Viewer’s per-database state-override editor (#1986) — which no web route reaches; the WPF Viewer’s own surfaces gate on a has_table_privilege read-only probe against the alert-dismiss write, which a viewer-role seat fails, so a locked-down Viewer shows Seat: read-only.) So a token-holder can read everything collected, author saved views and alert rules, and tune the mute rules. Whatever web.allowAdminWrites says, an edit seat (the shared token, or an OIDC admin) can ask the service to read a monitored server on demand: POST /api/collectors/run, POST /api/active-queries/live and POST /api/analyze-now, within the per-server limits. It can also add or edit a monitored server with POST /api/servers and PATCH /api/servers/{id}. Both refuse a Windows-authentication server over an unverified certificate (trust_server_certificate true, or encrypt_mode Optional) unless web.allowWindowsAuthOverUnverifiedTls is on (default off). An edit is judged only when it changes the machine the entry names or its sign-in and certificate settings: the host, the port, the auth type, trust_server_certificate, encrypt_mode or the Query Store replica. With web.allowAdminWrites on, an edit seat also makes the dashboard’s Admin writes on the managed store through the managed admin login. Those are routes and environment profiles, threshold overrides, report feedback, server-action switches (which let the service act on a monitored server), note decisions, undoing an agent change, the agent switch, closing a request, writing a note, practice requests, and case export. A new install writes that setting on. A darling.json without the key, such as one carried over from 3.11, keeps it off. Then the dashboard stays list-only for those Admin writes. These routes are why an exposed dashboard authenticates loopback too, exactly as MCP does. On any other bring-your-own store the dashboard connects as whatever postgres.webConnectionString names — the web role provision-roles.sql creates holds exactly these grants, secret-column carve and statement_timeout included — and with that setting unset it connects as the store OWNER: the routes above still bound what a token-holder can ask for, but the store no longer enforces any of it — no carve, no narrow write grants, no backstop on a runaway composed query (#3914). The service warns at every start while that is the case.

The web dashboard can serve HTTPS itself (#2562). Without it the token and the session cookie it mints travel cleartext on the segment, and the in-app CIDR bounds who can route to the port without protecting the wire — so an exposed dashboard with no tls block warns about exactly that at every start. Add a certificate to web.network:

"network": {
  "listen": "192.168.1.205",
  "allowFrom": "192.168.1.0/24",
  "encryptedToken": "<output of --encrypt-password>",
  "tls": {
    "pfxPath": "C:\\ProgramData\\PerformanceMonitorDarling\\certs\\dashboard.pfx",
    "encryptedPfxPassword": "<output of --encrypt-password>"
    // ...or a PEM pair instead: "certPath" + "keyPath" (what the compose distribution mounts)
  }
}

Give one form, never more than one: a PKCS#12 bundle, a PEM pair or a Windows certificate store entry. The password may sit in encryptedPfxPassword (DPAPI), in pfxPassword as a file:/env: reference, or nowhere at all if the bundle is unprotected. TLS applies to the network listener only: the loopback listeners stay plain HTTP, because your certificate names the LAN address and not localhost, and loopback traffic never reaches the segment this protects. There is no redirect-from-HTTP, because one port cannot speak both schemes and adding a second HTTP port would reopen the cleartext surface; a plain-HTTP client simply fails the handshake.

The product consumes a certificate and does not manage a PKI — no ACME, and deliberately no self-signed fallback, which would buy encryption without authentication and train you to click through the warning. An internal CA is the normal answer on a LAN. Loading fails closed: a certificate that is missing, unreadable, ambiguous, or expired keeps the dashboard loopback-only (the token is still required on that loopback listener) with a Critical log line rather than quietly serving the LAN over HTTP — and because an expired certificate takes the dashboard down, the service warns for the last 30 days before that happens. The listener negotiates TLS 1.2 and 1.3 only. A TLS-terminating reverse proxy in front of the port remains a perfectly good alternative. MCP has its own tls block, described in the MCP section above.

Behind a reverse proxy, list the proxy in trustedProxies. The connection from the proxy to this host is plain HTTP, so without it the session cookie is not marked Secure and an OIDC redirect_uri is built as http:// (which an IdP refuses). With "trustedProxies": ["10.0.0.5"] (IPs or CIDRs) the host honors X-Forwarded-Proto, X-Forwarded-For and X-Forwarded-Host from those addresses only — from anyone else the headers are ignored. Two consequences: allowFrom is then checked against the forwarded client address, so it has to cover your operators rather than the proxy; and the sign-in throttle counts per client instead of per proxy. Set web.publicBaseUrl to the name the proxy serves so the Host allowlist admits it. Set it too when the proxy rewrites the Host header (nginx’s proxy_pass does by default): a sign-in POST from a browser that does not send Sec-Fetch-Site is accepted only when its Origin or Referer names the host the request was addressed to, the X-Forwarded-Host a trusted proxy sent, or web.publicBaseUrl‘s host (Unicode and punycode spellings of a name are the same name). A browser that sends Sec-Fetch-Site: same-origin needs none of that. Behind a proxy that rewrites Host, the service cannot tell a browser on the LAN from one on this machine without one of those two settings: every upstream request carries the proxy’s own address, so the Cross-Origin-Opener-Policy header, and anything else that reads the request’s host, follows that address until either trustedProxies names the proxy and the proxy sends X-Forwarded-Host and X-Forwarded-Proto (which are what that header and HSTS read), or web.publicBaseUrl names the origin browsers use. With web.publicBaseUrl set, the opener policy is sent only when that origin is https or loopback and the request’s own origin is too. An entry that does not parse keeps the dashboard loopback-only with a Critical line. Strict-Transport-Security is off by default. Set "hsts": true in the network block, once the dashboard is reached over HTTPS only, and responses to a request that came over HTTPS (the listener’s own, or a trusted proxy’s) carry it (one year, no subdomains). HSTS is kept per host name and ignores the port: once a browser has reached the dashboard over HTTPS by name, it uses HTTPS for every port of that same name for a year, including other services on that name that speak plain HTTP. The proxy must append the client’s address to X-Forwarded-For or overwrite it, and trustedProxies must not cover clients that connect directly. Only the address of the connection itself can be loopback for allowFrom: a forwarded 127.0.0.1 or ::1 is judged against allowFrom like any other address.

Certificate from the Windows certificate store

A certificate enrolled from an internal CA usually sits in the Windows certificate store. Its key often cannot be exported, so you cannot make a PFX or a PEM file from it. For web.network.tls and mcp.network.tls alike, a third form reads the certificate from the store (#7718). It works on Windows only. On any other host the service refuses it and says to use pfxPath or certPath and keyPath.

"tls": {
  "store": {
    "location": "LocalMachine",       // the default, or "CurrentUser"
    "name": "My",                      // the default (Personal)
    "thumbprint": "A1 B2 C3 D4 ..."    // or "subject": "darling.example.com"
  }
}

Give exactly one form: store, a PKCS#12 bundle or a PEM pair. A store block next to pfxPath, certPath or keyPath is refused, and so is one with both thumbprint and subject or with neither. LocalMachine is what almost every install wants, because a service account with no loaded profile has no useful CurrentUser store. The service opens the store read-only and never changes it.

  • thumbprint names one exact certificate. Spaces and case do not matter, so you can paste it from the certificate snap-in. A thumbprint that matches nothing, or matches two certificates, is refused, and so is a certificate with no private key. The certificate’s dates are judged by the same check the file forms use, so an expired one is refused and still raises the expiry alert.
  • subject is a DNS name. The service serves the newest certificate, by start date, that meets four rules. It is valid now. It has the Server Authentication usage. It has a private key. It lists the name as a DNS name in its Subject Alternative Name. A wildcard name such as *.example.com counts for one label. The common name never counts. When nothing qualifies, the Critical line says how many certificates carried the name and why each was skipped. A certificate in the store whose Subject Alternative Name cannot be read is skipped as if it did not carry the name, and the refusal counts it. One damaged certificate in a shared store does not stop the service from finding yours. When the newest qualifying certificate’s private key cannot be opened by the service account, the service tries the next newest, and serves the first whose key opens. See “When the newest certificate’s key cannot be opened” below. A thumbprint never falls back.

Give the service account Read on the key

The service runs as NT SERVICE\PerformanceMonitor Darling unless you moved it to another account. A machine key is usually readable by SYSTEM and Administrators only. You must grant Read to the service account once for each certificate. Do it again after a renewal that makes a new key. There are two ways.

  • In certlm.msc (certmgr.msc for CurrentUser), open the certificate. Choose All Tasks, then Manage Private Keys, and add the service account with Read.
  • From an elevated prompt, run the command below.
PerformanceMonitor.Darling.Service.exe --grant-cert-key-access <thumbprint> [--account <name>] [--store-location LocalMachine|CurrentUser] [--store-name <name>]

The command follows these rules:

  • It grants Read only, to one account. That account is the one the service is registered under, or the one --account names.
  • It grants to one account and refuses every group except the local Administrators group, by asking Windows what the account is. That covers Everyone, Users, Authenticated Users, SERVICE, ALL SERVICES, LOCAL, Domain Users, Domain Computers and every other group. It accepts a user (a domain user, a local user, a group managed service account) and these service identities: LocalSystem, LocalService, NetworkService, a per-service virtual account (NT SERVICE\<name>, only when a service with that name is registered on this machine, so a mistyped name is refused), an IIS application pool identity and the local Administrators group. When it cannot tell what the account is, it refuses.
  • It refuses an empty --account, and a --store-name with a backslash or a slash in it. The same store name in darling.json fails closed with a Critical line, because a name like \\host\My would open another machine’s store over remote registry as the service account.
  • It adds one entry to the key’s access list and keeps every existing entry. It never replaces the list.
  • For a LocalMachine certificate it needs an elevated prompt. Without one it says so and changes nothing.
  • It finds the certificate by thumbprint. It refuses when none or two match, and when the certificate has no private key.
  • If the account already has Read, it says Already granted and changes nothing.
  • If an explicit Deny entry on the account covers Read, it stops and tells you to remove the Deny first.
  • When it succeeds, it names the account and the certificate’s subject and thumbprint. It tells you to restart the service.
  • It works on CNG keys and on legacy CAPI RSA keys. It does not handle a key on a smart card or a hardware module.
  • --store-location CurrentUser grants on the key of a certificate in the store of the account that runs the command, which is the elevated operator. A service that runs under its own account reads that account’s CurrentUser store, never the operator’s, so the grant does nothing for it. Use CurrentUser only when the service runs as the same account that runs the command, for example a service you moved to your own account. Every other install wants the default, LocalMachine.

When the newest certificate’s key cannot be opened

A renewal usually brings a new key, and the service account has Read on the old key only. With subject, the service does not go loopback-only for that when the older certificate is still in the store and listed. It serves the next newest certificate that meets the same four rules and whose key it can open, and logs one Warning. The Warning names the newer certificate (thumbprint, subject and start date), says the service serves the older one until it expires, and gives the --grant-cert-key-access command for the newer one. Run that command and restart the service before the older certificate expires.

  • The service serves the older certificate only for as long as the newer key is out of reach. Restart after the grant and it picks the newest again.
  • The expiry alerts read the certificate that is served, so they warn before the older one expires.
  • When no matching certificate’s key opens, nothing changes: the endpoint goes loopback-only and the Critical line names the newest certificate.
  • A thumbprint is an exact pin. Its key failure never falls back to another certificate.
  • The service reads the store without archived certificates, as a certificate marked archived is one Windows treats as retired. The fallback covers an older certificate that is still in the store and not archived, for example one you imported by hand, or a client that keeps the previous certificate. Windows can mark the certificate a renewal replaces as archived, and an archived certificate is not listed, so it is not a fallback. When an Active Directory autoenrollment renewal archives the old certificate, the service behaves as before: the endpoint goes loopback-only and the Critical line names the newest certificate until you run the grant command.
  • If you replaced a certificate because its key was exposed, delete the old one from the store or pin the new one by thumbprint. Otherwise the fallback serves the old certificate until you grant the new key.
  • A certificate whose Subject Alternative Name cannot be read is skipped. When the service serves another certificate in that case, the same Warning says how many were skipped.

Renewal needs a restart

The service reads the certificate once, when it starts. After you renew, restart the service. There is no reload.

  • With subject, the service then picks up the newest valid certificate by itself.
  • With thumbprint, you must also put the new thumbprint in darling.json, because a renewal changes it.
  • If the renewal brings a new key, grant the key access to the new certificate first.

The expiry alert catches a restart that you forget. Web TLS Certificate Expiring and MCP TLS Certificate Expiring read the certificate that the service loaded. They keep warning while the old certificate runs toward its end date.

What fails closed

Each of these keeps the endpoint loopback-only and logs one Critical line. None of them falls back to plain HTTP.

  • The store cannot be opened, for example because name has a typo.
  • No certificate matches.
  • Two certificates share the thumbprint.
  • The certificate has no private key.
  • The certificate is expired or not valid yet.
  • The private key cannot be opened. With subject, this is only when no matching certificate’s key opens.

For the last one, the line names the service account and the fix. The fix is the certlm.msc steps above, or the --grant-cert-key-access command with the account filled in.

The --configure-network status line reads TLS: on (certificate store, LocalMachine\My, <thumbprint>). When you chose subject, it reads newest valid for <name> in place of the thumbprint. The line reads darling.json and does not open the store, so it never names the certificate that is actually served. After a fallback, the service log has the Warning that names it.

Front door to store connections

A front door (see The front door) opens its own connections to each store it fronts. It is a client of the store’s MCP endpoint and of the store’s web dashboard, so the rules above apply to the store as they apply to any other client.

  • On each store, the MCP and web allowFrom lists must include the front door’s address, and the firewall rule for each port must cover it.
  • The front door sends the host of mcpUrl and webUrl as the Host header. The store must accept that name. For MCP, use the listen address, localhost or mcp.network.hostName. For the web dashboard, use the listen address, localhost or the host of web.publicBaseUrl.
  • When a store serves https with a certificate from an internal authority, the system’s trust decides. For a self-signed certificate, set certificateSha256 for that store in the front door’s frontDoor block. The front door then accepts only that exact certificate.
  • A plain http address to a host that is not the front door’s own machine works. The front door logs one warning for it, because the store’s token crosses the network in clear text.
  • The front door follows no redirects.

The health port

The health port is for Kubernetes and other orchestrators (#8184). It is off by default. Turn it on with a health block in darling.json, and restart the service. See health for the three settings (enabled, port 5154 and listen).

"health": { "enabled": true }

With listen empty, the port binds 0.0.0.0 inside a container and 127.0.0.1 everywhere else. 0.0.0.0 is IPv4 only: on an IPv6 single-stack cluster, set listen to ::. The port serves two routes, one word each:

Route HTTP Body When
GET /livez 200 ok, starting, degraded or stopped Always. The word is the current state. A stopped service is still alive.
GET /readyz 200 ok The collection loop is running.
GET /readyz 503 starting The service has not reached a verdict yet.
GET /readyz 503 degraded A startup step failed and the service retries it.
GET /readyz 503 stopped A startup step failed for good, or the configuration has problems.

The body is text/plain; charset=utf-8 and holds only that word. The words are the status values of /api/ping. A front door (see The front door) runs no collector, so its /readyz answers what its /api/ping answers: 503 stopped when its own darling.json was refused, 503 degraded when every store is unusable, and 200 ok otherwise. Its /livez is still 200.

The routes are matched the way ASP.NET Core routing matches every route: case-insensitively, with a trailing slash and a query string ignored, after percent-decoding and after .. segments are resolved. So /LIVEZ, /livez/, /livez?x=1 and /%6civez answer the same as /livez, and /livez/../readyz answers as /readyz. Any other path gets a 404 with an empty body. Any method other than GET on the two routes gets a 405 with an empty body.

What the port never returns

No server name, no database name, no step name, no failure detail, no attempt count, no version, no metric and no store content. There is no JSON, no cookie, no Server header, and no header beyond the few Kestrel always adds (such as Date).

The listener is tight because it has no token and, in a container, listens on every interface: HTTP/1 only (a kubelet probe is an HTTP/1.1 GET), no Server header, at most 64 connections, a 15 second keep-alive, a 10 second limit to send the request headers, 8 KB of headers and no request body. When the port binds an address that is not loopback, the service logs one Warning that names why: health.listen when it is set, or DOTNET_RUNNING_IN_CONTAINER when listen is empty and the container default applied.

Why it has no token and no allowFrom

A kubelet cannot hold a secret, and probes come from the node, not from a client you can list. So the port does not use the token gate, allowFrom, TLS or the bind ladder that the MCP and web endpoints use. The answer is one word that says whether the service is up and collecting, and nothing else. Keep the port off the networks you do not trust: in Kubernetes it is reachable by pods in the cluster unless a network policy blocks it, and the Dockerfile does not EXPOSE it.

It starts before migrations

The listener starts before the worker, so before the store migrations and before any ownership check. A long migration answers /livez 200 and /readyz 503 starting, so a startup probe on /livez never kills it. A start that is refused (for example, a configuration with problems) answers /livez 200 and /readyz 503 stopped.

What the port cannot cover

The listener reads only its own health block, frontDoor.enabled, web.port and mcp.port, and resolves no env: or file: reference. So a configuration with problems, or a store connection string whose secret cannot be resolved, still opens the port, and /readyz answers what the service is doing about it (degraded while it retries, stopped once it gives up).

One case is left: a darling.json that cannot be read or parsed at all (missing, empty, unreadable, access-denied or not valid JSON). The listener cannot know its own block, so the port stays off and the service logs one Error line that says why. The listener does not retry, so the port stays off for the life of that process. Restart the service after you fix the file.

When the port does not open

Two more cases leave the port off. In both, collection keeps running:

  • A bad health block. A port outside 1 to 65535, a port equal to web.port or mcp.port, or a listen that is not an IP address. The service logs one Critical line that names the setting. It is not a configuration problem, so it never stops collection.
  • A bind failure. The port is taken by another process, or health.listen is an IP address that is not on this machine. The service logs one Error line that names the address and port.

Kubernetes probes

startupProbe:
  httpGet: { path: /livez, port: 5154 }
  periodSeconds: 5
  failureThreshold: 60
livenessProbe:
  httpGet: { path: /livez, port: 5154 }
  periodSeconds: 10
readinessProbe:
  httpGet: { path: /readyz, port: 5154 }
  periodSeconds: 10

Never use /readyz for liveness. A service that stopped on a configuration problem answers /readyz 503 stopped until someone fixes the file. A liveness probe on it would restart the pod in a loop, and the restart cannot fix the file.