Anping 中文

Getting access and deploying

To use Anping from your app, you need a running Anping server: its address, a secret key for your app (API key) and at least one computer setup (model). This page shows how Anping runs today.

Still being built: ready-made packages for production (a production image of the desktop engine, setup templates) and one service spread over several regions.

What you need from the operator

WhatDetails
AddressSuch as https://anping.example.com.
API keyOne of the keys in Oturl:ApiKeys. Keep it on your server, never in a web page.
Model idsThe name of each computer setup (Targets:N:Id). Upper and lower case must match.
To show Anping inside your pageYour site's address in Oturl:FrameAncestors.

Then the Quick start.

What runs

The browser reaches your load balancer, which passes the secure connection to the Anping server; Anping and its desktop engine (guacd) run together in one copy with shared file storage and log storage, and the engine connects to Windows. Browser over https Load balancer handles https (TLS) One copy of Anping (replica: pod or task) Log storage, Anping only: ConnectionLog:Path Anping server port 8080, user 1654 Desktop engine guacd, port 4822 inside only File storage, same folder in both: Files:DriveRoot health checks: /healthz, /readyz Windows port 3389 Hyper-V 2179 https http RDP The browser reaches your load balancer, which passes the secure connection to the Anping server; Anping and its desktop engine (guacd) run together in one copy with shared file storage and log storage, and the engine connects to Windows. Browser over https https Load balancer handles https (TLS) http One copy of Anping (replica: pod or task) Anping server port 8080, user 1654 Desktop engine guacd, port 4822 inside only File storage, same folder in both Files:DriveRoot Log storage, Anping only ConnectionLog:Path health checks: /healthz, /readyz RDP Windows port 3389 Hyper-V 2179
Only the load balancer faces the internet. The desktop engine (guacd) and its port stay inside.
PartWhat it does
Anping serverBuilt from src/Gateway/Dockerfile (.NET 10). It serves the link page, the API, the connection log and the live desktop connection.
Technical detailIt serves /oturl.html, /ws/oturl/get, /log.html and /ws/log, and the WebSocket /tunnel. Plain http on port 8080, user id 1654, with tini as its first process so a crash ends the container instead of leaving it hanging.
Desktop engine (guacd)Apache Guacamole 1.6.0. It talks to Windows (over RDP, Microsoft's remote desktop protocol). It has no password of its own: never make its port public.
Technical detailIt runs as a sidecar in the same replica (pod or task) as the Anping server, which reaches it at Guacd:Host and Guacd:Port (localhost:4822).
File storage (drive volume)The folder for the users' shared folders, Files:DriveRoot, mounted in both. Size it as Files:DriveQuotaBytes (1 GB) times the sessions per copy.
Technical detailMounted at the same path in both containers, owned by user id 1654. Each session gets its own folder there, deleted when the session ends. Without it there is no file transfer. Automatic download of files saved outside the drive's Download folder needs the Anping server on Linux: it watches this volume with inotify. All sessions share the kernel's inotify limits (fs.inotify.max_user_watches); past them the Anping server logs a warning and those folders do not download by themselves.
Log storage (log volume)The folder for the connection log, ConnectionLog:Path, used only by the Anping server.
Technical detailOwned by user id 1654. Without it the connection log is in memory and a restart loses it.
Load balancer (TLS proxy)Your load balancer or ingress. It handles https and lets the live connections (WebSockets) through.

Steps

StepDo
1 Build the imagesdocker build -f src/Gateway/Dockerfile . for Anping; for the desktop engine use guacamole/guacd:1.6.0.
Technical detailRun the build from the repository root. The development stack runs the official guacd image as user 1654 with HOME=/tmp; an engine image built for production is coming. Printing is off by default. To turn it on, set Guacd:Printing to true; it needs a guacd image with Ghostscript (the official one has it), which is AGPL-3 or a commercial license from Artifex.
2 NetworkAnping must reach each Windows computer on port 3389 (Hyper-V: 2179). Keep 3389 closed to the internet.
Technical detailguacd's port stays inside the replica.
3 HttpsPut a load balancer with a valid certificate in front, with WebSockets allowed. Set ForwardedHeaders:KnownNetworks to its network and AllowedHosts to your public name.
Technical detailWithout a proxy (browsers connect directly), set ForwardedHeaders:NoProxy=true instead. Have the proxy drop query strings from its logs for /ws/oturl/get, /ws/log and /oturl.html.
4 SettingsKeys from a secret store (make one with openssl rand -hex 32), one Targets:N per computer setup, and both storage folders (all settings).
Technical detailEach key at least 32 random characters. Files:DriveRoot and ConnectionLog:Path. Oturl:AllowedComputers and Oturl:ComputerSettings if your program sends computer; Oturl:FrameAncestors for embedding. Leave Dev:Pages off (the default). As appsettings.json or environment variables.
5 LicensePut the license file you got with Anping in a folder on the host and mount it read-only at /etc/anping/license. Without one, Anping runs as a trial: 2 sessions at once (license).
6 Computer certificatesEach Windows computer must prove who it is: pin its certificate, or give it one the engine trusts. Others are refused (certificates).
7 WindowsFor users' own time zones, turn on Allow time zone redirection (below).
8 Health checksTwo checks for your platform: /healthz (is Anping running?) and /readyz (can it reach the desktop engine?). Check about every 30 seconds.
Technical detail/healthz answers 200 while the Anping server process runs. /readyz answers 200 when guacd completes an RDP handshake, otherwise 503. Each /readyz check makes guacd start a process, so the result is cached for 10 seconds.
9 CheckAnping runs in production mode by default and won't start with unsafe settings; its log says which. Then make a link (Quick start).
Technical detailRefused: the dev API key, a key shorter than 32 characters, dev pages, a missing proxy setting or an invalid setting.
Example as environment variables 
AllowedHosts=anping.example.com
ForwardedHeaders__KnownNetworks__0=10.0.0.0/24
Guacd__Host=localhost
Guacd__Port=4822
Files__DriveRoot=/drives
ConnectionLog__Path=/connection-log
Oturl__ApiKeys__0=<from your secret store>
Targets__0__Id=sales-desktop
Targets__0__Name=Sales
Targets__0__Host=sales-rdp.corp.example
Targets__0__CertFingerprints__0=sha256:<the computer's fingerprint>

License

Anping checks its license on the Anping server itself, offline: at startup and at every new session. It never contacts anyone, and a license problem never stops it.

License over time: licensed through its expiry date, then 14 days of grace with a warning, then new sessions are refused while open ones keep running. No license: a trial of 2 sessions at once. +14 days installed expiry date (UTC) Licensed its sessions at once Grace all works, /log.html warns New sessions refused open ones keep running No license, or one that is not valid: a trial, 2 sessions at once, no end date. License over time: licensed through its expiry date, then 14 days of grace with a warning, then new sessions are refused while open ones keep running. No license: a trial of 2 sessions at once. +14 days installed expiry date (UTC) Licensed its sessions at once Grace all works, /log.html warns New sessions refused open ones keep running No license, or one that is not valid: a trial, 2 sessions at once, no end date.
Dates are UTC days.
TopicWhat happens
InstallPut anping.license in a folder on the host and mount that folder read-only at /etc/anping/license.
Technical detailFor example -v /opt/anping/license:/etc/anping/license:ro. The file must be readable by user 1654. Instead of a file you can set License__Content to the file's content (one environment variable, for example from a secret store); it wins over the file. License:Path moves the file.
RenewReplace the file with the new one. It counts from the next new session: no restart, and open sessions stay.
Technical detailCopy the new file into the folder under another name, then rename it over the old one, so Anping never reads half a file. With License__Content, restart Anping.
SessionsThe license's number is sessions at once on this Anping server, whoever opens them. Over it, a new session is refused with All 100 licensed sessions are in use.
Technical detailA reload or reconnect of a link that is open replaces its session, so it needs no free place. Tunnel:MaxSessions applies too: the smaller one counts. Each refusal is in the connection log as license_limit.
Expiry and graceValid through its date (UTC). Then 14 days of grace: everything works and /log.html warns. After that new sessions are refused (The remote desktop service's license has expired.); open ones keep running.
Technical detailThe connection log says license_expired. After the grace period a reconnect is a new session too, so it is refused.
No license (trial)Anping starts and runs at most 2 sessions at once. /log.html says Unlicensed.
A damaged or changed fileAnping logs why, runs as a trial (2 sessions at once) and /log.html says why.
Technical detailThe file has two comment lines for people and one signed line. A changed line, a license signed by a key Anping does not know, or an unreadable file all count as no license.
Where to see itThe top of /log.html: the state in words, the customer, the expiry date and sessions in use out of the licensed number.
Technical detailThe API: GET|POST /ws/license with the API key (API reference). Anping's log says the state at startup and whenever it changes.

Windows computers

TopicWhat happens
Time zoneUsers see their own time zone if the Windows policy Allow time zone redirection is on, or one fixed zone per model (TimeZone, models).
Technical detailThe page sends the browser's time zone with each connection. A model's TimeZone sets one zone for all its sessions instead. The policy is a Remote Desktop Session Host policy under Device and Resource Redirection. Without it the session keeps the computer's own time zone.
What Windows getsYour time difference from world time (UTC) at the moment you connect (Client Local Time), without summer time rules.
MoreA session that runs across a clock change keeps the old offset until it connects again.
Computer name Windows seesAnping- plus 8 characters of the link's code, so you can find the session in the log.
Technical detailThe first 8 characters, seen as %CLIENTNAME% and in Task Manager. A model's ClientName sets another name.
Signing outWindows keeps you signed in (disconnected) after Disconnect and End, until its own time limits sign you out.
Checked on WindowsOn Windows Server 2025 the computer name works. The time zone is sent, but Windows keeps world time (UTC) even with the policy on; the cause is still open. Windows' own touch support (Touch) is not tried yet.

Limits today

LimitWhat to do
Links are kept in one server's memoryA link opens only on the Anping server that made it; restarting that server ends every session.
MoreA restart forgets every link and ends every live session; users then need a new link.
Several Anping serversGive each its own address, and ask the server whose address you hand out.
MoreFor example one per region. Several replicas behind one address need a shared link store, which is planned.
Updating or removing a copyUpdating or removing a copy (redeploy, scale-in) ends its sessions: run a fixed number of copies (replicas).
CapacitySet Tunnel:MaxSessions (100) to the sessions the copy's machine holds: about 18 on 4 vCPU / 8 GiB, 37 on 8 vCPU / 16 GiB. A full copy then answers busy instead of slowing everyone.
MoreBudget 0.15 vCPU and 170 MiB a session at 1920x1080 for office work, measured on a Mac with a Linux test desktop. Screens that change all the time (3D views, animation) need more: measure one session with your own software first.
Certificates from your own company authorityThey need Anping's own engine image, which is coming; until then, pin (certificates).

Try it on your computer

scripts/dev.sh up (needs the repository and Docker) starts Anping, its desktop engine and a Linux test desktop at http://localhost:8080. Key anping-dev-oturl-key, model dev-linux.

For development only: it runs in development mode, trusts the test desktop's own certificate (pinned) and turns on test pages.