Connector agents

Admin, Connector agents (/admin/agents).

Some of the systems a service desk needs live inside a school network and are not reachable from the internet: Active Directory, a Synergetic SQL Server, PaperCut, Web Help Desk, a printer answering SNMP.

A self-hosted install sitting on that network reaches them directly and needs nothing on this page.

A managed deployment cannot, so it uses an agent.

The shape of it

The agent dials out and is never dialled into. There is no inbound firewall rule to request, no port forward, no VPN tunnel to maintain.

Everything is pull-shaped: the platform queues work, the agent collects it, performs it inside your network, and returns the result.

   your network                         the platform
+-----------------+                +--------------------+
|  Active         |                |                    |
|  Directory  <---+----+           |   work queued      |
|  Synergetic <---+--+ |           |        |           |
|  PaperCut   <---+-+| |           |        v           |
|  printers   <---+ ||| |          |   +----------+     |
|                 | |||            |   |          |     |
|    +------------+-+++--- outbound HTTPS ------> |     |
|    |  agent     |            (long poll)  |     |     |
|    +------------+                         +----+      |
+-----------------+                +--------------------+

That is usually the difference between a two week change request and an afternoon.

Installing one

1. Admin, Connector agents, Add agent. Give it a name that says where it is, such as “Junior campus server room”.
2. Optionally attach it to a site, if you run more than one campus.
3. Copy the enrolment token. It is shown once. Only its hash is stored, because the token is a credential into your network and a leaked database must not hand one over.
4. Install the agent on a machine inside your network that stays on, and give it the token.
5. Watch it check in on this page.

A good host for it is the same server that already runs something else always-on and internal. It is a small process and it does not need much.

It monitors itself

Creating an agent creates a monitor for it at the same time, checking heartbeat freshness on a sixty second interval.

This is inverted from every other monitor: nothing can reach the agent, so the check is “did it report recently” rather than an outbound probe.

An agent that is installed and then dies gets noticed by the alerting you already have, instead of by somebody eventually wondering why the roster stopped syncing.

Which connectors need one

Connector	Why
LDAP and Active Directory	Domain controllers are internal by definition
Synergetic	Runs against a SQL Server on the school network
Web Help Desk	Typically an internal appliance
PaperCut	The print server is internal
Printers over SNMP	Printers answer on the LAN

Everything else reaches a vendor API over the public internet and works identically whether you are hosted or not.

Job lifetime

A queued job waits for an agent for a bounded time and is then given up on. If nothing collects it, the feature that queued it reports that the agent is not responding rather than hanging.

The agent holds its connection open when there is nothing to do, so work is collected within a second or so rather than on a polling interval.

Both timings are configurable on a self-hosted deployment through AGENT_JOB_TTL_MS and AGENT_LONG_POLL_MS. The defaults are sensible and there is rarely a reason to change them.

Security

The token is a credential into your network. Treat it that way. It is shown once, stored only as a hash, and can be revoked from this page.

Revoking is immediate. Delete the agent and its token stops working on the next poll.

One agent per network segment, not one per connector. An agent serves every connector that needs to reach the segment it sits in.

Scope the accounts the agent uses. The agent is only as privileged as the credentials the connectors hold. An LDAP bind account that can search and reset passwords should not also be a domain administrator.

More than one agent

A school with several campuses on separate networks installs one per campus and attaches each to a site. Work is routed to the agent for the right site.

A single campus needs one. Installing two for redundancy is possible; work goes to whichever collects it first.

Troubleshooting

Symptom	Cause
Agent never checks in	The token is wrong, or the machine cannot reach the platform. Check outbound HTTPS from that host
Agent checked in once and stopped	The process is not running as a service, or the machine slept. Its monitor will be alerting
Jobs time out	The agent is running but cannot reach the target system. Test from that machine directly
A connector still fails with the agent healthy	The connector’s own credentials are wrong. The agent’s health says nothing about them
Works for LDAP, not for SNMP	The agent’s host cannot reach the printer subnet. Agents are as reachable as the machine they sit on

The distinction in the last three rows is worth internalising: a healthy agent means the tunnel works. It says nothing about whether the credentials or the routing beyond it do.