Skip to main content

Connectors

The Matrix connector is a Windows service on a computer of the school's administration network. It connects out to Matrix, reads the FortiGates it is given, reports their rooms, and carries out changes. Connectors (tenant admins) lists the tenant's connectors with Name, Computer, Status, Firewalls, Version and Last seen, and the Enrollment tokens.

Requirements​

  • An always-on Windows computer (Windows 10/11 or Windows Server, 64-bit) on the administration network, which reaches the FortiGate's HTTPS management port. It should not be reachable from student networks.
  • Outbound TCP 443 to hub.entrosity.com (HTTPS and WebSocket). Nothing inbound, no VPN.
  • Its IP address, as the FortiGate sees it, is the only trusted host of the FortiGate's API administrator (Setting up the FortiGate).
  • A local administrator who will accept each firewall on it (The local guard).

One connector can manage several firewalls. The computer of an Axis, Edge or Sphere connector will do: each product's connector is its own service.

Install​

  1. Install a connector creates an enrollment token: a Label, the Site, Maximum uses (1 for one computer) and Expires after (days). Copy the token now — it is shown only once.

  2. On the computer, in an elevated command prompt, in the folder of the installer (Download connector downloads the newest one):

    msiexec /i matrix-connector.msi /qn ENROLLMENT_TOKEN=<token> SERVER_URL=https://hub.entrosity.com/matrix

    The dialog shows this command with the token filled in.

  3. The installer puts matrix-connector.exe in C:\Program Files\Entrosity\Matrix Connector, enrolls the connector, and installs and starts the service Entrosity Matrix Connector (EntrosityMatrixConnector, LocalSystem, automatic start, restarted on failure). A failed enrollment rolls the installation back.

  4. The connector appears under Connectors within a minute.

Without ENROLLMENT_TOKEN and SERVER_URL the service is installed and waits; enroll it later from an elevated prompt:

matrix-connector enroll --server https://hub.entrosity.com/matrix --token <token>
Install logs contain the token

An installation log made with msiexec … /l*v install.log contains the enrollment token. Delete it afterwards, and revoke tokens you no longer need (Revoke).

The local guard​

Matrix decides what a connector manages; the local guard is what a local administrator of the connector computer accepted. The connector writes to a firewall only while:

  • the firewall's current scope (host, port, VDOM, source and destination interface, policy name pattern, computer name suffix, marker) is the one accepted on this computer;
  • the kind of write (policy or address) is allowed locally;
  • fewer than the local cap of writes were made in the last minute (60 by default).

A firewall applied for the first time is pending (Waiting for acceptance); a later change of its scope in Matrix makes it mismatch (Configuration changed — accept again) until the change is accepted. Matrix shows the guard state on the firewall's page and the rooms page and refuses changes with guard_pending or guard_mismatch. The guard can only be changed on the computer itself, never from Matrix.

Run in an elevated command prompt in C:\Program Files\Entrosity\Matrix Connector:

CommandWhat it does
matrix-connector guard show [firewall_id]Lists every firewall in the guard: state, whether policy and address writes are allowed, the cap, the accepted scope, and a scope waiting for acceptance with what changed. (Works without elevation.)
matrix-connector guard accept <firewall_id> [--yes]Shows the scope (or what changed) and asks you to type yes; then accepts it. The first acceptance allows policy writes; address writes stay off.
matrix-connector guard set <firewall_id> [--policy-writes on|off] [--address-writes on|off] [--max-writes-per-minute N]Allows or forbids policy or address writes, and sets the cap (1–600).
matrix-connector guard reset <firewall_id>Withdraws the acceptance: writes stop until guard accept.

Example:

> matrix-connector guard accept 7c0e…
Firewall 7c0e…: Matrix may change the status of room policies and the /32 address objects of their groups within:
  destination_interface: "INTERNET"
  host: "192.0.2.1"
  hostname_suffix: ".coding.local"
  marker_prefix: "Entrosity Matrix operation"
  policy_pattern: "Internet Access for (?P<room>(?:SB[0-9]+|FB|HAC)-[0-9]{3})"
  port: "443"
  source_interface: "Students"
  vdom: "root"
Type yes to accept: yes
accepted: policy writes on, address writes off, at most 60 writes per minute
(address writes: matrix-connector guard set 7c0e… --address-writes on)

Changes take effect at once, without restarting the service. The guard is guard.json in the data directory; it must be writable by SYSTEM and Administrators only. If anyone else can change it, the connector ignores it and writes nothing.

Offline check​

matrix-connector check --config local.json checks a FortiGate from the connector computer without Matrix: it sends GET requests only and prints the FortiOS version, the direction, the rooms, the groups and members, the policies with the direction and the warnings, then Nothing was changed. The effect on traffic was not verified. The token is read from a file and never printed. Configuration and output: Matrix connector → Offline check.

Status​

matrix-connector status shows whether the connector is enrolled, and its firewalls with their guard states.

In MatrixMeaning
OnlineConnected now.
OfflineNo connection for 3 minutes: its firewalls' rooms are stale and changes are blocked.

Where it keeps its data​

C:\ProgramData\Entrosity\Matrix Connector:

FileWhat
connector.datThe connector's identity and key (DPAPI-sealed).
firewalls.jsonThe firewalls Matrix applied, with their API tokens (DPAPI-sealed).
guard.jsonThe local guard.
journal.jsonThe write journal: what was about to be written, recorded before each write.
state.jsonJobs in progress.
logs\connector.logThe log (rotated). Warnings and errors also go to the Application event log (source EntrosityMatrixConnector).

After a restart, a change whose journal shows that a write may have been sent is reported as Unconfirmed, never repeated.

Updates​

Matrix offers connectors that can update themselves the newest release: they download it, check its signature, install it from the scheduled task MatrixConnectorUpdate and roll back if the new version does not start. Version on Connectors shows updating to X, or update to X for a connector that must be updated by hand once (installed before self-update): run the new MSI on its computer. Data and the guard are kept (Matrix connector → Self-update).

Remove a connector​

Remove asks Remove this connector?: its key stops working and it disconnects. A connector that still manages firewalls cannot be removed (connector_has_firewalls): move them to another connector or delete them first. Then uninstall it on the computer (Apps, or msiexec /x matrix-connector.msi), which removes the service, the program, the enrollment, the firewalls with their tokens, the journal and the guard; the logs stay.