Troubleshooting

A room is disabled but still has internet

A disabled rule alone does not prove that the internet is off. In order of likelihood:

1. A later ACCEPT policy. Run Check on the firewall (Firewalls → Check). Every later_accept_policy: policy N "…" after room … accepts the room's computers when the room is disabled (…) warning is a policy further down the list, with the same direction (or any), whose source (all, the same objects, or a network covering the room's computers) lets the traffic through. For example a general Internet Access for Students policy for the whole student network, placed after the room policies. The FortiGate's administrator must take the managed addresses out of it or add a blocking policy after the rooms. Matrix does not change other policies.
2. Established sessions. Connections opened before the change may continue. firewall-session-dirty check-all makes the FortiGate re-evaluate them, which does not guarantee that they are cut. Test with a new connection.
3. The computer is not in the room's group, or has another IP than its address object (DHCP handed out another address, the student changed it). Check Addresses and groups.
4. Another way out: IPv6, another interface or policy, a proxy.
5. The change did not happen: see the room's last result and the History entry with its steps.

Stale data

The rooms show State not current and cannot be switched while the firewall's data is stale (Rooms → Stale data). The banner says why:

Reason	What to do
the connector is offline	Check the connector computer: the service Entrosity Matrix Connector running, outbound TCP 443 to hub.entrosity.com, the log C:\ProgramData\Entrosity\Matrix Connector\logs\connector.log.
the last report is too old	The connector is online but cannot finish reading the firewall in time. Look at the firewall's status and the connector's log.
no report yet	A new firewall: store its token, and wait one report interval.
A firewall status (below)	See Firewall status.

Firewall status

Status / code	Likely cause	What to do
unreachable	The connector computer cannot open the FortiGate's HTTPS management port.	Address and port on the firewall's page; routing; the FortiGate's admin access on that interface (HTTPS allowed); the API administrator's trusted hosts (the FortiGate does not answer from other addresses).
tls	The FortiGate's certificate does not verify.	Paste the right CA certificate (PEM); check the host name or IP in Address is in the certificate.
auth_failed	HTTP 401/403: wrong or revoked token, the connector's IP is not a trusted host, or the profile lacks a permission.	Store a new token; check the trusted hosts (the IP after NAT) and the access profile (Setting up the FortiGate).
version_mismatch	The FortiOS version is not Expected FortiOS version (for example after an upgrade).	Check the room policies still behave the same on the new version, run Check, then update the pinned version.
direction_invalid	The source or destination interface or zone is not on the FortiGate (renamed?).	Correct them on the firewall's page.
invalid_response	The FortiGate returned inconsistent data (a list that changed while it was read, an answer from another VDOM, duplicate policy IDs).	Usually passes on the next read. If it persists, check the VDOM and the connector's log.
unknown_firewall	The connector does not know the firewall (yet).	Wait a minute after adding or moving it; check the firewall is in use and on the right connector.
unknown_driver	simulator on a connector that was not started with --dev.	Trying Matrix with the simulator.

Refusals

A Refused change wrote nothing. The reason tells why:

Code	Meaning	What to do
room_not_granted	At write time: your right for this room was removed after the change was sent.	Ask a tenant admin (Room rights).
forbidden	Your role cannot do this.	Roles and permissions.
writes_disabled	Changes are switched off for the firewall, in Matrix or in the connector's guard.	Firewalls → Changes; guard set <id> --policy-writes on / --address-writes on.
guard_pending, guard_mismatch	The connector's local guard has not accepted this firewall, or its configuration changed.	matrix-connector guard show, then guard accept <id> on the connector computer (Connectors → The local guard).
snapshot_stale	The firewall's data is stale.	Stale data.
connector_offline	The connector is not connected.	Check the connector computer.
busy	Another change of the same room (or, for addresses, of the same firewall) is running.	Wait a moment.
rate_limited	More than 10 changes per minute by you, or 30 in the tenant (or the connector's local cap).	Wait a minute.
unknown_room	The firewall does not report this room (any more); for a teacher also a room not granted to them (This room is not available to you (any more)).	Refresh; check the policy on the FortiGate; ask a tenant admin for the right (Room rights).
forbidden_policy	The policy is not a manageable room policy (name, direction or VDOM does not match).	Check the policy and the firewall's pattern and direction.
room_mismatch, policy_changed	The policy changed on the FortiGate between the reads (renamed, another room, status changed by someone else).	Refresh and look again before retrying.
unauthorized	Matrix refused the write at the last moment: the right was removed, the author was signed out, the change expired, changes were switched off. The history's steps name the reason.	Check the steps; send a new change if it is still wanted.
conflict	Addresses: the group or the IP changed since you loaded them.	Refresh, check, retry.
duplicate_ip, duplicate_name	Another managed computer has this IP; an object with this name exists.	Choose another.
shared_object	The group or object is also used outside this room.	Change it on the FortiGate if needed.
invalid_input	The name or IP was rejected.	A single DNS label plus the suffix; a single host's IPv4 address.

Allowed sites

Refusals and messages of allowed sites:

Code or message	Meaning	What to do
sites_not_set_up	The list's address group or its ACCEPT policy is missing on the FortiGate (also as a job error, when it disappeared after the page was loaded).	A tenant admin opens FortiGate setup and has the commands pasted into the FortiGate (Allowed sites → FortiGate setup).
connector_outdated	The firewall's connector does not support allowed sites yet (The connector of this firewall does not support allowed sites yet. Update the connector.).	Update the connector (Connectors → Updates).
invalid_domain	A domain is not valid: an IP address, a path, a character that is not allowed, or more than 200 domains.	Use a name like example.com or *.example.com.
group_read_only	Matrix may not change the group: it is also used as a source address or inside another group, or has nested groups.	Use the group only as the destination of its allowed-sites policy, on the FortiGate.
writes_disabled	Allow editing allowed sites is off for the firewall, or the connector's guard does not allow site writes.	Firewalls → Allowed sites; on the connector computer matrix-connector guard set <id> --site-writes on.
conflict	The list changed since you loaded it (someone else saved it, or it was changed on the FortiGate).	Refresh, check the domains and save again.
forbidden, unknown_room	The list for all rooms is for tenant admins; a teacher changes only the lists of their rooms.	Roles and permissions.

Unconfirmed changes of a list: use Check / retry on the list (Allowed sites → Saving and results).

Computers are offline in Axis while a room's internet is off

Expected: Matrix has no built-in exception for Entrosity. While a room's internet is off, its computers reach only the domains of the allowed-sites lists, so the Entrosity Axis agent on them loses its connection until the internet is on again (the computers show as offline in Axis; remote support, scripts and deployments wait).

An admin can add the domains Axis needs to a list, but we advise against it: the Hub (hub.entrosity.com) and Axis management (manage.entrosity.com) are behind Cloudflare, whose addresses are shared with many other sites, so allowing them opens those sites to the room too (Allowed sites → Entrosity Axis agents). Turn the room's internet on while its computers need Axis.

Removing the old Entrosity services group

FortiGates set up with an earlier version of Matrix have the address group Matrix Entrosity services as a second destination of the shared allowed-sites policy (Matrix allowed sites). Matrix no longer reads or writes it, and nothing has to change: the policy still counts as the allowed-sites policy. To clean up, an admin runs in the FortiGate CLI (<shared policy id> is the ID of the policy Matrix allowed sites):

config firewall policy
    edit <shared policy id>
        unselect dstaddr "Matrix Entrosity services"
    next
end
config firewall addrgrp
    delete "Matrix Entrosity services"
end

Take the group out of the policy first: FortiOS refuses to delete a group that a policy still uses. Until the group is removed, whatever it holds besides none stays reachable from rooms with their internet off.

Errors

An Error / Failed change wrote nothing: the firewall could not be reached or answered unexpectedly (unreachable, tls, auth_failed, version_mismatch, direction_invalid, invalid_response), or the change reached the connector too late (expired, never taken by the connector: it was offline). See Firewall status. All codes: Error codes.

Unconfirmed changes

Unconfirmed means a write was sent, or may have been, and its confirmation did not arrive: the connection to the FortiGate broke after the write, the connector restarted in the middle, or the change expired after the connector took it.

1. Refresh and look at the room (or the computer).
2. Open the change in the History: the steps show how far it got.
3. Only then change it again if needed. Matrix never repeats an unconfirmed write on its own.

For address operations use Check / retry on the unfinished operation (Addresses and groups).

The guard

• guard: run this from an elevated (administrator) prompt: open the command prompt with Run as administrator.
• firewall … is unknown (it appears after the server applied it): the firewall has not reached the connector yet; check it is in use and assigned to this connector, and wait a minute.
• guard.json can be changed by non-administrators; it is ignored: its permissions were changed. Reset them (only SYSTEM and Administrators) or delete the file and accept the firewalls again.

Failed re-enables

A room disabled until a time was not turned back on (Schedules). Look at Detail: usually the connector was offline for 24 hours, the guard was not accepted, or changes were switched off. Enable the room by hand once the cause is fixed.

Where to look

• History: every change with its steps and result.
• Audit log (tenant admins): changes of the setup (firewalls, tokens stored and fetched, connectors, enrollment tokens).
• The connector computer: logs\connector.log and the Application event log (source EntrosityMatrixConnector); matrix-connector status; matrix-connector guard show; matrix-connector check --config.