Site connector

rmm-connector.exe runs as the Windows service RMMConnector on one domain-joined server per site. Source: entrosity-axis-connector/ (packages ldap, adsync, push, wol, account, vertex), sharing entrosity-shared-go/agentkit with the agent.

Installation

msiexec /i rmm-connector.msi /qn ENROLLMENT_TOKEN=<token> SERVER_URL=<url> [SERVICE_ACCOUNT=DOMAIN\user SERVICE_PASSWORD=<pw>]

Property	Meaning
ENROLLMENT_TOKEN	A connector token (from Active Directory → Download connector).
SERVER_URL	The server's public URL.
SERVICE_ACCOUNT, SERVICE_PASSWORD	Optional domain account for the service; the MSI grants it "Log on as a service" and access to the data directory.

The MSI installs one Windows service, RMMConnector (display name Entrosity Axis Site Connector; the Add/Remove Programs entry has the same name). It runs as LocalSystem unless SERVICE_ACCOUNT is given. After starting it, the MSI sets the service to restart 30 seconds after each of its first three failures, with the count reset after a day (sc.exe failure). This step is best effort and never rolls the install back.

Enrollment runs during the install only if the machine is not enrolled yet. If a credential is already stored in %ProgramData%\RMM Connector, the install log says already enrolled and the stored key is kept. If that key is no longer accepted, the connector keeps failing to connect (401 on /api/connector/v1/ws in the server log). To fix that, enroll again with a new connector token and restart the service:

"C:\Program Files\RMM Connector\rmm-connector.exe" enroll --server <url> --token <token> --force
sc start RMMConnector

/qn hides installer errors. To troubleshoot, add /l*v C:\connector-install.log and look for Return value 3. The verbose log contains the enrollment token, so delete it afterwards.

Command line

rmm-connector <command> [flags]

  run         run the connector (foreground, or as a service under the SCM)
              --server URL --token T   enroll first if not enrolled yet
  enroll      enroll this machine: --server URL --token T [--force]
  status      show enrollment state
  install     install the Windows service
  uninstall   remove the Windows service
  prepare-service-account --account DOMAIN\user
              grant "Log on as a service" and data directory access (MSI)
  vertex guard show|accept|set|reset
              the local Entrosity Vertex write guard (elevated prompt)
  version     print the version

RMM_CONNECTOR_DATA_DIR overrides the data directory (%ProgramData%\RMM Connector); RMM_LOG_LEVEL sets the log level. Logs: %ProgramData%\RMM Connector\logs\connector.log.

Capabilities and lanes

The connector announces ldap, winrm, wol, and on Windows builds smb and vertex. Jobs run in lanes so a long push does not block a sync:

Lane	Jobs	Parallelism
LDAP	adsync.run, ldap.test, ldap.ous	serial
push	push_agent	2 jobs, each concurrency targets (default 5)
wake	wake	–
update	update_agent	–
vertex	vertex.op (Entrosity Vertex changes)	serial, in order
vertex-read	vertex.read (Entrosity Vertex reads)	2

LDAP sync

• Connect with LDAPS or StartTLS using the system roots plus the optional CA from the configuration; verification is skipped only with skip_tls_verify.
• Simple bind, then a paged subtree search (500 per page) with (&(objectCategory=computer)<filter>); OU include/exclude by DN suffix.
• Computers are sent in chunks of at most 1,000; the last chunk has complete: true and the total. Chunks are idempotent per sequence number and may arrive out of order.

Agent push

The connector downloads the MSI once per job (up to 4 attempts with backoff on network errors and HTTP 5xx; the SHA-256 is checked). The server hands out the newest published stable agent release by its versioned object, so a release published during a push does not change the file. If the connector's DNS cannot resolve the files host, the error says so (download_failed).

Per target, with a 10-minute timeout:

1. resolve the name (FQDN, else the short name) → connecting;
2. SMB first (TCP 445, Windows builds). All SMB steps run on a thread impersonating a net only logon of the push account (like runas /netonly), because the connector's own identity (LocalSystem, the computer account on the network) is not an administrator on the targets and the remote service manager's RPC uses TCP on current Windows. Connect to \\host\ADMIN$ (a conflicting existing connection, error 1219, is dropped and retried) and open the remote service manager. An existing RMMAgent service → success (already_installed); a leftover RMMPush service is removed;
3. copy the MSI to ADMIN$\Temp\rmm-agent.msi → copying;
4. create and start a temporary RMMPush service that runs cmd /c start "" msiexec /i … /qn ENROLLMENT_TOKEN=… SERVER_URL=… /l*v C:\Windows\Temp\rmm-agent-install.log → installing;
5. poll the installer log (UTF-16 or ANSI) for Installation success or error status and the service manager for RMMAgent: exit 0, 3010 or 1641 with the service → success; another exit code → msiexec_failed with its meaning and the last 25 log lines (enrollment tokens redacted). The service, the MSI and the log are removed.

WinRM is used when port 445 is closed (or on non-Windows builds), and as a fallback when SMB fails before anything was started (ADMIN$ disabled, service manager not reachable: copy_failed or unreachable). It connects over HTTPS 5986, else HTTP 5985 with NTLM message encryption, and runs every command in one remote shell, one at a time (never with stdin: concurrent stdin and output polling corrupts the encrypted stream). The MSI is appended as base64 lines of 7,800 characters, decoded with certutil -decode and compared with certutil -hashfile … SHA256; then msiexec runs as above.

The push enrollment token, the credential and the MSI link are added to the job only at delivery.

Wake-on-LAN

wake sends magic packets for up to 16 MAC addresses on every IPv4 interface, to the limited and directed broadcast addresses, UDP ports 9 and 7.

Entrosity Vertex

On a domain controller, the connector runs the Active Directory operations of Entrosity Vertex: vertex.op and vertex.read jobs (Vertex protocol). For each job it fetches the AD account and passwords from Vertex through Axis (POST /api/connector/v1/vertex/jobs/{jobID}/secrets, once per job), starts Windows PowerShell 5.1 with an embedded script that opens a PowerShell session to the same machine as that AD account, and sends large results back as chunks (POST …/vertex/jobs/{jobID}/chunks). Requirements on the domain controller: Setting up the domain controller.

Changes need the local guard, vertex-guard.json in the data directory, which only a local administrator changes, from an elevated prompt:

rmm-connector vertex guard show
rmm-connector vertex guard accept [--ou "<DN>" ...] [--yes]
rmm-connector vertex guard set [--user|--group|--ou|--gpo|--pso on|off] [--deletes on|off] [--max-writes-per-minute N]
rmm-connector vertex guard reset

accept --ou (repeatable) accepts the given managed OUs in advance, before Vertex sent any job; they must be exactly the managed OUs in Vertex's settings. Without --ou, accept accepts the managed OUs that Vertex sent with its latest change (the guard is created, pending, by the first change). set switches write classes, deletes and the per-minute cap (default 1,000, from 1 to 2,000; new guards allow users, groups and OUs), and reset withdraws the acceptance. The file must be owned by Administrators and writable only by SYSTEM and Administrators, or it is ignored. Details: The connector's local guard.

Presence

A connector is online from its hello until its socket closes (connectors run on servers, so a drop shows at once) or after 3 minutes of silence.

Developing against Samba AD

The LDAP part runs on macOS and Linux too. See Development setup → Running the connector.