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

From 0.20.0, creating an agent and rotating its token require an unrestricted whole-school administrator and a fresh authentication confirmation. A delegated connector manager or campus/department-scoped administrator cannot issue these credentials. An agent can answer LDAP authentication jobs, even if LDAP is configured later, so enrolling its host changes the school’s sign-in trust.

First obtain an available agent asset for the intended host. The current native release matrix also builds connector-agent archives for Linux x64 only. Windows, macOS and ARM service examples below are reference/source-build instructions, not promises of published downloads. Check the download centre and validate any separately built agent before enrolling it.

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. It is good for a year; see Expiry and rotation.
4. Install the agent on a machine inside your network that stays on, and put the token and your Plugboard address in agent.env beside it. The address must be https:// — the agent refuses to start on a plain http:// address, because the token goes to it on every heartbeat and would be readable by anything on the wire in between.
5. On Linux or macOS, chmod 600 agent.env secrets.json. Both hold a credential — one into Plugboard, one into your domain — and the default on a new file is readable by every account on that server, and by anyone holding a backup of that folder. The agent warns at startup if either is.
6. Install it as a service, so it survives a reboot — see Run it as a service below. This step is not optional on a machine you care about.
7. 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.

Run it as a service

Started by hand, the agent runs in the foreground and belongs to the window it was started in. Close the window, log off, or reboot, and it stops. Nothing announces that: the connectors it was serving simply begin failing, which reads as “the connector broke overnight”.

So install it as a service. One command, run as an administrator from the folder the agent is in:

# Linux and macOS
sudo ./plugboard-agent install-service

# Windows, from an elevated prompt
.\plugboard-agent.cmd install-service

It starts immediately and comes back on its own after a reboot, with nobody logged in.

The other commands:

Command	What it does
plugboard-agent	Run in this window. Useful once, to watch it connect
plugboard-agent install-service	Start at boot and keep running with nobody logged in
plugboard-agent uninstall-service	Remove the service. agent.env and your secrets file are left alone
plugboard-agent service-status	Ask this machine how the service is doing
plugboard-agent version	Which build this is

What it installs, per platform

Platform	What is registered	Where to look
Linux	A systemd unit, plugboard-agent.service, running as an unprivileged plugboard-agent account it creates	systemctl status plugboard-agent, journalctl -u plugboard-agent -f
macOS	A LaunchDaemon, app.plugboard.plugboard-agent — a daemon rather than an agent, so it starts at boot with no user session	sudo launchctl print system/app.plugboard.plugboard-agent, and logs/ beside the agent
Windows	A Scheduled Task at system startup running as LocalSystem. If plugboard-agent-service.exe (WinSW) is beside the agent, a true Windows Service instead	schtasks /Query /TN plugboard-agent, or services.msc with the wrapper

On Linux the install hands ownership of the agent’s folder to the account it created and sets agent.env to 600 for you.

On Windows it is a Scheduled Task rather than a service because a plain Node process cannot answer the Service Control Manager — pointing sc create at node.exe gives the familiar error 1053. A task started at boot as LocalSystem meets the actual requirement. If you would rather find the agent in services.msc, drop WinSW in beside it renamed to plugboard-agent-service.exe, then run uninstall-service and install-service again; the matching XML is already written for you.

On Linux, --user <name> installs under an account you name instead of the default:

sudo ./plugboard-agent install-service --user svc-plugboard

If it will not start

Install first and configure after is fine — install-service tells you when there is no agent.env yet and the service picks the file up when it restarts. A service with no PLUGBOARD_URL and AGENT_TOKEN starts, says so, and exits, and every service manager here will keep restarting it.

The agent looks for agent.env and a relative AGENT_SECRETS path in its own folder as well as the working directory, so a Windows Scheduled Task — which starts in the system directory and has no working directory of its own — still finds them.

Pointing a connector at it

Installing the agent is half of it. The other half is telling each connector to use it, which is done on the connector rather than here.

1. Admin, Connectors. Configure the connector as usual — Active Directory, Synergetic, PaperCut, Web Help Desk, printers over SNMP.
2. Set Runs on to the agent at the right site. See Runs on.
3. Put that connector’s credentials in the agent’s own secrets file, not in Plugboard. The dialog stops asking for them once a site is chosen, because they are not ours to hold: the agent is what connects to your domain controller, so the agent is what needs the password.

The file is the AGENT_SECRETS path from the agent’s agent.env, and it is keyed by connector instance ID in 0.14.0:

