freeQoS technical documentation

1. Overview

freeQoS is an out-of-band QoS/QoE controller for internet service providers running MikroTik routers. It reads the routers through their API, measures what each subscriber experiences, and installs CAKE queues to enforce the plans that were sold. It never sits in the traffic path.

It covers three jobs of an ISP:

• See: each subscriber's throughput, latency and bufferbloat, the load on every link and node, traffic by destination and by application (NetFlow).
• Shape: one CAKE queue per subscriber at the plan rate, under one parent queue per link, created and maintained automatically.
• Integrate: an operating API (/api/v1), a Preseem-compatible inventory API (/model/v1) and a consumption API (/usage/v1).

Design principles

Compared with Preseem and LibreQoS

A direct consequence of being out-of-band: latency is measured by a ping from the router, which requires the subscriber's box to answer pings (see section 5).

Two control loops

freeQoS is the slow loop. The closed QoE loop of section 7 does not change that: it works at the scale of minutes, over windows of several minutes.

The three bottlenecks to shape

1. The last mile of each subscriber, on the PoP: one CAKE queue per subscriber.
2. The radio backhaul or sector: one parent queue per link, at the radio's real capacity.
3. The internet egress: optional, on the gateway. freeQoS reads it but installs no queue there.

What an out-of-band controller can and cannot see

Everything that can be read from counters is at parity. Everything that requires inspecting packets is not, and never will be from a management server: it is the price of being out-of-band, not a gap in the implementation. The interface marks such columns "n/a" rather than showing an empty value that could be read as zero.

Key notions

The rest of this documentation relies on these words. Each one is covered in detail in its own section.

2. Architecture

freeQoS is out-of-band: it is never in the traffic path. It reads the routers and the antennas, stores what it measures, and installs CAKE queues on the routers. The routers are the ones limiting traffic. If freeQoS stops, the queues stay in place and traffic flows normally; only measurement, timed boosts and adjustments pause.

Every grey arrow is a read. The coloured arrow is the only write path: it starts at the planner and goes through the safeguards of section 7.

Components

A measurement, from the router to the screen

1. The collect_subscribers cycle reads /ppp/active and the interface counters of each PoP, every 10 s.
2. The difference between two reads gives a rate. Impossible values are discarded (a counter going backwards, a rate above 100 Gbit/s).
3. The rate is written to a hypertable, together with the last RTT measured by probe_rtt.
4. Bufferbloat and the QoE score are computed when read, over the requested window. No score is stored in advance: a change of scale applies to the whole history.

A write, from the plan to the queue

1. A plan arrives (API, Plans page) or a capacity changes (radio, QoE loop).
2. The planner computes the desired state of each router: queue types, parent queues, subscriber queues.
3. It reads the actual state and produces a plan: the list of commands that would move from one to the other.
4. The safeguards filter the plan: ownership, transit, duplicates, oscillation, circuit breaker.
5. If writing is enabled, the plan is sent command by command, parents first, and each command is logged. Otherwise it is only displayed.

An API call that changes a plan runs these five steps immediately for that subscriber. The 2-minute reconciliation catches up with everything else (PPPoE reconnection, new address, queue edited by hand).

Instance identity

Each installation has an identifier (data/instance.id, or FREEQOS_INSTANCE_ID). It is written into the comment of everything it creates: freeqos:managed instance=<id>. This is what lets two installations, or freeQoS and an operator, never overwrite each other's work.

3. Installation and updates

One command installs everything: install.sh sets up Docker if needed, writes a .env with random secrets, builds and starts the stack, then waits for the application to answer. Running the same script again updates while keeping the data.

Required resources

The figures below were measured on 8 October 2026 on a virtual machine with 4 vCPU and 16 GB of RAM: the real freeQoS application, the timescale/timescaledb:latest-pg16 image, synthetic data. They give orders of magnitude; your network will refine them.

What consumes resources

The NetFlow collector uses a single core. This is the real sizing limit:

Beyond about 5,000 flows per second, datagrams are lost. Adding cores changes nothing; a faster core helps a little. To reduce the volume: export only from the internet edge (one vantage point instead of two), or enable sampling on the routers.

The number of flows per second depends on usage and cannot be guessed. To measure it, read flows_seen in GET /api/v1/netflow/status one minute apart, at peak time.

Disk

Measured per subscriber connected around the clock:

The NetFlow figure is a ceiling: it assumes traffic every minute, day and night, across three usage families. A real subscriber produces less. The two NetFlow tables are not compressed today, only purged after 90 days: they are the largest disk item.

How TimescaleDB stores measurements. A hypertable is split into one-day chunks. After 7 days, each chunk is rewritten as compressed columns: neighbouring values of a column look alike and compress very well. After 90 days, the whole chunk is dropped at once, without scanning the table.

Recommended sizing

The same figures apply to a physical machine and to a virtual machine.

These values keep a 50% disk margin over the measured worst case (≈ 90 MB per subscriber over 90 days), plus the images and the journal. They assume the NetFlow volume stays under 5,000 flows/s; otherwise, see above. An SSD is required: the database writes continuously.

2 GB and 2 CPU run, but with no headroom. The system and Docker take about 400 MB, the application 100 to 200 MB, the database about 700 MB with its cache. That is enough to try freeQoS, not for production: a NetFlow peak takes memory that is not given back. For production, start at 2 CPU and 4 GB.

Analysing both directions behind NAT keeps a pairing table (see Both directions, section 6). Full (100,000 conversations), it takes about 76 MB, plus up to about 15 MB for downloads waiting for their upload: under 100 MB at worst, already covered by the sizes above.

Physical machine or virtual machine

Both work, with the same sizes. What changes:

To know where you stand, read flows_seen in GET /api/v1/netflow/status twice, one minute apart, at peak time: the difference divided by 60 is your flows per second. Under 5,000, the sizes above are enough.

On the routers, freeQoS adds:

• an API read every 10 s (sessions and counters);
• 20 subscribers × 5 pings every 30 s per PoP;
• the NetFlow export, which uses router CPU.

Watch the routers' CPU load in Devices after commissioning.

Prerequisites

Network flows

A stateful firewall only needs a rule in the direction the connection is opened: the reply is accepted as part of the connection. The only exception is NetFlow: a one-way UDP send, from the router to freeQoS, with no reply.

On the router, the firewall's input chain must accept TCP 8728 or 8729 from the freeQoS address. The NetFlow export leaves through the output chain, which is usually open.

Step-by-step installation

1. Prepare the server. A virtual machine sized according to the table above, with a fixed IP and an SSD.

2. Open flows 1, 3, 4 and 13 of the table, plus 2 if a billing system calls the API.

3. Create the freeQoS account on each router. In the RouterOS terminal:

/user/group add name=freeqos policy=read,write,api,test
/user add name=freeqos group=freeqos password=<strong-password> address=<freeQoS-IP>/32
/ip/service set api address=<freeQoS-IP>/32

address= restricts the account and the API service to the freeQoS address. For the encrypted API, enable api-ssl (port 8729) with a certificate, and tick SSL when adding the router. To start read-only, there is nothing to change on the router: leave Allow freeQoS to write on this router unticked when you add it in Devices (the default). freeQoS then reads and measures without writing anything, and you allow writing later, router by router, from the same page (see Rolling out router by router, section 7).

4. Install freeQoS on the server:

curl -fsSL https://raw.githubusercontent.com/tatdorian/freeQos-/HEAD/install.sh | sudo sh

If the repository is private, this link does not answer without authentication. Clone the repository with an access token instead, then run sudo ./install.sh from its folder.

Without asking anything, the script:

1. installs Docker, the docker compose plugin and git if they are missing;
2. fetches the code into /opt/freeqos (main branch, or FREEQOS_BRANCH);
3. writes .env: random PostgreSQL password, APP_PORT=8000, NETFLOW_PORT=2055;
4. switches to mirror.gcr.io if Docker Hub is unreachable;
5. moves the web proxy to 8081 / 8443 if another web server already holds 80 / 443 (written to .env as HTTP_PORT / HTTPS_PORT);
6. builds, starts, waits for /health (3 minutes at most) and prints the address;
7. prints the first Administrator account, which the application creates by itself on its first start (see step 6). Nothing is asked: the installation runs unattended;
8. makes freeQoS start with the server: Docker is enabled at boot, every container is restart: unless-stopped, and a systemd service freeqos runs docker compose up -d at boot, even after a docker compose down.

sudo systemctl status freeqos shows it; sudo systemctl disable freeqos turns the automatic start off.

5. Check.

cd /opt/freeqos && sudo docker compose ps
curl -s http://127.0.0.1:8000/health/ready

The three containers freeqos-app, freeqos-db and freeqos-proxy must be running, and /health/ready must answer "status":"ready".

6. The first Administrator account is created by the application itself, on its first start, before it answers anyone. There is no "create the first account" screen left open to whoever reaches the server first.

• Email: FREEQOS_ADMIN_EMAIL (in .env, or in front of the install command), admin@freeqos.local by default.
• Password: drawn at random (Xk7pQ-m2RtW-..., about 114 bits, without look-alike characters), never written to the log. install.sh prints it at the end. It is also kept in data/first-admin.txt (readable only by the service), and that file is deleted as soon as the password is changed:

sudo docker compose exec app cat data/first-admin.txt

curl -fsSL .../install.sh | sudo FREEQOS_ADMIN_EMAIL=noc@example.com sh

This works the same with a plain docker compose up or on Kubernetes: nothing to run by hand. Open http://<freeQoS-IP>/ (or :8000), log in, change the password from the account menu. The other accounts (Viewer, Operator, Administrator) are created in Settings › Accounts.

Command line, in the container: python -m app.cli count-accounts prints how many accounts exist, python -m app.cli reset-password --email ... gives an account a new random password (and closes its sessions), and python -m app.cli create-admin --email ... creates the first account if there is none. FIRST_ADMIN_AUTO=false turns the automatic creation off; the first visit then offers to create the account, as before.

7. Give it a domain name and HTTPS (recommended), from the interface:

1. At OVH (or any registrar), in the DNS zone of your domain, add an A record: a sub-domain such as qos pointing to the server's public IP. It takes from a few minutes to a few hours to spread.
2. Open TCP 80 and 443 to the server from the internet. Port 80 must stay open: it is how Let's Encrypt checks the domain, first and at each renewal.
3. Settings › Domain & HTTPS: type the name (qos.example.com), optionally an email for certificate expiry notices, then Save and apply.

The included proxy (Caddy, container freeqos-proxy) obtains the certificate within a minute and renews it on its own. http:// on that name then redirects to https://. The server's IP keeps answering in plain HTTP: it is the way back in if the DNS is broken. Check now tells whether the name points to this server and whether HTTPS answers; the last error from the proxy is shown in plain words. Remove goes back to HTTP only.

Once HTTPS works, close port 8000 to the outside (or set APP_BIND=127.0.0.1 in .env). API: GET /api/v1/public-access, PUT /api/v1/public-access ({"domain", "email"}, Administrator), DELETE /api/v1/public-access, POST /api/v1/public-access/check.

The domain is stored in the database and pushed again to the proxy at each start of freeQoS. The proxy's admin interface (port 2019) is only reachable inside the Docker network, never published. Its certificates live in the caddy_data volume.

8. Add the routers. Devices → Connect a router: name, IP, the account from step 3, role (pop, core or gateway). Test checks the connection without saving anything. After adding, the automatic commissioning described in section 4 runs; follow its report.

9. Let it run in simulation, for at least one full cycle. Check the write plan in Settings: planned queues, skipped links and their reason. Then enable writing.

10. Schedule the backup. For example, once a night:

0 3 * * * cd /opt/freeqos && make backup

Copy the backups/ folder off the server regularly. make backup does not include the instance identifier: save it once with sudo docker compose exec -T app cat /app/data/instance.id > instance.id, or set it with FREEQOS_INSTANCE_ID in .env.

What must be kept

Backup and restore: make backup and make restore (with the timescaledb_pre_restore / post_restore steps).

Kubernetes

freeQoS recognises a pod (KUBERNETES_SERVICE_HOST, /var/run/secrets/kubernetes.io). Three things to set:

• NETFLOW_COLLECTOR_ADDRESS: the address the routers must send to (UDP Service, LoadBalancer or node). Without it, freeQoS sets no NetFlow target rather than announcing the pod IP.
• A persistent volume for data/ (key and instance identifier).
• FREEQOS_INSTANCE_ID for a readable, stable identifier.

RouterOS prerequisites

Updating

1. If two instances drive the same routers, stop one before updating.
2. Run install.sh again (or git pull then docker compose up -d --build).
3. On the first start of a new version, database migrations apply by themselves; the database keeps its data.

4. Routers and inventory

freeQoS only knows the routers it is given. Everything else (subscribers, links, tree, antennas) is discovered from them.

How freeQoS talks to a router

freeQoS uses a single channel: the RouterOS API. No SSH, no SNMP, no script installed on the router.

The protocol. The API is a TCP connection on port 8728 (clear) or 8729 (TLS-encrypted, api-ssl service). It carries the same commands as the router's terminal, as words: /ppp/active/print, /queue/simple/add, /ping. The router answers with lines of key=value fields, one per object. freeQoS therefore reads exactly what a technician would see in the terminal.

The rights. The RouterOS account belongs to a group, and the group grants policies:

Without write, freeQoS runs read-only: measurement, latency and NetFlow (if the export was set up by hand) work, shaping does not. The same result, without touching the router, is one switch in Devices: the per-router writing allowed switch (see The write switch and the account's rights, section 7).

Failures. Each request has a timeout (timeout_s, 5 s by default). Routers are queried in parallel: a router that does not answer misses its read and reports it, the others are read normally.

Declaring a router

Two sources add up:

• The database, through the interface or POST /api/v1/pops/routers. This is the normal case; the password is encrypted with data/secret.key and never comes out of any response.
• A file (ROUTERS_FILE, YAML or JSON) or the ROUTERS='[{…}]' variable. Useful for declarative deployment; a router from the file can be hidden from the interface without touching the file.

The form of Devices › Connect a router sends write_enabled explicitly, unticked by default: a router added from the interface stays read-only until you allow it. The API keeps true as its default so that an existing integration behaves as before. PATCH /api/v1/pops/routers/{id} changes it (write_enabled, with confirm: true and an optional reason to allow writing); a router of the file is switched with PUT /api/v1/pops/routers/file/{name}/write (enabled, confirm, reason). The file can be overridden towards read-only only: a router whose file entry says write_enabled: false cannot be allowed from the interface.

POST /api/v1/pops/routers/test tries a connection without saving anything; on failure, the response gives a hint (port closed, wrong credentials, missing api policy, certificate).

Automatic commissioning

As soon as a router is added, freeQoS immediately runs, in order, the cycles that would otherwise run at their own pace. Each step has 90 s at most.

1. Check the account's actual write rights.
2. Read the PPPoE sessions.
3. Load the plans.
4. Read the ports.
5. Discover the topology (tree, uplink, loopback).
6. Create the CAKE queue types and the subscriber queues.
7. Set up the NetFlow export.
8. Apply the traffic restrictions.
9. Read the DNS cache.
10. Measure latency.

The report (GET /api/v1/pops/provisioning/{router}) then reads the router back and says what is actually in place. If writing is disabled — for this router in Devices, or globally in Settings — or the account lacks write, the state becomes blocked, with the action that unblocks it; steps 6 to 8 are skipped and nothing is sent. A read-only router still goes through steps 2 to 5, 9 and 10: it appears in the tree, its subscribers are measured, and its plan can be read in Settings. Allowing writing on it later runs the commissioning again.

Who is a subscriber on this PoP?

RouterOS has no "subscribers" table. The census therefore starts from the subnets the router serves (/ip/address). Each subnet is classified: point-to-point, routing transit, PPPoE server or subscriber.

Seven sources are then cross-checked; none can erase what another one saw.

The result also states what it does not know: unreadable source, empty subscriber subnet, address outside any known subnet.

Topology

The tree is built from neighbours, shared subnets, tunnels, MAC addresses and, if configured, UISP. It is refreshed every 15 minutes. Everything can be corrected by hand and the correction survives rediscovery: move a box, change a parent, merge two boxes that are the same device, create or delete a link, correct a role.

How the tree is discovered

No single source is enough. freeQoS cross-checks seven:

Three rules make the tree reliable:

1. A router is identified by its loopback, not by its name or an interface address. Two sites configured from the same template often have the same /30 link; only the loopback is unique.
2. The hierarchy comes from the declared role (gateway, core, PoP), not from a guess based on the hardware model.
3. A subscriber's sector comes from a join: the MAC read in caller-id is matched against the stations known to UISP. It is the only way to know which antenna a subscriber goes through, hence its real chain of bottlenecks. Without UISP, only the PoP is known.

MAC addresses are normalised before the join: RouterOS writes AA:BB:CC:DD:EE:FF, UISP sometimes aa-bb-cc-dd-ee-ff; without normalisation, the join would fail silently. When the sector of a subscriber is unknown, its queue is created without a parent rather than under a guessed one: the last mile is shaped correctly, the backhaul contention is not. Attaching a subscriber to the wrong backhaul would be worse than doing nothing.

Where the hierarchy comes from

/ip/neighbor answers a weak question — who sees whom — which is also true of two devices plugged into the same switch. The configuration answers the strong ones, because it is what makes the network:

A box gets its parent from, in order of strength:

1. the parent set by hand in the tree editor — the operator always has the last word;
2. the parent proven by the routing table;
3. the shortest path in the graph, used only where the configuration says nothing (unmanaged devices, discovered neighbours).

Each box is marked "manual", "route" or "inferred", so you know what is established and what is assumed. A multi-homed router (two equal default routes) has no single parent: freeQoS refuses to pick one, says so, and falls back on the shortest path. A ring (two PoPs linked to the core and to each other) is where guessing goes wrong — both paths have the same length — and where the routing table settles it.

On a shared segment (a switch, a management VLAN where MNDP shows everyone), a box without a proven parent gets its most likely link, drawn dashed and marked uncertain, never a mesh. The panel offers to confirm it or correct it in one click.

One device, one box

The same router can be seen several times: as a managed router and as a neighbour of the core, under several management addresses, in IPv4 and IPv6. freeQoS reconciles these views into one box using what cannot change:

• the serial number (/system/routerboard, or the system-id of /system/license for a CHR);
• the RouterOS identity;
• every interface MAC — a neighbour only reveals the MAC of the interface facing it.

Three rules prevent wrong merges. Two declared routers never merge with each other. A MAC claimed by several routers stops identifying them (virtual machines cloned from the same image share interface MACs). The name merges nothing: it is unique only by convention. When identity cannot be proven, the operator decides: Same device as… folds one box into another, Split undoes it. Probable duplicates (same words in a different order, "CCR DS" / "DS-CCR") are flagged with a Merge button, never merged automatically. A box that groups several observations lists them.

How the loopback is found

When the loopback is not declared, it is looked for in the configuration, in this order:

Uniqueness is checked, not assumed: the database refuses two routers with the same loopback, and if discovery finds two anyway, the address is left out of the index with a warning.

A subscriber's CPE is not one more device

A subscriber's box arrives by two paths: a /ppp/active session (the subscriber, with its login and queues) and a /ip/neighbor entry at the end of the PoP's port (a discovered device). freeQoS joins them by equality, never by resemblance: for PPPoE, the session's caller-id equals the MAC announced by the neighbour (rebuilt from an fe80:: link-local address when that is all the neighbour announces); for a routed VLAN, the client's declared address equals the neighbour's address. The subscriber is then counted once. A router of the inventory is never reclassified as a CPE, even if it opens a PPPoE session itself.

The tree follows the inventory

Adding, removing, disabling a router or changing its role starts a new discovery within the minute, whatever path changed the inventory (interface, API, file). A removed router leaves the tree; if the device still exists and a neighbour still sees it, it comes back as an unmanaged device, which is what it has become. An empty inventory erases nothing: that would be a database read failure, not a deletion. The graph never forgets on its own, so that a device briefly invisible (radio fade, reboot) does not disappear; Forget vanished devices removes what you choose.

A known router is never silently absent

The router also keeps its box in the tree, marked "skipped": a skipped PoP is a situation to fix, and it must not look like a PoP that never existed.

A VLAN that carries clients is a site

For a radio operator, a VLAN usually carries a village, a relay or a zone; the router is only its head. freeQoS therefore turns every VLAN carrying at least one declared or seen client into a site of its own. A management, transit or supervision VLAN carries no subscriber and does not become a site. The name comes from the interface, i.e. from what you wrote on the router:

Each site records the router that serves it: this is how shaping still finds the subscribers of a VLAN site on their router.

Clients in the tree: automatic, and editable

Every client has a place in the Network tree, found automatically, and the box shows how it got there (Placed by, in the side panel). In order:

Clients declared by hand and never seen are in the tree too. Clients are grouped per box ("N client(s)"), click to list them.

What an Administrator can change, all undoable:

• drag a client, or a whole group, onto any box: they hang there. Back to automatic place on the client undoes it;
• on a device: This box is a client (choose it) links a device to a client; Not this client refuses a link found by name, for good;
• Attach a client under this box places a client from its name or login.

API: GET /api/v1/topology returns placements (login → box and how) and client_nodes; PUT /api/v1/topology/client-places ({"logins", "node_key"}), DELETE /api/v1/topology/client-places/{login}, PUT /api/v1/topology/client-links ({"node_key", "login"}, empty login = not a client), DELETE /api/v1/topology/client-links/{node_key}.

Static-IP subscribers

A subscriber without PPPoE (fixed IP, routed block, VLAN) is declared in Static clients: a name, one or more addresses or networks, a PoP. It is then measured, limited and scored like a PPPoE subscriber.

A static-IP client announces nothing: no session, no RADIUS plan. The declaration is the only possible source, and freeQoS treats it as the truth, like the router inventory. PPPoE and static subscribers live in the same table, distinguished by their kind, and follow exactly the same path for plans, overrides, boosts and audit.

Several address ranges for one client. A VLAN client usually has a single IP pool. When the same client has several pools on the same VLAN (an extra public block, a service pool), or a block routed behind its CPE, list them in Additional ranges (extra_prefixes in the API). Each item is an IP (10.0.1.5), a block (10.0.1.0/28) or a MikroTik pool range (10.0.1.10-10.0.1.50, split into the exact covering blocks; spaces around the dash are accepted). The main IP address, subnet or range field takes the same input: a range or several comma-separated IPs typed there keep their first block as the client's address and add the others to its additional ranges (editing the address alone with a range adds its other blocks to the ranges already declared). They all share one queue — RouterOS accepts a list as target (target=10.0.0.0/29,10.0.1.0/28) and applies a single max-limit to the whole list — because the client bought one rate; two queues would give it two. The target is canonical (sorted, a block contained in another one dropped), so reading it back in RouterOS's own order is not a change. The queue hangs under a parent link only if that link's segment contains every range; a range claimed by two clients makes both ambiguous, and neither queue is written. An address of any range confirms the client's presence and is never proposed as a candidate. Several clients on the same VLAN are simply declared separately, one record each.

Alone on its VLAN. When a single client is declared on a VLAN (and no PPPoE server listens on it), every network of that VLAN interface belongs to it — all of them when the VLAN carries several pools — plus its declared ranges: its queue targets the whole list, and its traffic is attributed to it in NetFlow.

Census and candidates. The census of a PoP (GET /api/v1/pops/census, see above) confirms declared clients — an address inside a declared block is "seen active" — and lists the addresses that match nothing. GET /api/v1/static-clients/candidates returns those candidates and GET /api/v1/static-clients/candidates/diagnostic the reason each ARP line was set aside. A candidate is never turned into a subscriber automatically: a printer, a camera or another operator's device leaves exactly the same trace, and nobody can guess the sold rate. Declaring always goes through POST /api/v1/static-clients (or the Add a client form) with a reference and a plan.

Ubiquiti antennas and radio capacity

The capacity of a radio link changes with rain, interference and alignment. freeQoS only knows it by asking the antenna, in one of two ways:

• airOS (BACKHAUL_PROVIDER=airos): each antenna is polled on its local API (https://<antenna>/status.cgi), with no UISP needed. Antennas are added in Devices › Add an antenna, or automatically: when common airOS credentials are given (AIROS_USERNAME, AIROS_PASSWORD, set by the installer), every Ubiquiti radio discovered as a neighbour, with an address, is added and attached to the PoP of the router that sees it. Nothing is ever removed or changed automatically, and a radio already known (same address, MAC or name) is not duplicated.
• UISP (BACKHAUL_PROVIDER=uisp): the UISP controller's API, read-only, which also gives the station → access point attachments used for the sector join.

A declared backhaul is matched to the link that carries it by the physical identity of the radio: its UISP device id or its MAC (uisp_device_id, compared without case or separators). Without it, the match falls back on equal names, and failing that the parent queue keeps the port's negotiated speed — the ceiling of the ethernet cable, not of the radio. BACKHAUL_PROVIDER=mock is a deterministic lab simulator.

Radio health (Devices › Radio health) flags, per access point and per CPE:

Wired or radio: the capacity of each link

The capacity used for a link's parent queue and for load percentages depends on its medium:

• Wired: the declared capacity, or the port's negotiated speed.
• Radio: the capacity its antenna announces live (airOS / UISP).
• Auto (default): the lowest known value.

Saturation risks › wired / radio… (or PUT /api/v1/capacity/media) declares each uplink; DELETE /api/v1/capacity/media/{router}/{interface} goes back to automatic. A radio link must name its antenna.

Empty sites and services waiting for an address

• Empty sites are removed every 10 minutes when they have neither subscriber nor backhaul and their name is declared nowhere. A site declared but still empty (router added, no session yet) is kept.
• Services pushed without an address (MAC only, Preseem style) or before their router is known are looked for every 2 minutes in the routers' ARP and DHCP tables; once found, they become full subscribers — placed, shaped, visible.

5. Measurements: throughput, latency, QoE

Throughput

Byte counters are read through the RouterOS API, then turned into rates by the difference between two reads.

Two safeguards reject absurd values. A counter going backwards (restarted session) does not produce a spike. A rate above MAX_PLAUSIBLE_BPS (100 Gbit/s) is discarded.

How a rate is computed

A router never gives a rate. It keeps counters: the total number of bytes received (rx-byte) and sent (tx-byte) by each interface since it was created. freeQoS reads these counters at regular intervals and divides the difference by the elapsed time.

Example: at 10:00:00 the counter reads 5,000,000,000 bytes; at 10:00:10, 5,012,500,000. Difference: 12,500,000 bytes, i.e. 100,000,000 bits, in 10 s → 10 Mbit/s.

Three details matter:

• Where a PPPoE subscriber's counters are. /ppp/active gives the login, the address and the session uptime, but not the bytes. Those are on the dynamic interface <pppoe-login>. freeQoS makes two reads and links them by name.
• Direction. The router counts from its own point of view: what it receives from the subscriber (rx) is the subscriber's upload, what it sends to it (tx) is the subscriber's download. freeQoS swaps the two.
• Reconnection. When a PPPoE session restarts, the interface is recreated and its counters start from zero. If the session uptime goes backwards or a counter decreases, freeQoS writes no rate for that cycle. A gap in the curve is visible; a fake spike would distort averages and scores.

A static-IP subscriber has no interface of its own: its traffic mixes with that of a VLAN or a port. Its bytes are read from the counters of its queue (/queue/simple, bytes field). Consequence: a static-IP subscriber is only measured once a queue targets it.

The throughput of a link

A link's throughput comes from the counters of the port that carries it, with the same safeguards as subscribers. RouterOS counts per interface, not per adjacency: when a switch sits between the router and several devices, /ip/neighbor sees several neighbours on the same port, and giving the counter to each would multiply the total. Measurements are therefore stored per (router, interface); a link inherits its port's throughput, and the interface shows a shared badge when several adjacencies share the port. A link declared by UISP, without a local port, has no counter and says so.

Direction. rx and tx stay those of the router: what it sends to the device opposite, and what it receives from it. Depending on whether the neighbour is upstream (gateway) or downstream (sector), the same tx is upload or download. The link table shows both directions without guessing; the network tree orients them towards the child (↓ = download).

Two time scales. History comes from collection (every 10 s). For "how much is going through now", the live measure calls /interface/monitor-traffic on the router, a read-only command; if it fails (version, rights, virtual port), the last collected value is returned with the reason.

Reset queues: every client back to Automatic

Devices › Reset queues deletes every freeQoS queue of the router and lays them down again from the plans. Every client of that router (sessions on it, static-IP clients, and the clients of its VLAN sites) goes back to Automatic: its mode, boost and forced limit are removed, it is back on its plan, and its Activity says so (queues reset on <router>). A bandwidth schedule that targets the client applies again at its next window.

A client whose usage stays well over its limit (25 % and more) is shown Over its limit, not "at its limit": the router is not holding that limit (queue missing, removed by hand on the router, or bypassed by FastTrack). Reset queues lays it down again.

When the queue does not see the traffic

A client's throughput is read, in this order, from its queue (what passed, after the cap, both ways), from its interface (the PPPoE interface, or the VLAN when it is alone on it), and from NetFlow. Both router counters are read at every cycle and compared:

• a queue that stays flat (under 2 kb/s, or under 5 % of the interface) while the interface carries traffic (over 64 kb/s) is blind, not capping: the interface takes over;
• when no router counter moves but NetFlow sees the client's traffic, NetFlow gives the throughput.

The usual cause of a blind queue is FastTrack on the router (/ip firewall filter with action=fasttrack-connection): fasttracked packets skip simple queues, so the queue neither counts nor caps them. Another cause is traffic that does not cross the queue's router. The client's page shows it in Client details › Measured by, with the reason, and the container log says Mesure de <client> par interface : .... To have the cap applied too, exclude the clients' traffic from FastTrack, or disable FastTrack.

Latency: the probe

A subscriber's latency is the round-trip time measured from its PoP to its address. It goes neither through the core nor through freeQoS: the router does the pinging.

How a ping measures latency

The router sends a small ICMP echo request packet to the subscriber's address. The subscriber's CPE answers with an echo reply. The time between sending and the reply is the RTT (round-trip time).

A single ping means nothing: one packet may wait behind a download, another may go straight through. freeQoS therefore sends 5, 200 ms apart, and keeps:

• the median (the value displayed): it ignores a single very slow ping;
• the minimum and the maximum;
• the jitter: the variation from one ping to the next, which hurts voice;
• the loss: the share of pings left unanswered.

Why from the PoP. The ping leaves from the router serving the subscriber, not from the freeQoS server. It therefore measures the last segment, the one the operator controls and that decides the experience: radio, CPE, queue. A ping from freeQoS would add the core and the management network, unrelated to what the subscriber experiences.

Why a round-robin. Pinging 2,000 subscribers every 30 s would load the routers. Each cycle takes 20 subscribers per PoP, and the next one resumes where the previous one stopped. PoPs are probed in parallel.

Three choices make the measurement faithful.

VRF, in two sentences. A VRF is a separate routing table on the same router: subscriber routes can live in CUST-INET while the main table serves management. A packet only sees the routes of the table it leaves in.

DSCP, in two sentences. Every IP packet carries in its header a 6-bit label stating its class of service. The value 46 (Expedited Forwarding) means "voice, send first", and queues that honour it serve it before the rest.

1. Ping in the subscriber's VRF. If subscriber routes live in a VRF (for example CUST-INET), a ping without a table leaves through the main table, goes up to the core and comes back: 700 to 900 ms instead of 2 ms. freeQoS therefore picks the table from the most specific route to the subscriber:

1. a connected route first;
2. otherwise a route that does not point to the upstream gateway;
3. a VRF is preferred over main.

The parameter sent is vrf=, falling back to routing-table= for versions that do not know it.

2. Priority ping. The probe's packets carry DSCP 46 (EF). CAKE puts them in the Voice tin, with its default setting (diffserv3) as with diffserv4. They do not queue behind the subscriber's traffic: the latency measured is that of the path, not that of a subscriber saturating its plan. Only CAKE_DIFFSERV=besteffort cancels this effect. If the router refuses the DSCP parameter, the ping is sent again without it.

3. Slow fallback. If the median exceeds the interval between pings with at least 50% loss, the subscriber is re-tested with 3 pings 1 s apart for 10 minutes. This avoids counting merely late pings as lost.

When latency stays empty

A subscriber that has never answered is not a degraded subscriber: its CPE often filters ICMP. It is flagged ever_answered=false, excluded from the score and from the QoE loop, and the interface explains why. The Find the cause button (GET /api/v1/rtt/diagnose) replays the probe by hand and returns a verdict:

The response also contains routing_table, the route_candidates and a control ping to the gateway.

Latency by segment

Executive › Where the delay comes from splits latency into three segments, measured from the same router with the same method (a series of pings, median kept with min, max, jitter and loss):

If the internet segment is much higher than the next hop, the delay is outside your network. GET /api/v1/latency returns the three segments per router; GET /api/v1/latency/clients returns the latency each subscriber lives.

Live check of one subscriber

On a subscriber's panel, Measure on the router now reads its PPPoE interface and its queue live for two seconds, adds the NetFlow rate and the last recorded sample, and returns a verdict that says where throughput is lost, if it is (GET /api/v1/subscribers/{id}/live). It is the quickest way to compare what the interface shows with what the router sees.

Bufferbloat

Bufferbloat is the latency that load adds. freeQoS computes it by crossing the RTT and the rate of the same sample: latency when the link is loaded, minus latency when it is not. No dedicated test is run.

Why bufferbloat exists

Every device (CPE, radio, router) has a buffer to absorb bursts. When the link is full, packets pile up in it and wait their turn. Manufacturers size these buffers for throughput, not for latency.

Example: a 1 MB buffer on a 10 Mbit/s link. When full, it holds 8 Mbit, i.e. 0.8 s of waiting for the last packet in. A video call whose packets sit behind a download takes those 800 ms.

An idle latency test does not see it: the buffer is only full under load.

How freeQoS computes it

Each collection cycle writes one sample per subscriber: its rate and its last RTT. Over the requested window:

1. Idle latency = the 20th percentile of all RTTs. This is the observed floor, without being fooled by a single low value.
2. Loaded slice = the samples whose rate is at least the 60th percentile of the subscriber's rates. If the subscriber's rate is constant, the cut is at the median.
3. Loaded latency = the 90th percentile of the RTTs in the loaded slice.
4. Bufferbloat = loaded latency − idle latency, never negative.

At least 4 samples are needed, including 2 in the loaded slice. Otherwise freeQoS gives no grade: showing A+ for a subscriber who never downloaded anything would be a false good result.

QoE score (0 to 100)

The score is the minimum of two components:

• Idle latency: 100 − 0.6 × (RTT − 10 ms). Below 10 ms, no penalty.
• Bufferbloat: interpolation between the points 0 ms → 100, 5 → 90, 30 → 80, 60 → 65, 100 → 50, 200 → 25 and 400 → 0.

The weakest link sets the score. A satellite link at 600 ms stays bad even without bufferbloat; a link at 8 ms that climbs to 400 ms under load is not excellent.

Each score states its basis (basis):

• composite: both components;
• load: bufferbloat only;
• latency: RTT only, a mere substitute when no load can be correlated.

Display thresholds: ≥ 80 green, ≥ 50 amber, below that red.

"At plan limit"

A subscriber filling its plan has high latency by construction. When the probe is not prioritised, its samples at the limit are set aside and the At plan limit badge explains it. When the probe is prioritised (DSCP 46 and CAKE), the measurement stays accurate even at the limit: nothing is set aside.

6. NetFlow traffic

Counters say how much a subscriber consumes. NetFlow says what and where to.

How NetFlow works

The problem. There are two ways to know what traffic is made of. The first is to copy every packet to a probe (port mirroring): on a 10 Gbit/s internet edge, that is 10 Gbit/s more to carry. The second is to ask the router to summarise what it sees. That is NetFlow: a few tens of kbit/s to describe thousands of conversations.

A flow. For NetFlow, a conversation is a flow: all packets with the same source address, the same destination address, the same ports and the same protocol. A video call gives a few flows; a web page, a few dozen.

The cache. The router keeps one line per ongoing flow in memory. For each packet, it adds its bytes to the flow's line. It sends nothing until the flow has expired:

• inactive timeout: no packet for 15 s, the flow is considered finished and exported;
• active timeout: a flow still in progress is exported anyway every minute, then its count starts again from zero.

RouterOS's default active timeout is 30 minutes: an hour of streaming would show up as two records, half an hour late. freeQoS therefore sets active-flow-timeout=1m and inactive-flow-timeout=15s on each router.

The export. Expired flows leave in UDP datagrams towards the collector. UDP resends nothing: a datagram that does not arrive is lost for good. This is why the collector listens permanently and does no slow processing while receiving.

The formats.

In practice: after a freeQoS restart, v9 data is ignored until the router resends its templates, which it does regularly. A few minutes of traffic may be missing; this is normal and counted.

Sampling. A very busy router may only examine one packet in N. It announces it, and freeQoS multiplies volumes by N.

Step 4 is the heart of the collector: it turns "45 MB between two addresses" into "45 MB downloaded by this subscriber".

Collector

freeQoS listens on UDP port 2055 (NETFLOW_PORT) and decodes NetFlow v5, v9 and IPFIX. Flows are aggregated in memory then written every 60 s (NETFLOW_FLUSH_INTERVAL_S).

Four counting rules:

1. Direction comes from the subscriber, not the interface. A flow whose destination falls in a subscriber's block is download for it; one whose source falls in it, upload. Rewiring therefore distorts nothing.
2. The vantage point is part of the key. The same byte crosses the PoP then the internet edge, and both export it. Counters are kept per vantage point, never added up.
3. An unknown address is not a subscriber. It goes into the list of "hosts seen", used only to help declare subscribers.
4. The other end is kept. The remote address of each flow is recorded to answer "who watches which service".

Attribution, in detail

freeQoS builds an index of subscriber blocks: each PPPoE subscriber's address (/32) and the networks of static-IP subscribers (/29, /30…). For each flow, it looks up the most specific block containing the source, then the destination. Blocks are sorted by prefix length: a lookup costs a few comparisons, whatever the number of subscribers. An internet edge sends tens of thousands of flows per minute; a slow lookup would lose datagrams.

Vantage points

The same byte crosses several routers, and each can export it. freeQoS distinguishes two vantage points:

Counters are kept per vantage point and are never added up. Consumption (Traffic page, /usage/v1 API) is read direction by direction: NETFLOW_ACCOUNTING_VANTAGE=auto (the default) takes, for each subscriber and each window, the larger of the two vantage points for download and, separately, the larger for upload. It is the same byte seen twice, so the larger is the right figure and the sum would be wrong. edge or pop force a single vantage point for both directions. For the list of conversations, freeQoS keeps a single source per conversation and per direction: the one closest to the subscriber.

Both directions

Each direction is measured on its own, from end to end. Three situations used to lose one of them:

Translated addresses. RouterOS puts the post-NAT addresses and ports in its v9 and IPFIX records when the nat-src-address, nat-dst-address, nat-src-port and nat-dst-port fields of /ip/traffic-flow/ipfix are on. freeQoS turns them on itself when they are off (one set, under the same write switch as the rest of the export). A download addressed to the public address is then tied to the client named by its translated destination.

Pairing without NAT fields. For each upload towards the internet, freeQoS remembers (remote address, remote port, protocol, client port) → subscriber, kept 10 minutes after its last upload (the oldest go first when 100,000 are held). A download coming back from that remote address and port, towards that client port, belongs to that subscriber. When the router changed the client port, pairing without the port is tried only towards an address already recognised as the NAT's public address, and only when a single subscriber talks to that remote end: two subscribers on the same server, and freeQoS does not guess. A download that arrives before its upload in the same window is replayed when the window closes. GET /api/v1/netflow/status counts nat_translated (tied by the NAT field), nat_matched (tied by pairing) and nat_unmatched (looked like a NAT return, no upload to name it), and gives directions: the bytes tied to a subscriber per vantage point and per direction since start-up.

The warning on the Traffic page. When the internet exit sees more than 1 MB of upload and less than a fifth of that in download, the page says that it translates your clients' addresses, and what is counted meanwhile.

Rate of a flow

A record carries a volume and a duration (first → last packet). The rate is the volume divided by the actual duration. With RouterOS's 30-minute timeout, dividing by an assumed minute showed a rate thirty times too high; this is why the duration is always read from the record.

Usage families

Traffic is classified into broad families by service port: the smaller of the two ports, because the client picks its port at random above 32,768 and the server listens below.

Encryption sends Netflix, YouTube and the rest of the web through port 443: the port cannot tell them apart, and the family is honestly called "web". What distinguishes Netflix from YouTube is the name of the remote address (below).

What is left out of the list of conversations

• Management traffic (SNMP, BGP, BFD, RADIUS, syslog, NetFlow, Winbox, RouterOS API): the network administering itself, not a subscriber.
• DNS queries (ports 53, 853, 5353): asking 8.8.8.8 for a site's address is not "going to 8.8.8.8". Their volume is still counted.
• Private addresses: two subscribers talking to each other are not an internet destination for either of them.

At most 2,000 destinations are kept per 60-second window, so that a subscriber running p2p does not trigger a burst of writes. A destination not seen for 7 days is forgotten; its name is kept.

Export set up automatically

freeQoS configures the export on each router itself, every 10 minutes if needed (NETFLOW_EXPORT_AUTO, NETFLOW_EXPORT_INTERVAL_S):

/ip/traffic-flow set enabled=yes interfaces=all active-flow-timeout=1m inactive-flow-timeout=15s
/ip/traffic-flow/target add dst-address=<collector> port=2055 version=9
/ip/traffic-flow/ipfix set nat-src-address=yes nat-dst-address=yes nat-src-port=yes nat-dst-port=yes

The last line is only sent when one of those fields is read as off: without them, downloads behind NAT cannot be tied to a client (see Both directions). A router whose RouterOS has no /ip/traffic-flow/ipfix menu is left as it is.

The collector address is not guessed. It is the local address the system would use to reach this router (a UDP socket opened towards it, without sending a packet). It is therefore correct even on a server with several interfaces.

Special cases:

• Container (Docker, Podman, Kubernetes): the local address would be the container's, unreachable from the routers. Without NETFLOW_COLLECTOR_ADDRESS, freeQoS sets no target and says so.
• Target towards another collector: never touched. A third-party tool already receiving the flows keeps receiving them.
• Stale target: a target carrying the mark of this instance and pointing to an old address is removed.

Writing goes through the same path as queues: simulation by default, circuit breaker, audit.

Exporters and vantage points

A router whose export was set up by freeQoS is declared as an exporter at the same time, with its vantage point deduced from its role (gateway → edge, otherwise pop). An exporter that sends without being declared still appears, marked unknown: a badly configured PoP must show up, not disappear. Traffic › Advanced: NetFlow exporters declares by hand an exporter that is not one of your routers, with its vantage point and its sampling rate. Declaring sampling matters: a router sampling 1 in 1,000 reports a thousandth of the real traffic, and nothing else would show it.

"No datagram received": the causes

The Traffic page names the cause and the action:

The most misleading one is the path: without the /udp suffix, Docker publishes TCP, the router exports, the collector listens, and nothing meets, without an error anywhere. The repository's docker-compose.yml publishes 2055/udp, and a test locks it.

Orphan records

orphan_records in GET /api/v1/netflow/status counts v9/IPFIX data that arrived before its template. A counter that rises then stabilises is normal (after a restart, the templates come back within minutes). A counter that keeps rising means the exporter never sends its templates.

Which addresses are subscribers, which are infrastructure

• NETFLOW_CUSTOMER_NETWORKS (default 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10 (CGNAT), fd00::/8): where subscribers live. If your subscribers have public addresses, add their blocks, otherwise their conversations are taken for transit.
• Infrastructure addresses are learnt automatically (the freeQoS server, the declared routers and their addresses, the exporters); NETFLOW_INFRASTRUCTURE_NETWORKS adds what the inventory does not know (a transit link, a monitoring network). A client pinging one of your routers is shown as reaching your network, not an unidentified internet address.

Naming addresses

NetFlow only carries addresses. When a subscriber reaches an address never seen before, it is recorded "to be named". A separate loop then names it, in batches of 40 every 30 s, most recent first. Naming may need a network request, hence a wait: doing it while receiving would block the collector. An address reached ten seconds ago is named on the next pass.

An address without a reverse name is asked again 3 times at most. A name read from the DNS cache is no longer attributed after 24 h: the address may have changed owner.

A CDN is not streaming. Cloudflare, Akamai or Fastly serve a recipe site, a video or a software update alike. They are classified cdn, never streaming, so that a restriction placed on them is a conscious choice. The interface shows the source of each name (catalogue, reverse name, registry).

Privacy. RDAP and web-service geolocation are enabled by default. They send to third parties the addresses your subscribers visit. To avoid it:

• IPFINDER_GEOIP_DB points to a local MaxMind database (.mmdb): same result, no outgoing call;
• IPFINDER_GEOIP_ENABLED=false and IPFINDER_RDAP_ENABLED=false turn these two sources off (changeable live);
• the catalogue, the DNS cache and reverse names are enough to recognise the large services.

Each source is isolated: a resolver that breaks, a registry that rate-limits or a geolocation service that fails never costs the verdict the others gave. The reverse name beats the block: an Open Connect cache hosted at your premises is in no published block, yet it carries the most traffic. An address with no reverse name is still marked resolved — "this address has no name" is an answer, and most of the internet is in that case.

What the Traffic page shows

Searching conversations. Four filters combine — free search (client address, login, remote address, reverse name, organisation, service), PoP, category, usage family — and every value in the table is clickable to filter on it. The lists only offer values that exist in the data shown. The unidentified share is shown like the others: a page that only showed what it can name would hide the largest unknown.

A machine without a subscriber record counts too. "This address reached that one" is the observation; attaching it to a subscriber is an interpretation, which may be missing (monitoring station, camera, router). Such lines appear under the client address, marked not declared.

Volume over time per subscriber: GET /api/v1/netflow/subscribers/{id}/series. Live connections (GET /api/v1/netflow/connections) read the collector's in-memory window, the only truly live view: it empties at each write and fills up again — that is not a failure.

Traffic restrictions

A restriction targets a catalogue service for one or more subscribers. Two actions:

Every 5 minutes (RESTRICTIONS_INTERVAL_S), the address list of each rule is recomputed and only the difference is pushed. A new Netflix address seen by NetFlow therefore joins the list by itself.

No rule is ever created automatically: throttling a service is a business decision. GET /api/v1/traffic-rules/{id}/preview shows what a rule targets today. IPv6 is not installed yet: IPv6 prefixes of a rule are set aside and the plan says so.

What a rule contains. A name; an effect (block, or limit with download and upload caps in kbps, Mbps or Gbps); its targets — catalogue services, categories (streaming, social networks, gaming, voice / video, cdn, cloud, updates, dns, messaging) and hand-entered prefixes; optionally a protocol (tcp, udp, icmp) and service ports (443, 6881-6999); and for whom: every client, some sites (PoP or VLAN site), or some clients.

A rule is a criterion, not a snapshot. Its address set is recomputed at each pass from two sources: the published blocks cover servers no client has reached yet, the discovered addresses cover what lies outside them (a cache hosted at your premises, a server rented elsewhere). An address already inside a kept block is not added: it would change nothing and lengthen a list the router walks through for every packet (RESTRICTION_ADDRESS_LIMIT).

Writing. Saving an enabled rule, editing it or re-enabling it installs it on the routers immediately (still subject to the write switch, the circuit breaker and the audit). Suspending a rule lifts it at once; deleting it lifts it too. A rule without any criterion (no service, category or prefix) is refused: it would target the whole internet, and on an internet edge would cut the network. The Last applied column is what distinguishes a rule saved from a rule installed. POST /api/v1/traffic-rules/apply reinstalls everything (dry run by default).

7. Plans and shaping

This is the only part of freeQoS that writes to the routers. It always follows the same path: compute a plan, show it, apply it, with several safeguards in between.

How shaping works

The queue always forms at the bottleneck. When a device receives faster than it can transmit, it stores the excess in a queue. That queue appears at the slowest point of the path: often a sector's radio or the subscriber's CPE. Their buffers are large and sort nothing: a video call waits there behind a download. This is the bufferbloat of section 5.

The idea of shaping. Traffic is deliberately limited slightly below the bottleneck capacity, at a place we control: the PoP router. The PoP then becomes the slowest point. The queue forms there, in a CAKE queue that keeps it short and shares it fairly. The radio's buffer stays empty. About 10% of throughput is given up (SHAPING_SAFETY_FACTOR=0.90), and latency stays low even when the sector is full.

How a limit acts on TCP. Most traffic (web, video, downloads) uses TCP, which speeds up as long as nothing is lost. When the subscriber exceeds its limit, the extra packets wait in the queue. If the wait lasts, CAKE drops one (or marks it, with ECN). The TCP sender understands it is going too fast and slows down. The rate thus settles on the limit, without a growing queue.

What CAKE does

CAKE (Common Applications Kept Enhanced) is the queueing algorithm freeQoS uses. It combines several mechanisms:

How queues nest

RouterOS queues form a tree:

• A sector's parent queue caps the sum of its subscribers' traffic at 90% of the link's measured capacity.
• Each subscriber queue, attached to that parent, caps its subscriber at its plan. It has two limits, max-limit=upload/download, and two CAKE queue types, one per direction.

A subscriber alone on a quiet sector gets its full plan. When everyone pulls at once, the parent queue shares the available capacity. If radio capacity drops (rain, interference), the parent queue drops on the next cycle, and the queue stays at the PoP.

Where a subscriber's plan comes from

The plan belongs to the subscriber, not to the PoP: a PoP has a capacity, not a plan. It is resolved in this order:

1. The plan written for this subscriber, pushed through the API (billing, Preseem integration) or entered on the Plans page. The last write wins.
2. A subscriber pushed without a rate gets the default plan (DEFAULT_PLAN_DOWN_MBPS / DEFAULT_PLAN_UP_MBPS, 100/20).
3. A subscriber that is only detected has no plan: it is observed, never throttled to a rate nobody sold, unless DEFAULT_PLAN_FOR_DETECTED_CLIENTS=true.

Deleting a subscriber's plan removes its queue on the next cycle.

What is installed on the router

Two queue types: freeqos-cake-up and freeqos-cake-down. Their CAKE options come from the settings:

One parent queue per link (freeqos-parent-<link>): radio backhaul or sector. Its rate is max(5 Mbit/s, measured capacity × 0.90) (SHAPING_SAFETY_FACTOR, SHAPING_FLOOR_MBPS). The queue thus forms in CAKE, where it is controlled, rather than in the radio's buffer.

One queue per subscriber:

• Target: the subscriber's address (target=10.20.0.10/32), never the <pppoe-…> interface. The interface is recreated at each reconnection, and RouterOS reverses the direction of max-limit on it.
• Parent: the link whose network contains the subscriber's address; the most specific wins.
• Write order: parents first. RouterOS refuses a child whose parent does not exist.

Every object carries the comment freeqos:managed instance=<id>.

Reconciliation

Every 2 minutes (SHAPING_RECONCILE_INTERVAL_S), freeQoS reads the queues in place, computes the desired state and sends only the difference. A queue that is already right gets no command. Only the field that changes is rewritten: a plan change only touches max-limit.

Safeguards

Manual adjustments

• Rate override (PUT /api/v1/shaping/policies): sets the rate of a link or a subscriber, above the computed one.
• Boost (POST /api/v1/shaping/boosts): a higher rate for a duration; it is removed when it expires (checked every 30 s).
• Dry run (POST /api/v1/shaping/plan): the commands that would be sent, without sending anything.

Units. Every rate field has a kbps / Mbps / Gbps selector: a subscriber capped at 512 kbps is typed as such, not as 0.512 Mbps, and displayed as "512 kbps". Internally everything is converted once, at the input, to Mbit/s. The API accepts max_down_mbps, max_down_kbps or max_down_gbps (same for upload, and down_* / up_* for a boost); two units for the same direction are refused as ambiguous.

Which rate wins. From strongest to weakest: a running boost, a permanent override (a hand-set rate, or the client's bandwidth mode), the bandwidth schedule in its current time slot (see below), the subscriber's plan. A boost goes over the override then disappears; it does not erase it. A schedule never undoes an override: a decision taken on this subscriber (capped for non-payment, for instance) is not lifted because the night begins.

Boosts. A duration (1 minute to 7 days), then either a multiplier of the plan (the interface offers ×2, ×3 and ×5; the API accepts more than 1, up to 50) or explicit rates, and a reason. It is written immediately if writing is allowed and expires by itself: a job checks expiries every 30 s and brings the queue back to its normal rate — RouterOS knows nothing about the duration. A boost without an expiry is refused: it would be an override in disguise that never goes away.

A rate set by hand is written at once. Setting a subscriber's or a link's rate writes the corresponding queue immediately (the full plan of the router, restricted to that queue), and the reply says what was written, on which router, or what prevented it (apply_now=false only records the intention).

Bandwidth modes (Backup, Night…)

A bandwidth mode is a named rate given to a client in one click, from the Clients page: Backup when the backhaul is degraded, Extreme backup for a crisis or non-payment, Night... The operator picks a name in a list instead of typing rates (Modes, or /api/v1/bandwidth-modes).

• Rate: fixed (rate_kind=fixed) or a share of the client's plan (percent: 200 = twice the plan). A share needs the client's plan; a client without a known plan can only get a fixed mode. In the form, the unit is a switch: kbps, Mbps or % of plan. A rate typed in kbps is stored in Mbps (512 kbps = 0.512 Mbps), and shown again in kbps when the mode is edited.
• Automatic is not a stored mode: it is the absence of a mode. The client follows its plan and, when it has one, its bandwidth schedule — its rate then changes with the hour on its own.
• Where it sits: a client's mode is its permanent override (shaping_policies.max_down_mbps/max_up_mbps, with mode_id and mode_name). It is therefore above the schedule (a client in Backup stays in Backup when the night begins) and below a running boost. Back to Automatic removes the override and keeps a running boost.
• Modes that stop boosts (disables_boost, API only): entering the mode clears the running boost, and a new boost is refused (409 Boost is unavailable in <mode>. Change the mode first.). The form no longer offers this option: a mode saved from the form has it off.
• Its clients: the mode form itself has a list of clients to tick (Clients in this mode), with search and a site filter: saving the mode also puts the ticked clients in it and puts the unticked ones back to Automatic — for a new mode as for an existing one. On the Modes board, Add or remove clients on a mode opens the same list.
• Editing a mode's rate re-applies it at once to every client in it. A mode given to clients cannot be deleted (409): put them back to Automatic or in another mode first.
• Writing: like a hand-set rate, a mode change writes the client's queue at once (when writing is allowed) and the reply says what was written.
• Changing a client's plan keeps its mode and its boost: only a manual limit (an override without a mode) is lifted, so that the new plan takes effect. A mode expressed as a share of the plan follows the new plan at once.

Client actions (POST /api/v1/clients/actions, {"logins": [...], "action": "mode" | "boost" | "stop_boost", ...}) act on one or several clients. The reply gives a result per client (succeeded, failed, results[]): a partial failure never looks like a complete success. It needs the Operator level, for one client as for several.

Boost or temporary plan, from the Clients page. On one or several selected clients (or from a client's page):

• Duration: a quick choice (30 min, 1 h, 4 h, 1 day, 7 days), a custom value in minutes, hours or days (up to 365 days), or until stopped (boost_until_stopped: true): it runs until someone clicks Stop boost (action: "stop_boost"). Internally it still has an expiry, five years away, so that the expiry check and the planner treat it like any boost; the interface shows it as "until stopped".
• Rate: the client's current rate multiplied by any factor above 1 (up to ×50, boost_multiplier). The current rate is the one in force without the boost, by the same rule as the planner: its mode or manual limit, else its schedule slot, else its plan. A client held at 550 kbps by a mode gets ×1.5 = 825 kbps, not ×1.5 of its base plan. The dialog shows the current rate and the result before applying. Or a temporary plan: explicit download and upload rates (boost_down_mbps, boost_up_mbps), higher or lower than the plan. At the end of the duration the client goes back to its plan, its schedule or its mode on its own.
• When the boost ends (stopped, or its time is up), the client goes back to exactly what it had before: its mode, its schedule or its plan. The boost never erases the mode.
• The log records what and for how long ("x1.5 of the current rate (550 kbps -> 825 kbps down, ...) for 4 h", "temporary rate 5 / 2 Mbps for 3 days", "... until stopped").

Clients page, map, alerts and reports

Clients page. Four cards on top: Clients (and the number of sites), Connected (with a bar, green above 80 %, orange from 50 %, red below), In a mode, Boosts. A card is also a filter: tap it to list those clients. For each client, Usage now is a bar of its download rate against its limit, with a word: Quiet (under 10 %), Normal, Busy (60 % and more), At its limit (90 % and more). The IP address is not shown in the list: it is on the client's page (search by IP still works).

Made for hundreds of clients (20 sites of 20 clients): search, filters by site, connection and mode, sort (name, site, not connected first, highest usage), and pages of 25, 50, 100 or 200. Sorted by site, each site gets a header with its count, its connected clients and a Select the site button. The box at the top of the list selects every client matching the filters, on every page.

• Traffic (with clients selected): the traffic of the whole selection as a chart, then each client with its own small chart, its current rate and its volume, over 1 hour, 24 hours or 7 days.
• Export: the list as filtered, every page, in two formats. Excel (.xlsx): a formatted workbook — coloured header, columns at the right width, filters, frozen header row, real numbers and dates, status coloured (green online, red offline, grey never seen), use of the limit coloured, and a second sheet summing up each site. CSV: a plain table whose separator follows the browser's language (; and a decimal comma in French, so that Excel opens it in columns). Columns: client, status, last seen, site, kind, IP address, mode, what sets the limit, boost and its end, download and upload now, use of the limit, limit, plan, latency, session.
• + Add a client (Administrator): declares a static-IP or VLAN client (address, subnet or range, additional ranges, plan, CPE MAC) and lists the declared clients and the clients by VLAN. It replaces the former Subscribers tab, whose content is now on this page.

Client page. Status (online or offline, since when), Usage now (gauge and word against its limit), Limit (and where it comes from), Experience (score out of 100 with a word, the latency and the slowness under load — or the latency alone when no score is measured). Then the usage chart, a Diagnosis, the mode and boost, the connection (IP, site, session), What it uses and the recent changes.

The Diagnosis answers "why is it slow?" in three lines, each with a coloured dot (green, orange, red; grey when not measured, with the reason):

• Radio signal of the client's antenna (CPE), found by its MAC (PPPoE caller-id, or the CPE MAC declared for a static client) among the antennas freeQoS reads: Good from −65 dBm, Fair down to −75 dBm, Weak below, with the access point, the SNR and the link quality.
• Its site: the current load of the site against the radio capacity of its backhaul: OK, Busy from 70 %, Saturated from 90 % — every client of the site is then slowed, not only this one.
• Limit on the router: whether the cap is really held (Applied), or NOT held and why (FastTrack, a queue hidden or disabled), from the background check of the routers.

What it uses: the volume downloaded and uploaded over 24 hours and 30 days, and the five main uses over 7 days (streaming, social networks, web, calls, gaming...) from the traffic flows. All of it comes from one call, GET /api/v1/clients/{login}/health, open to every level.

Map (#/map, every level). The sites and the clients on an OpenStreetMap map. A site is a pin: its size follows the number of clients, its colour the share connected (green 80 % and more, orange 50–80 %, red below). A client is a dot (green online, red offline, grey never seen): at street zoom (or when its site is selected), each client appears at its own position — a small square, linked to its site — or, without a position, in a ring around its site. Moving is smooth: drag (the map keeps a little momentum when released), pinch with two fingers on a phone, the mouse wheel, the + / − buttons, a double click, or the arrow keys. A search box finds a site or a client (by name or IP). Tap a site: its counts, its clients (offline first), Show its clients, PDF report. Tap a client: its status, site, mode, position, Open the client.

An Administrator gives a position (Position / Place it) in three ways: type or paste coordinates (13.5137, 2.1098, or a Google Maps / OpenStreetMap link), use the GPS of the phone (on site, over HTTPS), or tap the map. Remove from the map takes it off. API: GET /api/v1/site-locations, PUT /api/v1/site-locations/{site} and GET /api/v1/client-locations, PUT /api/v1/client-locations/{login} ({"latitude", "longitude"}), and their DELETE. The map tiles come from tile.openstreetmap.org: without internet, the pins stay usable on a plain background.

Alerts and error codes. Every alert carries a stable code, the clients concerned and what to check:

PDF report. Alerts › PDF report (all sites, or the site chosen in the list) and Map › a site › PDF report (audit of one site) download a PDF made in the browser (no server, no internet needed): the counts, every alert with its code and what to check, the sites, the offline clients with their IP and last contact, for a site all its clients, and the list of codes.

Editing a client, and adding one by hand

Discovery and hand entry live side by side; neither erases the other.

• What discovery gives (PPPoE sessions, the static inventory): login, IP address, site, session, traffic. It is refreshed at every cycle and is not edited by hand for a PPPoE client: the next session would rewrite it.
• What only a person knows, entered with Edit client on the client's page (Operator and above): name, phone, email, address, CPE MAC, note. It is kept in its own table (client_profiles) and never touched by discovery. The CPE MAC entered here takes precedence for the radio diagnosis, when the PPPoE caller-id does not give one.
• A static-IP client also has its network part editable there by an Administrator: IP or subnet, VLAN, site.

The client's page shows its IP address in the header (click to copy) and its details in Client details. The list shows the name when one is set, with the login and the IP below it; the search finds a client by its name too.

Add a client (Clients, + button, Administrator) offers two ways:

• PPPoE login: declare a client before it connects: login, site, optionally a name, a plan and the CPE MAC. It shows as never seen until its first session; discovery then joins it by its login and the details entered are kept.
• Fixed IP / VLAN: a client without a session, measured on its address (as before).

Every change is written to the client's Activity. API: GET /api/v1/clients/{login}/profile (discovered facts and details), PUT /api/v1/clients/{login}/profile, POST /api/v1/clients ({"login", "pop_name", "display_name", "cpe_mac", ...}), GET /api/v1/client-profiles.

Ubiquiti UISP (antennas)

Devices › Ubiquiti UISP connects the UISP controller (formerly UNMS), which knows every airMAX / airFiber / LTU antenna of the network. An Administrator gives its address (https://uisp.example.net) and an API token with read access (UISP › Settings › Users › API tokens), then Test the connection and Save. The token is stored encrypted (same vault as router passwords) and never comes back through the API. Unticking Verify the certificate accepts a self-signed UISP.

The section then lists the antennas UISP knows: model, role, IP, UISP site, status, radio capacity down and up, signal and airtime — the potential of each link. Attach a backhaul antenna to its site: its capacity is read every backhaul cycle and becomes the ceiling of the site's queue, like an antenna added by its own address (Add an antenna). API: GET/PUT/DELETE /api/v1/uisp, POST /api/v1/uisp/test, GET /api/v1/uisp/devices, PUT/DELETE /api/v1/uisp/links/{device_id} ({"name", "pop_name"}). The environment variables BACKHAUL_PROVIDER=uisp, UISP_BASE_URL, UISP_TOKEN keep working for a controller declared in the file.

UISP traffic, in the network

Once UISP is connected, freeQoS reads every minute, for each device UISP manages: the throughput of its radio port (or of its busiest port), its radio capacity, its signal, whether it is online, and, for an access point, the stations (CPEs) hanging on it with their MAC, IP, signal and traffic. The last reading is shown in the table (Traffic now: towards the clients, what an AP sends and what a station receives); each row is kept 7 days (uisp_device_metrics, GET /api/v1/uisp/devices/{id}/history?minutes=).

It goes into what freeQoS already shows:

• Network tree. Every UISP device is a box of the tree, and each station hangs on its access point. Where no router port measures the link to a UISP device, the link shows the throughput UISP reads (uisp_rates in GET /api/v1/topology).
• Place it by hand. Place (in the table, Administrator) says under which box a device is connected, and whether it is a client's CPE. Dragging the box in the tree does the same. The automatic placement stays for everything else, and the choice is undone with Automatic.
• Clients. A station whose MAC or IP is a client's gives that client's Radio signal diagnosis. The list of stations of an AP names the client of each CPE.
• Email alerts. An access point, or a device attached to a site, that UISP reports offline is a problem that can be emailed (Settings › Email alerts).

API: GET /api/v1/uisp/traffic (the reading, with each device's box, place set by hand, client and stations).

Email alerts

Settings › Email alerts (Administrator) takes the SMTP account freeQoS sends from: server, port and security (STARTTLS 587, SSL/TLS 465, or none for a local relay), user name and password (stored encrypted, never returned), sender and recipients. Send a test email checks it at once; a failure says why in plain words (login refused, wrong port, host unknown, certificate...). Gmail and Microsoft 365 need an app password.

Every minute the server looks for failures, whether or not anyone has the interface open:

A problem is emailed once, when it has lasted the chosen delay (3 minutes by default), and once more when it is resolved; the problems of a minute go in one email. The section lists the recent problems and whether they were emailed. API: GET/PUT/DELETE /api/v1/notifications/smtp, POST /api/v1/notifications/test, GET /api/v1/notifications/history.

Bandwidth schedules (day, evening, night)

Many operators sell rates that change with the time of day: a plan reduced in the evening peak, opened at night, normal during the day — and switched automatically, on time. A bandwidth schedule (Schedules, or /api/v1/bandwidth-schedules) is a set of time slots, each with the rate that applies during it. Applies to is a segmented control (All, Clients, Sites, Plans); except for All, it opens a list to tick, with search and All / None. Each slot is one card: its name, the hours (18:00 → 23:00), the rate with a % / Mbps / Mode switch, and the days as round pills (tap to turn a day off). The hours are not typed: tap an hour to open a wheel (hours, then minutes by 5), or drag it up or down to move it by a quarter of an hour (up = later, down = earlier); the mouse wheel and the arrow keys work too. Time zone is a menu that starts on the browser's own time zone and shows the time it is there; the list of schedules shows each schedule's next switch in your local time. The rate is either:

• a percentage of the plan (percent: 200 = twice the plan at night, 70 = 30 % less in the evening), which follows every subscriber's own plan without copying it; or
• a fixed rate (down_mbps / up_mbps; a single direction is allowed, the other one keeps its plan); or
• a bandwidth mode (mode_id: Backup, Night... the same modes you give a client by hand). With Applies to › Clients, this puts one or several chosen clients in a mode during the slot. The schedule keeps a reference to the mode, not a copy of its rate: edit the mode on the Modes page and every slot using it follows at once. A mode used by a schedule cannot be deleted until those slots are changed.

Outside every slot, the normal plan applies.

Two slots of one schedule may not overlap — which one would win at 19:00 between "evening 18:00–23:00" and "peak 19:00–21:00"? The overlap is refused when saving, with the day and time where it happens.

One schedule per subscriber. When several schedules target the same subscriber, the most precise one governs it alone: named subscribers, then plans, then sites, then all clients; at equal precision, the most recent. Schedules never combine: the operator can always say, subscriber by subscriber, where its rate comes from. The Clients button of a schedule (GET /api/v1/bandwidth-schedules/{id}/preview) lists the subscribers it governs, their plan and their rate right now, and those a more precise schedule takes away from it.

The switch is automatic. A job re-reads the schedules every 30 s and compares, for each schedule, the slot running now to the one of the previous pass: as soon as a slot starts or ends, the queues are re-planned and written (author system:schedule in the audit), without waiting for the 2-minute reconciliation — which, in any case, writes the scheduled rate too. Saving, suspending or deleting a schedule applies it at once. The same safeguards as reconciliation apply: nothing is written while writing is off, and a scheduled switch never deletes a queue. The oscillation guard does not watch max-limit, so three switches a day are never mistaken for an oscillation. The last switch (when, why, how many writes, on which routers) is shown under the list.

The subscriber list shows a scheduled rate with a schedule badge (the schedule and slot in the tooltip), and the Plans page shows, under each plan, the rate applied right now and the governing schedule.

The shaping map

Settings › Shaping and writing to the routers shows the map, not the commands: where the network is capped, at how much, and where that cap comes from (measured capacity, override, plan, bandwidth schedule, boost, QoE tightening). GET /api/v1/shaping/points returns it, read-only.

Points without a queue are listed like the others: a map that only showed what works would leave the rest to be found nowhere. The raw details stay available under the map: analysis of what exists (GET /api/v1/shaping/state), the plan computed on demand, and the command log.

Where a subscriber queue points, and when it is skipped

The subscriber's address is read on the router when the plan is computed, never taken from the database: a stored address may be one cycle late, and if the subscriber reconnected in between, the pool may have given its IP to a neighbour. It is written in canonical form with its prefix (10.20.0.12/32): RouterOS always rewrites a bare address that way, and sending it bare would produce a difference at every cycle.

Each skipped subscriber is listed with its reason. Automatic writes never delete: boost expiry and the immediate write of a cap add queues, they never remove any. Without this rule, a momentary /ppp/active failure would make everyone look offline and erase the queues of a whole PoP. Only a plan read in the interface (or Reset queues) can delete. SUBSCRIBER_QUEUE_TARGET=interface restores the old behaviour (queue on the <pppoe-…> interface) for a network that depends on it; it is not recommended.

Are the caps actually held?

Three different questions are often confused: what freeQoS wants to install (the plan), what it wrote (the log), and what the network applies. Only the third is felt by the subscriber, and on RouterOS a queue can exist, carry the right rate, read without error — and cap nothing:

A background job checks these four causes on the routers, queue by queue, every 3 minutes (GET /api/v1/shaping/limits reads the result without waiting for the routers). It feeds Settings › Are the caps actually held? and the Limit column of the subscribers, where a cap the network does not hold shows NOT HELD with its cause. freeQoS does not touch the firewall: FastTrack is a performance decision that is not its own. It names it and gives the line to paste (/ip firewall filter disable [find action=fasttrack-connection]). It does fix what belongs to it: a queue disabled by hand is re-enabled by reconciliation, and a queue hidden by another is reported as a conflict.

The write switch and the account's rights

freeQoS writes to a router only when all three agree:

1. the global switch (Settings › Shaping and writing to the routers) is on;
2. the router's own writing allowed switch (Devices, list of polled routers) is on;
3. the RouterOS account has the rights (below).

The global switch turns writing on or off without a restart; the database keeps its state. Turning it on asks for a confirmation and a reason, recorded in the log; turning it off is immediate. ENFORCEMENT_LOCKED=true, or ENFORCEMENT_ENABLED=false in the environment, forbids turning it on from the interface.

The per-router switch works the same way: turning it on first shows what freeQoS would write on that router, then asks for a confirmation and a reason; turning it off is immediate. Each change is recorded in the command log (GET /api/v1/shaping/audit, verb switch) with its author and its reason. While it is off, every write path skips the router — reconciliation, CAKE queue types, NetFlow export, restrictions, boosts, bandwidth schedules, the closed QoE loop, a rate written at once, Reset queues and commissioning — and nothing is sent, not even for a gesture made by hand. Reading, measurement, the latency probe and NetFlow collection go on as usual. The router's plan is still computed: the map and the plan of Settings show it marked read-only, so you can read what would happen before allowing it. A router of ROUTERS_FILE accepts write_enabled too (default true); the interface can make it read-only, and allow it again as long as the file does.

Writing needs the write and api policies. freeQoS reads the real rights of the account on the router (/user and /user/group) and gives one of three verdicts: can write, cannot (with the missing policy, or Writing is disabled for this router in freeQoS (Devices) when the per-router switch is off — the account's own rights are then still reported, in account_can_write), or undetermined. When /user cannot be read (an account authenticated by RADIUS, for example), freeQoS does not block: it tries the command and reports what RouterOS answers, translating not enough permissions into the fix to make. A separate write account can be declared per router (rw_username); REQUIRE_SEPARATE_WRITE_ACCOUNT=true makes it mandatory.

Rolling out router by router

The safe way to put freeQoS next to an existing shaper (Preseem, scripts, RADIUS rate limits) is, entirely from the interface:

1. Declare the core and every NAS in Devices, leaving Allow freeQoS to write on this router unticked. Leave the global switch off.
2. Observe for as long as needed: tree, subscribers, latency, traffic, and in Settings › Shaping and writing to the routers the plan each router would receive, marked read-only.
3. Allow writing on one pilot NAS (its switch in Devices: the plan is shown, a reason is asked), then turn the global switch on. Only that NAS receives commands.
4. Then NAS by NAS. Turning a router's switch off puts it back to read-only at once; the global switch stops everything.

Closed QoE loop

Every 5 minutes, freeQoS looks at the QoE of each sector over the last 15 minutes.

• Tighten: if at least 2 subscribers of the sector fall below 55, the link's queue is tightened by 10%. The queue then forms again in CAKE rather than in the radio.
• Floor: it never goes below 50% of the computed rate.
• Relax: one step is given back after 3 healthy cycles in a row. Tighten fast, relax slowly, to avoid oscillation.
• What never moves: a subscriber's purchased plan. Only the sector's shared envelope changes.
• What does not count: a subscriber that has never answered the ping.

A single degraded subscriber points at its last mile (CPE, home Wi-Fi), not at the sector. This is why at least two are needed.

On and off. The setting qoe_loop_enabled (Settings › Write safeguards, live, on by default) turns the loop on or off. Off, the loop reads no score and decides nothing, and every tightening it had applied is released: the planner ignores the tightenings at once, the next reconciliation brings the links back to their normal envelope, and the stored tightenings are reset (last_action = release) as soon as the setting changes, without waiting for the loop's next pass, so that turning the loop back on starts from scratch rather than re-applying old decisions (turning it back on resets them again, in case some were left over). Like every write, the loop is also subject to the global switch and to each router's switch: on a read-only router, the tightening is decided and the plan computed, nothing is sent.

8. Capacity and business insights

The measurements answer operating questions ("is it working?"). The same data, read over days, answers capacity and commercial ones: how much was sold behind each link, when links saturate, who is about to leave, who is ready for a bigger plan, and how many more subscribers each site can take.

Sold against real capacity

For each PoP, freeQoS divides the sum of the plans sold by the measured capacity of the site (GET /api/v1/capacity):

A PoP at 12:1 is not broken: it becomes so the day its subscribers use it at the same time. That is why the busy-hour peak actually observed is shown next to the ratio.

When a link saturates

For each link, the occupancy is the busy-hour peak divided by its capacity: below 80% free, from 80% loaded, from 95% saturated. It can exceed 100%: the capacity of a port is its negotiated speed, that of a radio a measurement of the moment, and an occupancy above 100% means the capacity retained is underestimated — exactly what needs to be seen.

A link is flagged to reinforce when its average occupancy over the period is above 80%, with at least 10 samples. A peak at 100% proves nothing — it is what a well-sized link does on a match night; an average above 80% means the next growth will be paid in latency for everyone.

Saturation risks (Executive, GET /api/v1/capacity/hotspots) apply the gauges' thresholds — from 70% a link is to watch, from 90% it no longer holds one more peak — and split links into two sides: the internet side (the gateway's uplink and the PoP-to-core links, where a saturation hits every client) and the PoP side (links towards subscribers, VLANs and relays, where it only hits what hangs below). A radio link that only carries 70% of its nominal capacity is flagged as degraded.

Who is about to leave, who is ready for more

Insights (GET /api/v1/insights/subscribers?days=7) compares the chosen period (7, 14 or 30 days) with the one before it, so it needs twice the period of history; the page says how many days it has.

A subscriber who saturates its plan and whose latency rises is not in the second list: that is a network problem first, and selling it a bigger plan would fix nothing. Subscribers spending more than 20% of their samples above 90% of their plan are also listed in the capacity view as living at their ceiling.

How many more subscribers a site can take

For each site and access point (GET /api/v1/insights/capacity), freeQoS takes the measured busy-hour peak, divides it by the number of subscribers to get what each one adds at peak, and divides the room left under 80% of the capacity by that contribution. This is the site's own measurement, not a theoretical oversubscription ratio. A site where 20% or more of the subscribers already have a poor experience has no room, whatever the apparent margin. Without a known capacity or a busy-hour measurement, the answer is "unknown", with the reason.

Volumes

The capacity view also ranks subscribers by volume over the period. The top of instantaneous rates names whoever is downloading right now; the volume over a week names whoever weighs on the network. They are almost never the same subscribers.

9. Interface

Errors say what happened and what to do: a title (Not allowed with your account, Not possible right now, A router or service did not answer, freeQoS cannot be reached...), the server's reason, and the next step. An error from a button shows in a corner without blocking the page; a page that cannot load says so in a banner and retries on its own.

Each page reads in sections, with a table of contents at the top and a tooltip on every figure that deserves an explanation. The two long configuration pages, Settings and Devices, show one section at a time: their table of contents works as tabs.

Read the Settings page before enabling writes

The Shaping and writing to the routers section shows, before enabling, what freeQoS would do on each router: queues created, modified, deleted, and links skipped with their reason. A router whose writing is disabled in Devices is listed too, marked read-only: its plan is what it would receive once allowed, and it is left out of the commands counted when the global switch is turned on.

Two banners can appear at the top of the interface:

• Other instance detected: another freeQoS installation creates queues on the same routers. Its objects are not touched; one of them must be stopped.
• Frozen lines: anti-oscillation has frozen one or more queues. The banner says which and why.

Offline, or not measured?

A client is Offline when its router answered but the client was not in its sessions (/ppp/active) for 90 seconds: the client really left (CPE off, line down, PPPoE session closed by the router or RADIUS). freeQoS never closes a PPPoE session itself: it only writes queues, firewall rules and the NetFlow export.

A client is Not measured · router X not answering freeQoS when freeQoS could not read the sessions of its router. The client may be connected; it is freeQoS that no longer reaches the router. Hover the text for the reason:

GET /api/v1/pops/read-status gives, for each router, the time of the last successful read, since when it fails and why. The container log says the same: sudo docker compose logs app | grep "Collecte impossible".

RouterOS calls are blocking and run in threads: IO_THREADS (default 64) sets how many. A small pool (the Python default is the number of CPUs + 4) let latency probes and configuration exports hold every thread, and session reads ran out of time on routers that were fine.

Empty latency

When a subscriber has no latency, the cell does not stay silent: it says whether the subscriber has never answered, whether the measurement is too old, or whether the probe has not run yet. Find the cause runs the diagnostic described in section 5.

Search, units and empty values

• Search (top of every page, GET /api/v1/search): one field finds a subscriber, an IP, a MAC, a device or a site — type what you have in front of you.
• Units: rate fields accept kbps, Mbps or Gbps, and values are displayed in the most readable unit.
• Empty is not zero: a value that was not measured shows "-" or a reason, never 0. A subscriber that is declared but never measured is listed with gaps, not zeros.
• Errors are shown: a tab that cannot load says which error, rather than staying blank.
• No external dependency: no framework, CDN or downloaded map tile; the interface works on a management server cut off from the internet. After an update, the browser cannot serve the old scripts: their address carries a fingerprint of their content.

Every section and every figure of the interface carries an (i) with its explanation. Appendix A reproduces all of them, page by page.

10. API

Everything the interface does goes through the API. The full guide, with curl examples and the reference generated by the server, is at <your-freeqos-url>/api-guide. This section gives its structure and rules.

Three APIs, one server, the same keys

How the commercial model reaches the network

A billing system (Splynx, UISP CRM, Powercode…) knows its customers and what it sold them, but not the routers. The /model/v1 API makes the link. It takes the exact shape of the Preseem model API: an existing integration only has to change URL and key.

What happens when a service is pushed (PUT /model/v1/services/{id}):

1. The rate is the service's own if it has one, otherwise its package's. A commercial exception on one line does not require creating a package for it.
2. The PoP is found by walking service → access point → site → site name. freeQoS finds the router to configure through that name.
3. With an address (network_prefixes), the service becomes a static-IP subscriber: it is placed on its router, measured and limited.
4. With only a MAC, it is set aside. As soon as that MAC appears in a router's ARP or DHCP table, freeQoS deduces the address and places the service.
5. An identifier already used by a record entered by hand is refused (409): the API never takes over a human action.

PUT creates or replaces: billing can replay its whole inventory every night without risk. The identifier in the URL is authoritative; a body carrying another one is refused (400).

Usage API parameters (GET /usage/v1/services and /usage/v1/services/{id}): start and end (ISO 8601, UTC), or days (default 30, up to 366) when start is absent; bucket = total, hour, day or month; vantage = auto, edge or pop to override the accounting vantage point.

For a PPPoE subscriber, the simplest is still PUT /api/v1/plans/{login}: the login is enough to find it on its router.

A plan can come before the subscriber. A management interface that feeds the RADIUS creates the subscriber and its plan before its first PPPoE session, and an initial sync pushes offline subscribers too. PUT /api/v1/plans/{login} therefore accepts a login never seen connected: the plan is kept ("pending": true, state en-attente-de-connexion), listed under Plans › Waiting for first connection and in the pending field of GET /api/v1/plans, and applied by itself at the first session — the plan source reads the same table for every new login. DELETE forgets a pending plan (a misspelt login would otherwise wait forever). Use the PPPoE login, which is the RADIUS username: unlike an address, it never changes. With PLAN_PROVIDER=freeradius_sql, a new subscriber's plan comes from RADIUS at its first connection: a pending plan is then refused (409) rather than silently ignored.

Consumption (/usage/v1) comes from NetFlow, not from queue counters: those restart from zero at each reconnection and do not exist for a subscriber without a queue. With no router exporting, this API returns zeros and says so in its source field.

Authentication

A key is created in the API tab. The secret is shown only once. Two scopes:

• read: every GET;
• read + write: also POST, PUT, PATCH, DELETE.

A key can never manage keys, accounts or passwords: that stays behind a person's login.

Three equivalent forms are accepted everywhere:

Authorization: Bearer <key>
X-API-Key: <key>
Authorization: Basic base64(<key>:)      # Preseem form

GET /model/v1 checks a key in one call: it returns the collections, the key prefix and its scopes.

The secret is drawn once, shown once, and the database only keeps its SHA-256 fingerprint. A lost key is revoked and replaced. A refusal never says why (unknown, disabled, expired): distinguishing the cases would give an oracle to whoever tries keys at random; the server log does say it.

Conventions

• JSON in and out. Down = towards the subscriber, up = from the subscriber.
• ISO 8601 timestamps in UTC.
• A PPPoE subscriber is identified by its login, a static-IP subscriber by its reference, a model object by the id chosen in the URL.
• PUT creates or replaces: replaying the whole inventory is harmless.
• A plan or limit change is written to the router in the same call.

The enforcement report

Every response that touches a queue contains an enforcement object telling what actually happened:

The calls that matter

A few usage rules:

• A plan for an unknown login returns 404: the subscriber must first be seen on a router or declared.
• Giving a plan lifts a forced limit on that subscriber: the plan becomes the rule again.
• The report of an API call is authoritative. In simulation, automatic writing is blocked even for a write key: state is then file-a-poser.

Reference

/openapi.json describes every route, generated by the installed server: it cannot drift from the code. The /api-guide page makes it readable, with search.

11. Security

freeQoS holds router credentials that can write across the whole network. Security follows a simple principle: what writes is rare, explicit and logged.

Interface accounts

• First account: created by the application on its first start, as an Administrator (edit), with a random password kept in data/first-admin.txt (mode 0600) until it is changed. The first-visit screen only appears if this is turned off (FIRST_ADMIN_AUTO=false).
• Three access levels, each including the rights of the previous one, enforced by the server (a refused write is a 403 naming the level it needs, whatever the interface shows):

The writes open to the Operator form a closed list (POST/DELETE /api/v1/shaping/boosts, PUT /api/v1/clients/{login}/mode, PUT /api/v1/clients/{login}/profile, POST /api/v1/clients, POST/PATCH/DELETE /api/v1/static-clients, POST /api/v1/clients/actions, PUT/DELETE /api/v1/plans/{login}, POST/PATCH/DELETE /api/v1/bandwidth-modes and /api/v1/bandwidth-schedules): a route added later is reserved to the Administrator until it is opened on purpose. Every change is recorded with the account that made it, in the activity log below and in the enforcement audit. - Activity log: every change made on a client (bandwidth mode, boost, boost stopped, plan, plan removed) is recorded in client_activity: who, when, which client, the detail, and the state of the queue afterwards (written, pending on the router because writing is off, no router, refused). It is read on the Activity page (search, CSV export), in each client's sheet, and through GET /api/v1/activity?login=&q=&limit=. Kept 400 days. An API key keeps its two scopes: read, or write (Administrator rights except accounts, which no key can manage). The stored values read and edit are those of the former two roles: existing accounts keep their level without migration. - Passwords: 12 characters minimum, too-common words are refused. They are hashed with scrypt (N=2^14, r=8, p=1, salted, compared in constant time). - Anti-guessing: 5 failures in 5 minutes lock the email and the client address for 5 minutes. Each repeat doubles the wait, up to 1 h. - Session: an HttpOnly, SameSite=Strict cookie, valid 24 h, 30 days at most (SESSION_TTL_HOURS, SESSION_MAX_HOURS). Writes also check Origin and Sec-Fetch-Site. - Log: every login (successful, refused, locked), logout and account change is recorded with the address and browser. At login, everyone sees the date and origin of their previous login. - Last Administrator: at least one active Administrator account always remains; the last one can be neither deleted, downgraded nor disabled. - Sessions: at most 10 open sessions per account; everyone sees their own sessions (browser, address, last activity) and can close them remotely. Changing a password or a role closes the other sessions. - Journal retention: login events are kept 180 days (Settings › Accounts › Login journal) and are also written to the container log (auth login_failed …), usable by fail2ban.

Behind an HTTPS reverse proxy (the included one is already set up), set FORWARDED_ALLOW_IPS=<proxy address> so that the application trusts the proxy's X-Forwarded-Proto: the session cookie is then sent Secure, HSTS is set, and the address recorded for each login is the client's, not the proxy's.

Locked out? Give the account a new password from the server; measurements and inventory are untouched:

sudo docker compose exec app python -m app.cli reset-password --email noc@example.com

HTTP headers

API keys

read or read + write scope. A key never manages keys, accounts or passwords. It can be disabled and revoked. Every write made with a key is logged as api:<name> (<prefix>).

Router credentials

• Passwords are encrypted in the database with data/secret.key and never come out of any response, not even encrypted.
• Least privilege: a dedicated RouterOS account (read,write,api,test), without ssh, ftp, winbox or policy.
• Separate accounts: REQUIRE_SEPARATE_WRITE_ACCOUNT=true requires a distinct account for writing.
• Encryption: api-ssl (8729) with tls_verify=strict or a fingerprint, rather than the clear API, when freeQoS and the routers do not share an isolated management network.

Writing to the network

• Simulation by default; explicit enabling, after reading the plan.
• ENFORCEMENT_ENABLED=false in the environment locks writing: the interface cannot turn it back on.
• Writing is allowed router by router in Devices; a router added from the interface starts read-only, and a read-only router receives nothing at all.
• Only objects of this instance are touched; the others are read, never modified.
• The circuit breaker refuses an abnormally large plan.
• The command log (/api/v1/shaping/audit) gives the author, target and result of each write.

Network exposure

It is recommended to put the interface behind HTTPS and to restrict 2055/UDP to the routers' addresses.

12. Operations

Monitoring freeQoS

Monitor /health/ready, not /health: a collector can fail for an hour while the process still answers.

The cycles

Each cycle can be run immediately with POST /api/v1/jobs/{name}/run.

The scheduler runs each cycle once immediately at startup, then at its period. A cycle never overlaps itself: it runs, then sleeps for the rest of its period; an overrun is counted, not stacked.

Live settings

Most operating settings can be changed in Settings without a restart (PUT /api/v1/settings/{name}): shaping and CAKE options apply at the next plan, cadences at the next turn of the scheduler. They are stored in the database with their history (GET /api/v1/settings/history: who, what, when, why). The database wins: the environment only seeds a value on the very first start, so once a setting has been changed in the interface, editing .env no longer affects it. GET /api/v1/settings shows each setting's value, default and origin; DELETE /api/v1/settings/{name} brings it back to its default.

Deliberately out of the interface's reach: database access, secrets, and ENFORCEMENT_ENABLED=false when it is set in the environment.

Data and retention

Measurements live in TimescaleDB hypertables:

• split by day (CHUNK_INTERVAL_HOURS=24);
• compressed after 7 days (COMPRESSION_AFTER_DAYS);
• deleted after 90 days (RETENTION_DAYS).

Without TimescaleDB, freeQoS runs on plain PostgreSQL, without compression or automatic retention.

Backup and restore

make backup                                   # backups/YYYYMMDD-HHMMSS/: base.dump + secret.key
make restore DIR=backups/20261008-0300        # replaces the database, asks for confirmation

make restore stops the application, wraps pg_restore in timescaledb_pre_restore() / post_restore(), puts secret.key back, then restarts. Copy backups off the server.

make backup does not copy data/instance.id. On a new server, copy it back or set FREEQOS_INSTANCE_ID; otherwise queues already in place will be seen as another instance's and left alone.

Common actions

Several instances

Two installations must not drive the same routers. If it happens, each only touches its own objects (instance=<id> comment), but they fight over subscribers. The Other instance banner reports it. For an update or a migration, stop the old one before starting the new one.

13. Troubleshooting

All these cases come from the lab or the first deployment. For each: the symptom, the check that settles it, then the action.

700 to 900 ms latency on nearby subscribers

• Cause: the ping leaves through the main table while subscriber routes are in a VRF. It goes up to the core and back.
• Check: Find the cause → routing_table must name the VRF (CUST-INET), not main. On the router, /ping <subscriber> vrf=CUST-INET count=5 must give a few ms.
• Action: up to date, freeQoS picks the VRF by itself. If routing_table stays main, look at route_candidates: the route to the subscriber may be a default route towards upstream. After fixing, POST /api/v1/rtt/reset-history clears the wrong measurements.

Empty latency ("no reply", "probe silent")

Run Find the cause and read the code (table in section 5). The two most frequent cases:

• client_blocks_icmp: the subscriber's CPE filters ping. This is not a degradation; the subscriber is excluded from QoE.
• no_test_policy: the RouterOS account's group lacks the test policy.

High latency on a saturated subscriber

• Symptom: a single subscriber at 300 or 500 ms, filling its plan.
• Cause: real bufferbloat. Without a CAKE queue, the queue forms in a buffer along the path (CPE, radio, test link).
• Action: give it a plan slightly below the real capacity of its line, so the queue forms in CAKE. Example: 800 kbit/s on a line that holds 1 Mbit/s. If latency stays high, the real capacity is lower than expected: lower the plan further.

A queue is rewritten every 2 minutes

Two writers are fighting over the queue: two freeQoS instances, a script, or another queue targeting the same address.

• Check: GET /api/v1/status. Read other_instances (another installation is writing) and frozen_lines (anti-oscillation froze the line).
• Action: stop the extra instance, then Reset queues. If a queue created by hand targets the same subscriber, remove it by hand: freeQoS will not touch it.

A parent queue appears on a transit link

Recent versions skip routing links, the uplink, the gateway and links towards other managed routers.

• Check: the Settings page lists skipped links with their skip_reason.
• Action: a queue created by an old version stays until Reset queues. If the link is not recognised as transit, correct its role in the tree (PATCH /api/v1/topology/nodes/{key}).

Nothing is written to the routers

In order:

1. Is writing enabled? GET /api/v1/shaping/enforcement.
2. Is it locked by the environment? ENFORCEMENT_ENABLED=false in .env.
3. Is writing allowed on this router? Its switch in Devices (write_enabled in GET /api/v1/pops/routers); a router added from the interface starts read-only.
4. Does the account have write? GET /api/v1/shaping/capability.
5. Did the plan trip the circuit breaker? The log says so.
6. Does the subscriber have a plan? A subscriber that is only detected is observed, not limited.

No NetFlow traffic

1. GET /api/v1/netflow/status: are datagrams arriving?
2. GET /api/v1/netflow/export: is the target set, and to which address?
3. In a container, is NETFLOW_COLLECTOR_ADDRESS set?
4. Is UDP port 2055 open between the routers and freeQoS?

Scores stay old

Scores are computed over a sliding 15-minute window. After a measurement fix, old samples still weigh in. POST /api/v1/rtt/reset-history starts again from clean measurements.

The router refuses the connection

POST /api/v1/pops/routers/test gives a hint:

14. Settings reference

All settings are read from the environment or from .env. The variable name is the one in the table, in capitals. Those marked ✱ can also be changed live in Settings.

Application and database

Inventory and sources

Cycles

Latency

Plans and shaping

QoE loop

NetFlow and traffic

15. Data model

Reference data

Time series (hypertables)

What subscribers reach

A row is created in ip_intel with no resolution date as soon as a subscriber reaches the address: that is the naming queue, and what makes discovery dynamic. Three views give the last point of each series: subscriber_latest, interface_latest, backhaul_latest. Aggregations use date_bin rather than time_bucket: the same queries work on plain PostgreSQL.

16. Known limitations and FAQ

Limitations, by design

• No code in the packet path. Consequence: no TCP retransmissions, and latency comes from an active probe that requires the subscriber's box to answer ping.
• Radios are never driven. Their capacity is read; writing only concerns RouterOS queues, address lists, firewall restrictions and the NetFlow export.
• No RADIUS writes (no CoA): plans can be read from FreeRADIUS, never written back.
• No fast local loop on the PoP: freeQoS sets baselines, it does not react below the second.
• Restrictions are IPv4 only: IPv6 prefixes are set aside and the plan says so.
• A static-IP client is only measured once a queue targets it.
• The NetFlow collector uses a single core: beyond about 5,000 flows per second, datagrams are lost (section 3).
• The two NetFlow tables are not compressed: they are the largest disk item (section 3).
• RDAP and web geolocation are on by default and send the addresses your subscribers visit to third parties (section 6).

FAQ

Does freeQoS cut subscribers if it stops? No. The queues stay on the routers and traffic flows; only measurement, timed boosts and adjustments pause. A boost that should have expired keeps running until freeQoS comes back.

Can I try it without touching my routers? Yes: it starts in simulation, and a router added from the interface starts read-only. Keep its writing allowed switch off in Devices (or the global switch off) and read the plan; giving the account only read,api,test also makes writing impossible, from the router side.

Will it touch the queues I created myself? Never. Only objects carrying freeqos:managed instance=<this instance> are modified or deleted; your queues are shown on the map as manual queues.

Why does a subscriber show no latency? Most often its CPE does not answer ping (client_blocks_icmp). Find the cause says which of the eight causes applies (section 5).

Why is a subscriber not capped? Is writing on, globally and on its router (Devices)? Does it have a plan? Is it online? Then look at Are the caps actually held?: FastTrack is the first cause of a cap that does not cap (section 7).

Why is the Traffic page empty? The page names the cause: no router, export not set up yet, writing off, or a network path problem — most often UDP 2055 not published or filtered (section 6).

Can two freeQoS run on the same routers? They will not overwrite each other's objects, but they will fight over subscribers. Run one per network; stop the old one before starting a new one.

How do I move freeQoS to another server? make backup, copy the backup and the instance identifier to the new server, make restore, set the same FREEQOS_INSTANCE_ID or copy data/instance.id into the volume, then update the routers' NetFlow target if the address changes (freeQoS does it by itself at the next export pass).

Where are the logs? make logs (or sudo docker compose logs -f app). Every command written to a router is also in Settings › Log of commands sent.

Appendix A. Interface reference

The explanations below are exactly those the interface shows behind each (i), extracted from the application at build time: they cannot differ from what operators read on screen.

Clients

The daily page of Operators (who also have Modes, Alerts, Activity, Schedules and Map, and no Settings): every client, its connection, its usage against its limit, its bandwidth mode, its boost and its plan, for one client or for a selection. The four cards on top filter the list; search, filters, sort and pages handle hundreds of clients; the list exports to CSV; Traffic charts the selected clients. An Administrator adds a client (static IP, VLAN, ranges) with the + button. Clicking a client opens its page (Overview: status, usage now against its limit, limit, latency, usage over 1 hour, 24 hours or 7 days, connection; Plan & mode: change its mode, plan and boost; Activity: its history).

Client operations

What it shows. The daily page: every client, its connection, its usage, its bandwidth mode and its boost.

How it is measured. Operators only see this page and their account. They act on one client or on a selection.

How to read it. Tick clients to change their mode or boost them together; a group change reports a result per client. The Plan button sets the rate the client subscribed to.

Bandwidth mode

What it shows. The named rate the client is in: Automatic, or a mode such as Backup or Night.

How it is measured. Automatic follows the plan and, when there is one, the bandwidth schedule: the rate changes with the hour on its own. A mode stays until the client is put back to Automatic.

How to read it. “Manual limit” is a rate set by hand by an Administrator, outside the modes.

Connection

Connected = a measurement less than 90 s old. Otherwise, when the client was last seen.

Current usage

Download (↓) and upload (↑) of the client right now, from the last measurement.

Not in automatic

Clients in a bandwidth mode or under a manual limit: their rate does not follow their plan and schedule.

Boosts active

Clients with a running boost. A boost ends on its own at its expiry.

Alerts

What needs someone, grouped by cause, each alert with a stable error code (ERR_POP_TIMEOUT, ERR_CLIENT_DISCONNECT...) and what to check. PDF report for every site or one site.

Connection health

What it shows. What needs someone, grouped: a site where several clients are down together is one site problem, not many client problems.

How it is measured. Also listed: clients offline on a site that is up, high latency (150 ms or more right now), clients in a mode that stops boosts, clients never measured.

How to read it. “View clients” opens the Clients page with these clients selected, ready for a mode or a boost.

Activity

The log of every change made on clients.

Team activity

What it shows. Every change made on a client: bandwidth mode, boost, plan. Who asked for it, when, and whether it reached the router.

How it is measured. “Applied”: the queue was written. “Pending on router”: writing is off or the router is unreachable, it is written later. “Refused”: nothing changed (for instance a boost in a mode that stops boosts).

How to read it. Kept 400 days. Export CSV gives the list shown.

Map

The sites and the clients on a map, coloured by connection. A site opens its clients and its PDF report; an Administrator places sites and clients by coordinates, GPS or a tap on the map.

Modes

Every bandwidth mode, the clients in each one, and creating or editing modes. Open to Operators.

Bandwidth modes

What it shows. Named rates operators give a client in one click: a fixed rate, or a share of the client's plan.

How it is measured. Defining modes needs the Administrator level; giving one to clients, the Operator level. Changing a mode's rate applies it at once to every client in it.

How to read it. A mode that “stops boosts” clears the running boost and refuses new ones: use it for a crisis or non-payment.

Schedules

The bandwidth schedules: rates that change with the time of day, on their own. Open to Operators.

Client management

What it shows. Bandwidth schedules: rates that change with the time of day, on their own (Schedules tab).

How it is measured. Open to Operators: these are commercial decisions about clients. Adding clients, sites, routers, antennas and APIs stays with the Administrator.

Bandwidth schedules

What it shows. Rates that change with the time of day (day, evening, night, weekend), on their own, for all clients, some sites, some plans or named clients.

How it is measured. Each time slot sets a share of the plan (200 % = twice the plan) or a fixed rate. A client in a bandwidth mode or with a boost is not affected until it is back in Automatic.

Dashboard

What is happening on the network right now.

Network throughput

What it shows. Total traffic of all your subscribers (PPPoE and static clients) over time. Download is drawn above the axis, upload below.

How it is measured. Read every 10 s from each subscriber’s queue on its router, then summed. Solid line = average of each time step; dotted line = the highest 10-second moment inside the step, so a short burst is not flattened away.

How to read it. Traffic that belongs to no subscriber — a bandwidth test between routers, device management, an undeclared client — is not in this curve: it shows in Routers — live traffic as “not from clients”. Filter by router or client with the menus.

What to do. A flat line at 0 while clients are online usually means the collection stopped: check the health dot at the top left and Devices › Polled routers.

Routers — live traffic

What it shows. Each router, live: what it exchanges with the internet on its uplink, what its own clients consume, and the gap between the two.

How it is measured. Uplink port counters and subscriber queues, read every 10 s. Router CPU and port load come from the same poll.

Scale.

• Green: under 70%: comfortable
• Amber: 70 to 90%: watch it — peaks start to queue
• Red: over 90%: saturated — latency rises for everyone behind it

How to read it. The coloured state line at the top says whether each collection (subscribers, ports, latency) is running. A large “not from clients” share is traffic of no known client.

What to do. Red collection state: open Devices › Polled routers and test the connection of that router.

Top consumers

What it shows. The subscribers using the most bandwidth right now.

How it is measured. Last 10-second measurement of each subscriber’s queue, sorted by download.

How to read it. A client at the top of this list is not a problem in itself — it is using what it pays for. It matters when its row is red (at its limit) and the node it belongs to is saturated too.

Radio backhauls

What it shows. The radio links declared in the inventory (UISP / airOS), with what they can carry now and how loaded they are.

How it is measured. Current capacity is read from the radio (it drops when the signal fades); nominal capacity is what the link is rated for. Load = traffic ÷ current capacity.

Scale.

• Green: under 70%: comfortable
• Amber: 70 to 90%: watch it — peaks start to queue
• Red: over 90%: saturated — latency rises for everyone behind it

What to do. Current capacity far below nominal: alignment, interference or rain fade — check signal and SNR on the antenna page.

Executive

Where the risk is: saturation, experience, load and queues per node, health over time. Clicking a node or a client opens the Selection panel.

Saturation risks

What it shows. Every link compared with what it can carry, worst first.

How it is measured. Traffic of the link ÷ its capacity (the lowest of: rate set by hand, measured radio capacity, port speed). Bar = now; marker = the peak of the selected period.

Scale.

• Green: under 70%: comfortable
• Amber: 70 to 90%: watch it — peaks start to queue
• Red: over 90%: saturated — latency rises for everyone behind it

How to read it. Internet side (gateway uplink, PoP-to-core): a saturation hits every client. PoP side (towards subscribers, VLANs, relays): only the clients behind that link. A link with “capacity unknown” cannot be judged — set its rate in the Network tree.

What to do. Peak regularly over 90%: upgrade the link or lower the plans sold behind it. Only the peak is high: usually fine, links are meant to be full at the busiest minute.

Latency by client

What it shows. The experience each subscriber really gets, with a verdict (good / fair / poor) and the reason in plain words.

How it is measured. The PoP router pings each client 5 times every 30 s (200 ms apart, from its loopback). Median, p95, jitter and loss come from those pings; “under load” compares latency when the client’s line is busy with latency at rest.

Scale.

• Green: good: median under 30 ms, no loss, little bufferbloat
• Amber: fair: 30–100 ms, spikes, some loss, or +30 to +150 ms under load
• Red: poor: over 100 ms, 2%+ loss, +150 ms under load, or score under 50
• Grey: at plan limit: judged apart (see below)

How to read it. Samples taken while the client uses 85%+ of its plan are left out: a full line makes its own queue — that is not a network fault. “no reply” on every client of a router means the probe itself is failing, not the clients.

What to do. Many poor clients behind the same node: look at that node’s load and backhaul. A single poor client: its CPE, signal or home Wi-Fi.

Load by node

What it shows. Traffic of each node (site) compared with the sum of its clients’ limits.

How it is measured. Sum of the clients’ queues every 10 s, divided by the sum of their limits.

How to read it. This is a share of what was sold, not of the link: 100% means every client is at its cap at once, which practically never happens.

Queues by node

What it shows. Each node (PoP or router) with its clients: traffic now vs limit, limits applied, plans sold, worst latency and experience.

How it is measured. Queue counters every 10 s; latency from the probe every 30 s. A VLAN client is listed under the router that carries it.

How to read it. Click a row to open its detail below. The “Rate” field lets you force a client’s limit by hand — it then overrides its plan until you clear it.

Selection

Details of the node or client selected in the table above: link, plans, limits and the clients behind it.

Node

What it shows. Detail of the selected node: its link (capacity and load), the limits and plans of its clients, and how each client is doing.

How to read it. Oversubscription = plans sold ÷ link capacity. Some is normal (clients are not all active at once); far above 3× the link will be full at busy hours.

Client

What it shows. Detail of the selected client: its plan and where it comes from, the limit really applied, its usage and its latency at rest and under load.

Health over time

What it shows. One colour per time step for three indicators: experience score, latency and load vs limit. Read it left to right to see when things went wrong.

How it is measured. Steps of the selected period (e.g. 5 min over 24 h). Steps where a client was at its plan limit are left out of latency and score.

Scale.

• Green: green: good
• Amber: orange: fair / watch
• Red: red: poor / saturated
• Grey: grey: no measurement in that step

How to read it. For a node: the worst client of the step. For the whole network: all clients together. A red band at the same hour every evening is a capacity problem; a red band at random times is more often radio.

Traffic

Who consumes what, where the traffic goes, and the traffic restrictions.

Who consumes

What it shows. Volume per subscriber over the period.

How it is measured. From NetFlow, each client counted once per direction: downloads where they are seen best, uploads likewise (the best exporter for each direction, never two added up).

How to read it. This is volume (GB), not speed: a client streaming all evening outweighs one who ran a short speed test.

Which services the traffic comes from

What it shows. Traffic grouped by recognised service (YouTube, Netflix, Steam, Microsoft updates…).

How it is measured. The remote address of each flow is matched with a catalogue of published address blocks, then with its reverse name and owner. Content is never inspected — it stays encrypted.

How to read it. “unknown” is traffic to addresses that match no catalogue entry yet; it shrinks as names are resolved.

Where the traffic goes

What it shows. Map of the destinations your clients reach: each country and city sized by the volume exchanged with it.

How it is measured. From NetFlow: each remote address is located from its address block (geolocation database). Hover a point for its volume and clients; click it to open the detail of that place.

How to read it. A location is that of the server’s block, not of the company: a CDN often answers from a nearby city even for a foreign service.

Who talks to whom, client by client

What it shows. Each client and the internet addresses it exchanges with: volume, rate while active and live rate.

How it is measured. NetFlow records of the period, grouped by client and remote address.

How to read it. “Rate when active” divides by the time the conversation was really active, so a 10-second download at 100 Mbps shows 100 Mbps — not the 1 Mbps a whole-hour average would give.

Destinations reached

What it shows. Internet addresses reached by your clients, with their owner, location and volume.

How it is measured. From NetFlow; names come from the catalogue, reverse DNS and (if enabled) the registry.

Find an IP

What it shows. Look up any IP address or domain: owner, location, recognised service, and which of your clients reach it.

How to read it. Useful when a client complains about one site: see whether others reach it too and how much traffic it carries.

Traffic restrictions

What it shows. Rules that block or cap traffic towards a service, a category or an address range — for everyone, some sites, or some clients.

How it is measured. Written on the routers as address lists plus firewall (block) or mangle + queue tree (cap). The address list is refreshed automatically from the catalogue and from what NetFlow discovers.

What to do. A rule that seems to have no effect: check “Last applied” and that the router is reachable; new addresses join the list at the next refresh.

Network tree

The discovered tree, editable with the mouse: drag a box onto another to re-parent it, correct a role, create or remove a link, merge two boxes that are the same device, hide a box. Each link carries its measured throughput. Forget vanished devices removes boxes not seen for a chosen time; declared routers and hand-made links are never removed.

Plans

Which rate for whom: the default plan, every client's plan and its source, and the packages pushed through the API.

Default plan

What it shows. The limit given to a client pushed by the API (or entered) without a rate. A client only DETECTED on a router, with no plan pushed, is observed and never throttled.

How to read it. 0 = no limit. To also cap detected clients, turn on default_plan_for_detected_clients in Settings. Changing it re-writes the queues of the clients that use it.

Clients

What it shows. Each client and the plan applied to it, with where that plan comes from.

How to read it. Source: pushed by the API (billing / CRM), set by hand here, or the default plan. A limit forced in Subscribers (Rate) overrides all three — it is shown here so you know why the plan is not what is applied.

Packages pushed by the API

Offers received from your billing system or CRM through the public API (/model/v1/packages). Clients pushed with a package get its rates automatically.

Insights

The commercial reading of the measurements, comparing the chosen period with the one before.

At risk of leaving

What it shows. Clients showing the signs that come before a cancellation.

How it is measured. Any of: experience score under 50 over the period; usage down more than 70% versus the previous period; no traffic at all for 3 days or more (for a client that used to consume).

What to do. Call before they do: a CPE swap, a realignment or a plan change is cheaper than a lost client.

Ready for a bigger plan

What it shows. Clients that live at their plan ceiling while their experience stays good — the plan limits them, not the network.

How it is measured. At 90%+ of their plan in 15% or more of the samples of the period, with a score of 50 or more.

How to read it. A client at its ceiling with poor latency is not here on purpose: selling it more would not fix what is a network problem.

Sites and access points room for more subscribers

What it shows. How many more subscribers each site or access point can take at today’s usage.

How it is measured. Busy-hour peak per subscriber, against a target of 80% of the capacity (above that, queues fill and latency rises before the link is full).

How to read it. A site where 20% or more of the clients already have a poor experience shows no room, whatever the margin on paper.

Every subscriber plan, usage, experience

What it shows. All subscribers with their limit, current usage, latency and whether the router really holds the cap.

How to read it. Click a client to see its plan, its queue on the router and its history. The search box accepts a login, an IP, a MAC or a site.

Devices

Routers and antennas: their health, adding them, the Ubiquiti UISP controller (connect it, see every antenna's radio capacity, attach backhauls to their site), and the inventory. One section at a time: the table of contents works as tabs.

Router health

What it shows. CPU, memory and uptime of each polled router.

Scale.

• Green: CPU under 70%: fine
• Amber: 70–90%: busy — queues and NetFlow may lag
• Red: over 90%: overloaded — packets and measurements suffer

What to do. A sustained high CPU on a PoP: too many simple queues for the hardware, or a firewall rule doing heavy work.

Polled routers

What it shows. The routers freeQoS reads (and writes queues to).

How to read it. Reset queues deletes every freeQoS queue of that router and rewrites them cleanly — use it when caps behave strangely. Queues not created by freeQoS are never touched.

Connect a router

What it shows. Add a MikroTik router: its address, API port and an account with read rights (and write rights if freeQoS should shape).

How to read it. The API-SSL port (8729) is preferred. A dedicated account with the “read, write, api, test” policies is enough — “test” is needed for the latency probe.

Ubiquiti antennas

airOS access points and CPEs polled for their radio state: signal, noise, CCQ, capacity. Their capacity feeds the saturation and room-for-more calculations.

Radio health access points and their CPEs

What it shows. Each access point and the CPEs connected to it, with the radio quality of each link.

Scale.

• Green: signal above −68 dBm, SNR above 25 dB, CCQ above 90%
• Amber: signal −68 to −75 dBm, SNR 20–25 dB
• Red: signal below −75 dBm, SNR under 20 dB or CCQ under 75%

What to do. Weak signal on one CPE: alignment or obstacle. Weak on all CPEs of an AP: interference — check the noise floor and change channel.

Add an antenna

Declare an airOS device by its address and credentials. Credentials are encrypted at rest with the controller key.

Inventory

Every device freeQoS knows, with where it was discovered.

Known sites

The PoPs and VLAN sites known to freeQoS. A site pushed by the API takes the place of an automatically discovered one.

API

API keys, and the way to the API guide.

Create a key

What it shows. Create a key for an external system (billing, CRM) to call the public API.

How to read it. The key is shown once — copy it then. “read” gives GET; “write” adds PUT and DELETE. Give each system its own key so you can revoke one without breaking the others.

Endpoints

What it shows. The routes an external application (billing, CRM, provisioning) calls with a key.

How to read it. /model/v1 and /usage/v1: clients, packages, sites, sectors and usage. /api/v1: everything the interface does — routers, plans, forced limits, boosts.

Example

A ready-to-run call with curl. The key goes in Basic authentication as the username, with an empty password.

Settings

Accounts, operating settings, and everything about writing to the routers.

Accounts

Who can log in to this interface, your own password and sessions, and (for edit accounts) the journal of logins.

Who can log in

What it shows. The accounts of this interface.

Scale.

• Grey: Read only: sees everything; every change is refused by the server
• Green: Edit: can change everything, including accounts

How to read it. There is always at least one active edit account: the last one cannot be deleted, demoted or disabled. Changing someone’s role or password logs them out everywhere.

My password

What it shows. Change your own password. Your other browsers are logged out; this one stays connected.

How to read it. At least 12 characters. Passwords from attacker lists (Password2024!, azerty123…), repetitive ones or ones containing your email are refused. A short sentence is both stronger and easier to remember than a short complicated word.

My sessions

What it shows. Every browser currently logged in to your account: device, address, when it logged in and when it was last active.

How it is measured. A session ends after 24 h without activity, and after 30 days in any case. At most 10 per account — the oldest is closed beyond that.

What to do. A device or address you do not recognise: log it out, then change your password.

Login journal

What it shows. Every login, failed attempt, block, logout and account change, with address and device. Kept 6 months.

Scale.

• Green: Login
• Red: Failed login / Blocked: someone typed a wrong password
• Amber: Account changed or deleted

How to read it. After 5 failures the email and the address are blocked 5 min, then 10, 20… up to 1 h if it continues. Many failures from one unknown address = someone guessing.

What to do. Repeated failures on a real account from an unknown address: change that password and, if exposed to the internet, restrict access to the interface.

Operational settings

What it shows. Settings stored in the database and applied without restart.

How to read it. “default” = the value from the environment / built-in default. Apply writes it; the source column then says “database”.

Services and IP location

What it shows. What NetFlow keeps about the destinations your clients reach, and how addresses are named (catalogue, reverse DNS, registry, geolocation).

How to read it. Volumes per client are measured whatever these say; they only decide what is kept per destination and how much naming work (and outbound queries) the controller does.

Shaping

What it shows. How queues are computed and written: safety factor on measured capacity, floor rate, default plan, adoption of queues freeQoS did not create, and how a queue targets the client.

How to read it. A change here is applied at the next reconciliation (or right away with Reset queues in Devices).

CAKE

What it shows. Parameters of the CAKE queues — the queue discipline that keeps latency low while a line is full.

How to read it. Keep the defaults unless you know why: overhead and MPU must match the encapsulation (PPPoE, VLAN) for the rate to be exact; rtt sets how fast CAKE reacts.

Write safeguards

Limits that stop an automatic loop from changing too much at once (circuit breaker), and whether a separate write account is required on the routers.

Traffic

Where the volume of each client is counted when both the internet edge and the PoPs export NetFlow — so a byte is never counted twice.

Collection cadences

What it shows. How often each collection runs.

How to read it. Shorter = fresher figures, but more load on the routers and the database. A 10 s subscriber poll and a 30 s latency probe suit most networks.

What stays out of reach of the interface

Settings that can only change in the environment (.env) — the database address, the encryption key… — because the interface itself depends on them.

Shaping and writing to the routers

What it shows. Whether freeQoS writes queues by itself.

How to read it. On: a reconciliation every 2 min writes any missing or wrong queue. Off: it writes only when you act (Rate, plan change, Reset queues). Either way, only queues marked freeqos:managed are ever modified.

Are the caps actually held

What it shows. Compares the limit freeQoS intends for each client with what is really written on its router.

How to read it. A mismatch means the router was changed by hand, a queue failed to write, or another queue matches first (RouterOS applies the first matching queue).

What to do. Use Devices › Reset queues on that router to rebuild its freeQoS queues from scratch.

Log of commands sent

Every command freeQoS sent to a router: when, by whom (account or automatic loop), what, and the result. The first place to look when a cap changed unexpectedly.

Detail panels

What opens when you click a link, a node, a client or an address.

Right now

Last 10-second measurement.

Clients on this link

What it shows. The clients of this node with how much of their limit they use, their latency and score.

How to read it. Several clients red on latency at the same time as the link is loaded = the link is the bottleneck. Only one client red = look at that client.

Link

What it shows. What freeQoS knows about this node’s link: capacity, load, limits applied and plans sold behind it.

How to read it. Capacity unknown: set the rate of the link in the Network tree so load and oversubscription can be judged.

Plan

What it shows. The plan of this client, where it comes from, and the limit really applied.

How to read it. When “limit applied” differs from the plan, the limit was forced by hand (Rate) or a temporary boost is running.

Plan usage

What it shows. How much of its limit the client uses right now, and its latency at rest and under load.

How to read it. At 85%+ of its plan the client is “at plan limit”: its latency then reflects its own full queue and is not held against the network.

Limit usage

How much of its forced limit the client uses right now, and its latency at rest and under load.

Who reaches this address

Your clients that exchanged traffic with this address over the period, with the volume of each.

Columns and figures

Every other label that carries an (i) in the interface, in alphabetical order. Where names the place when the same word means something else elsewhere.

Appendix B. API endpoint index

The server exposes 207 operations. This index is generated from its own OpenAPI description, so it cannot drift from the code; the API guide (/api-guide) gives the parameters and bodies of each one.

Public API (model)

Public API (usage)

PoPs

Plans

Shaping

Static clients

Metrics

Capacity

Traffic (netflow)

Traffic restrictions

Antennas

Operations

Settings

Health

Accounts

API keys

Bandwidth schedules

Clients

Map

Modes

Notifications

Public access

Topology

Ubiquiti