Firewalls
Firewalls (tenant admins) lists the FortiGates Matrix manages, with Name, Address, Connector, Status, FortiOS version, Connector guard, Last report and whether Changes are on. Add firewall opens the form; a firewall's row opens its page.
Each firewall is one FortiGate VDOM reached through one connector. A tenant can have several (up to 50 per connector).
Settings
General
| Field | Meaning |
|---|---|
| Name | Shown on the rooms page and in the history. Unique in the tenant. |
| Site | Optional location. |
| Connector | The connector that reaches this FortiGate. Moving the firewall to another connector removes it (and its token) from the old one. |
| Driver | FortiGate (REST API), or Simulator (test data, no real firewall) (Trying Matrix with the simulator). |
Connection
| Field | Meaning |
|---|---|
| Address | The FortiGate's HTTPS management address as the connector computer reaches it: a host name or IP address. |
| Port | Its HTTPS management port (default 443; many sites use another admin port). |
| VDOM | The VDOM of the room policies (default root). Every request names it, and every answer must come from it. |
| Verify the FortiGate's TLS certificate | On by default. Checks the certificate against CA certificate (PEM), or the connector computer's trusted roots when that is empty. Off: the connection stays encrypted, but the firewall's identity is not checked; turn it on as soon as you have the CA. |
| CA certificate (PEM) | The CA that issued the FortiGate's certificate (at most 64 KiB). |
| Expected FortiOS version | For example 7.4.11. When set, every answer of another version is refused (version_mismatch): pin it so an upgraded FortiGate is re-checked before Matrix writes to it. Empty accepts any version. |
| Report interval (seconds) | How often the connector reads the rooms: 15–300, default 30. |
The connector never uses a proxy from the environment and never follows redirects when it talks to the FortiGate; a request times out after 4 seconds to connect and 8 seconds in total.
Rooms
| Field | Meaning |
|---|---|
| Source interface or zone, Destination interface or zone | A room policy's srcintf and dstintf must be exactly these, one each (interfaces, zones or SD-WAN zones), for example Students → INTERNET. Both must exist on the FortiGate (direction_invalid otherwise). |
| Policy name pattern | Which policies are rooms, and their room codes (below). |
| Building names | Names shown for building codes, for example FB → Фирма, HAC → ЦВП. Codes SB1, SB2, … without a name are shown as Building 1, Building 2, …. |
Computers
| Field | Meaning |
|---|---|
| Computer name suffix | New computers are named <label><suffix>, for example pc-102-01.coding.local with .coding.local. Starts with a dot. |
| Marker of created objects | Starts the comment of address objects Matrix creates, followed by the operation ID. Default Entrosity Matrix operation. |
Changes
| Field | Meaning |
|---|---|
| Firewall in use | On: the connector reads the firewall and reports its rooms. Off: the firewall is removed from its connector; its rooms stay listed as stale. |
| Allow turning room policies on and off | Off by default. |
| Allow changing and adding computers | Off by default. |
Allowed sites
| Field | Meaning |
|---|---|
| Allow editing allowed sites | Off by default. On: tenant admins (and teachers, for their rooms) may change the allowed sites of this firewall. Matrix then changes the members of the Matrix allowed sites address groups and creates FQDN address objects (matrix-site:…). The connector's guard must allow it too: matrix-connector guard set <firewall id> --site-writes on on the connector computer. |
Only tenant admins change this switch (the firewall's settings are theirs); teachers never can. There is no switch for Entrosity's own servers: while a room's internet is off they are not reachable unless a list holds them (Allowed sites → Entrosity Axis agents).
With changes on, Matrix writes to the real FortiGate: policy statuses, /32 address objects of the room groups and the members of the allowed-sites groups. The connector's local guard must also be accepted on the connector computer (Connectors → The local guard).
Every save sends the new configuration to the connector. A change of the host, port, VDOM, interfaces, pattern, suffix or marker is a change of the scope: the connector stops writing to the firewall until a local administrator accepts the new scope (Configuration changed — accept again). Token, TLS, version pin, report interval and the switches (including the allowed-sites switches) are not part of the scope.
Policy name pattern
The pattern is a regular expression in RE2 syntax (no look-arounds,
no back-references), at most 500 characters, matched against the whole
policy name (as if it started with ^ and ended with $). It must have:
- exactly one named group
(?P<room>…): the room code shown to users and used for rights (SB1-102); - optionally one named group
(?P<building>…): the building. Without it, the building is the room code up to the first-(SB1).
Examples:
| Pattern | Matches | Room | Building |
|---|---|---|---|
Internet Access for (?P<room>(?:SB[0-9]+|FB|HAC)-[0-9]{3}) | Internet Access for SB1-102 | SB1-102 | SB1 |
| same | Internet Access for FB-102 | FB-102 | FB |
| same | Internet Access for Students, Test-Internet-SB1-102 | – (not rooms) | |
Room (?P<building>[A-Z])(?P<room>[A-Z][0-9]{3}) | Room B B204 | B204 | B |
Only policies that match and have exactly the configured direction and VDOM are rooms. A policy whose name matches but whose direction does not is ignored (never switched). Keep the pattern tight: a policy that is not a room must never match.
The Pattern tester on the firewall's page checks a pattern before you save it: paste policy names (one per line) or choose Use names from the last check, which lists every policy with the configured direction; it shows Room SB1-102 · building SB1 or not a room for each and 5 of 8 names are rooms.
API token
The token of the FortiGate's REST API administrator (Setting up the FortiGate). Under API token, paste it into New token and choose Store token (at most 512 characters, no spaces). Token stored. The connector picks it up within a minute.
- It is write-only: stored encrypted, never shown again, never in the history, the audit log or a job. A token is stored. / No token stored yet. is all the app shows.
- The connector fetches it from Matrix (and keeps it DPAPI-sealed on its
computer) when it is new or changed; each fetch is recorded in the
audit log as
firewall.credentials_fetch(without the token). - To rotate it, generate a new token on the FortiGate and store it here.
Check
Check runs a read-only check through the connector (it only reads the FortiGate) and shows:
| Item | Meaning |
|---|---|
| FortiOS version | As the FortiGate reports it. |
| Direction | found: both interfaces or zones exist. |
| Room policies | Policies that are rooms. |
| Address groups, Computers | Groups in the rooms' sources, and their members. |
| Connector guard | Accepted, Waiting for acceptance or Configuration changed — accept again. |
| Warnings | What would still let traffic through, and anything odd. |
The most important warning is later_accept_policy:: policy N "…"
after room SB1-102 accepts the room's computers when the room is
disabled, with the reason: source "all", same address objects, or
an address range covering every computer of the room. It lists every
enabled ACCEPT policy later in the sequence with the same direction
(or any) whose source covers the room. While such a policy exists,
switching the room off does not cut its internet
(What switching a room off means).
Fix it on the FortiGate; Matrix does not change other policies. An
ACCEPT policy whose every destination is an allowed-sites group (or the
old Matrix Entrosity services group, until it is
removed) is
not such a policy: it only lets the rooms reach those domains.
With a connector that supports allowed sites, the check also lists the
allowed-sites lists and warns when something is missing:
sites_not_set_up: (the group does not exist),
sites_policy_missing:, sites_policy_disabled:,
sites_policy_not_covering: (a list's policy), sites_group_read_only:
and sites_wildcard_dns:
(Allowed sites → Setup status).
The same check runs offline on the connector computer with
matrix-connector check --config (Matrix connector → Offline check).
Refresh asks the connector to read the firewall's rooms and address groups now.
Status
| Status | Meaning |
|---|---|
online | The last read succeeded. |
unreachable | No connection (address, port, routing, the FortiGate's trusted hosts). |
auth_failed | The FortiGate answered 401/403: wrong token, or the connector's IP is not a trusted host of the API administrator. |
version_mismatch | The FortiOS version differs from Expected FortiOS version. |
direction_invalid | The source or destination interface or zone was not found. |
error | Anything else, for example inconsistent data (invalid_response) or a failed TLS verification (tls). |
What to do for each: Troubleshooting.
Connector guard
Connector guard shows what the connector's local guard says about this firewall, and the command to run on the connector computer when it is not accepted:
| Shown | Meaning |
|---|---|
| Accepted | A local administrator accepted the current scope. |
| Waiting for acceptance | A new firewall: matrix-connector guard accept <id> on the connector computer. |
| Configuration changed — accept again | The scope changed since it was accepted: review and accept again. |
Delete a firewall
Delete firewall asks Delete this firewall?: Matrix forgets it and its rooms, and the connector forgets its token. The FortiGate itself is not changed. The history is kept.