{
  "<north-ldap-instance-id>": { "bindPassword": "..." },
  "<south-ldap-instance-id>": { "bindPassword": "..." },
  "<printer-instance-id>": { "community": "..." }
}

Use actual instance id values from the authorised GET /api/connectors/instances response. Legacy keys such as ldap remain supported only for the original default instance. Additional instances require separate entries and an updated agent; an older agent cannot claim their work. Changing a name or campus does not change the instance ID. See configuring instances.

If you set the printer connector up before its community string became a credential, it is still in the connector’s settings on the platform. Add it here, then clear the field in Admin, Connectors. See Printers over SNMP.

A connector left on Plugboard itself on a managed deployment is refused when it runs, saying so. It is not queued to an agent and it does not silently fail — it tells you which of the two steps is missing.

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.

Expiry and rotation

A token issued now is good for a year. The date is shown on this page, and the row turns amber a month out. When it passes, the agent stops being accepted and says so in its own log; nothing else about the agent changes, and rotating it brings it straight back.

Rotating is not an outage. Rotate token issues a new one immediately and keeps the one it replaced working for seven more days, so the new token can go into agent.env on your own schedule rather than during a change window. Restart the agent once it is in. After seven days the old one stops.

Rotate when somebody with access to that server leaves, when the file has been somewhere it should not have been, or on whatever cycle your own policy sets. A rotation is written to the audit log, naming who did it and which agent.

Agents installed before this existed carry no expiry date and keep working untouched. They get one the first time they are rotated.

A self-hosted deployment can change the year with AGENT_TOKEN_TTL_DAYS.

Security

After upgrading to 0.20.0, review existing enrolments. Match every agent to an approved host and responsible administrator. Revoke unknown or untrusted agents and enrol approved replacements. The new issuance checks do not establish who holds a token issued before the upgrade. Use revocation for immediate containment; ordinary rotation preserves the seven-day grace period below.

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

Revoking is immediate. Revoke the agent and its token stops working on the next poll, along with any token a rotation had left inside its grace window.

Rotating is not — that is the point of it. Use Revoke when a token is believed compromised, and Rotate token for housekeeping. See Expiry and rotation.

The agent refuses a plain http:// address. The token is sent to it every thirty seconds, and clear text on a school LAN is exactly where a credential like this gets picked up. localhost is exempt.

Keep agent.env and the secrets file to the account that runs the agent — chmod 600 on Linux and macOS. The agent says so at startup if they are wider than that. Mind the backups of that folder too: they hold the same two credentials.

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

Credentials for agent-run connectors never reach Plugboard. They live in the agent’s secrets file on your server. Plugboard does not receive that file, does not ask for it, and refuses the credentials if a settings form sends them.

Scope the accounts the agent uses. The agent is only as privileged as the credentials in that file. 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
Cannot add an agent or rotate its token	Issuance requires an unrestricted whole-school administrator and fresh authentication confirmation; delegated connector access is insufficient
The agent exits saying the address must be https	PLUGBOARD_URL in agent.env is http://. Fix the address; the agent will not send its token in clear text
The agent exits saying its token has expired	The token passed its year. Rotate token on this page, and put the new one in agent.env
The agent exits saying its token was replaced	Somebody rotated it and the seven day grace window has closed. The current token is the one from that rotation; if it was lost, rotate again
A warning at startup about agent.env being readable	Exactly what it says: chmod 600 agent.env secrets.json. The agent keeps running
Agent checked in once and stopped	It was started by hand, so it ended with the window, the logoff or the reboot — or the machine slept. Install it as a service: Run it as a service. Its monitor will be alerting
install-service seemed to do nothing, on an older agent	It genuinely did nothing. Agents built before this was released dropped the subcommand and started in the foreground instead, so they stopped at the next reboot. Check with plugboard-agent version, take the current agent, and run it again
The service starts and immediately exits	No agent.env, or no PLUGBOARD_URL and AGENT_TOKEN in it. Check plugboard-agent service-status and the service log; the agent names which is missing
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
Save and test says this deployment cannot reach your network	The connector’s Runs on is still “Plugboard itself”, or it names a site with no agent. Set it under Admin, Connectors; the test runs through the agent, the same as every other call
The credential fields vanished when I chose a site	Working as intended. They go in the agent’s secrets file instead — see Pointing a connector at it
Runs on offers no sites	None have been created under Admin, Campuses, or your role does not include the site.manage permission

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.