¶ The user sees "reachable only through a tunnel agent"
The session is refused with this message:
This target is reachable only through a tunnel agent, which is currently offline. Contact your administrator.The target has a tunnel agent and that agent is not connected.
The access events show the reason Tunnel agent offline with the subject Tunnel agent <id>.
Check in this order:
- On the server, the service Artica RDS tunnel agent is running (
sc query ArticaRDPTunnelAgent).
On Linux, the agent process or its unit is running. - The server reaches the appliance on the port of the receiver.
In PowerShell:Test-NetConnection <appliance> -Port 4443. - The Status tab shows the receiver Running.
- The source address of the site is in Allowed sources, and the firewall in front of the appliance lets it through.
- The agent is not revoked and its certificate has not expired.
Check the Agents tab. - The identifier in the target is exactly the identifier of the agent.
A typo gives the state No certificate.
¶ The session opens then fails at once
The agent is connected but cannot reach its forward address.
It closes the session and the user gets the usual target error of the RDS Proxy.
- Check that Remote Desktop is enabled on the server, or that the VNC server listens.
The default127.0.0.1:3389needs Remote Desktop listening on the loopback, which is the Windows default. - Check the
forwardvalue ofagent.json.
If the agent already has 32 open sessions, further sessions are closed at once.
¶ Enrollment errors
| Message of the agent | Cause and fix |
|---|---|
the receiver refused the enrollment (token expired, already used or deleted? create a new one in the console) |
The code expired, was already used, was cancelled or was replaced by a newer code. Create a new code for the same identifier. After 5 failures from the same address within 10 minutes, the receiver refuses further attempts until the window ends. |
connect to the receiver ... |
The server cannot reach the address written in the code. Use -server <address>:<port> when the name does not resolve or the site goes through a NAT. |
receiver CA does not match the fingerprint of the enrollment string |
Something answered on that address that is not this appliance. Check the address, and any TLS inspection device on the way. |
receiver certificate not valid for <name> under the expected CA |
The receiver certificate does not carry the name written in the code. This happens when the names of the appliance changed after the code was created. Create a new code. |
this machine is already enrolled (... exists); use -force to enroll it again and replace that key |
The server already has an agent key. Add -force to replace it. |
this command must be run from an elevated (Run as administrator) prompt |
On Windows, enrollment and service commands need an elevated prompt. |
¶ service install is refused
Without the MSI, service install refuses an executable that ordinary users can modify.
The message ends with ordinary users could replace the program the service runs.
Copy (not move) the executable into %ProgramW6432%\Artica\RDPTunnelAgent and run the command from there, or install the MSI.
You can also give the folder back to the Administrators with icacls <folder> /setowner *S-1-5-32-544 /T and remove the other write permissions.
¶ A folder was moved aside
The service and the enrollment never reuse a configuration folder they cannot trust.
This happens with inherited permissions, a foreign owner or an unexpected file.
The folder is renamed <name>.untrusted-<timestamp> and restricted to SYSTEM and the Administrators.
A new, empty folder is created and a new enrollment is needed.
Event 41 of the Application log names the folder.
Check its contents, then delete it.
¶ MSI exit code 3010
Code 3010 means a reboot is needed to finish.
Another program held the executable open, for example an antivirus scan or service status still running.
Windows Installer replaces the file at the next reboot.
Until that reboot, the service keeps running the previous version.
Restart the server at a convenient time.
A deployment tool must report 3010 as "reboot planned", not as a plain success.
¶ Interrupted uninstall or failed upgrade
- If an uninstall fails after the service was removed, the files stay and the service is gone.
Runmsiexec /i <same file>.msi /qn /norestartagain to recreate it. - If an upgrade fails, the machine can be left without the agent.
The configuration in%ProgramData%is kept: reinstall the MSI, no new enrollment is needed.
The cause is in%ProgramData%\Artica\rdptunnel-agent\msi-actions.logand in the/l*vlog of msiexec.
¶ Windows events
The service writes to the Application log, source ArticaRDPTunnelAgent.
The enrollment code and the key are never written there.
| Event | Level | Meaning |
|---|---|---|
| 1 | Information | Service started, with its version |
| 2 | Information | Service stopped |
| 10 | Information | Connected to the appliance |
| 11 | Warning | Disconnected, with the reason |
| 12 | Warning | Cannot connect to the appliance (at most once an hour) |
| 13 | Error | TLS handshake refused by the appliance (at most once an hour) |
| 20 | Warning | Not enrolled yet (at most once an hour) |
| 21 | Error | Configuration invalid (at most once an hour) |
| 30 | Warning | Cannot reach the forward address (at most once an hour) |
| 31 | Warning | Too many sessions at once (at most once an hour) |
| 40 | Warning | Service warning |
| 41 | Warning | Configuration folder moved aside |
¶ Receiver log on the appliance
The receiver runs as the unit artica-rdptunnel.service.
Read its log with:
journalctl -u artica-rdptunnel --no-pager -n 100Typical lines:
artica-rdptunnel-server 0.3.0 starting, listening on :4443
enrollment token created for agent "srv-erp", expires 2026-11-01T02:03:48Z
agent "srv-erp" enrolled from 192.168.1.142:62864, certificate serial 85bf96c5fb0a167d08a377a4dba218e9
agent "srv-erp" connected from 192.168.1.142:62870
agent "srv-erp" from 192.168.1.142:62870 disconnected: EOFThe precise reason of a refused enrollment is written here, never sent to the agent.
¶ Files of the receiver
| Path | Content |
|---|---|
/etc/artica-postfix/rdptunnel/server.json |
Port and certificate names, written by Artica |
/etc/artica-postfix/rdptunnel/ca.crt, ca.key |
Certification authority of the agents |
/etc/artica-postfix/rdptunnel/revoked.txt |
Revoked certificate serial numbers |
/etc/artica-postfix/rdptunnel/issued/ |
One record per issued certificate, without any key |
/run/rdpproxy/tunnel/<id>.sock |
Local socket of a connected agent, used by the RDS Proxy |
A migration of the appliance carries /etc/artica-postfix, the certification authority included.
The agents stay valid on the new appliance as long as they reach it under a name of its certificate.
¶ SIEM events
When the SIEM of the RDS Proxy is configured, the receiver sends its own events on the same channel.
The user name is agent:<id> and the client address is the address of the agent.
| Event | When |
|---|---|
tunnel_agent_connect |
An agent connects |
tunnel_agent_disconnect |
An agent disconnects, with the reason and the duration |
tunnel_agent_refused |
A connection is refused: revoked, unknown_ca, bad_id or handshake |
tunnel_agent_enrolled |
An agent is enrolled |
tunnel_agent_revoked |
An agent is revoked |