Documentation

SAMM documentation

The complete operator manual — from first install to day-to-day operations.

25 topics 8 sections One-command install
Quick install

Online in minutes, from one command.

Run a single line on a fresh Ubuntu or Debian server — or in PowerShell on Windows — and the installer fetches the latest release and sets up the whole SAMM stack for you.

Read the full installation guide
Ubuntu / Debian — run as root
curl -fsSL https://samm.securytik.com/install.sh | sudo bash
Windows — run in PowerShell as administrator
irm https://samm.securytik.com/install-windows.ps1 | iex
Playlist Video course Watch SAMM from install to daily operations — a full video course A free, step-by-step YouTube playlist that walks you through installing SAMM and running it day to day — the same ground this manual covers, on video. Watch on YouTube

Getting started

Overview & architecture

SAMM — SecuryTik Active Mikrotik Manager — is a complete ISP management platform for MikroTik PPPoE & Hotspot networks. One installer turns a bare Linux server into a full AAA, billing, and subscriber-management system.

Who SAMM is for

SAMM is built for wireless ISPs, fibre operators, and hotspot providers running MikroTik RouterOS. If you authenticate subscribers over PPPoE, Hotspot, or IPoE/DHCP and need to enforce speed tiers, data caps, expiry dates, and billing — SAMM does all of it from one screen.

IPoE/DHCP subscribers are identified by their DHCP Option 82 circuit-id (the physical access port — the professional ISP way) or device MAC, and the DHCP server's radius-password is simply the router's own RADIUS shared secret, so there is nothing extra to provision.

IPv6 dual-stack is an opt-in option: every subscriber can get IPv6 alongside IPv4. Enable it in the router wizard and choose the delegated (DHCPv6-PD) prefix length — a /56 by default, or anywhere from /48 to /64 — and the IPv6 blocks to hand out. On each Access-Accept SAMM returns a WAN IPv6 pool plus a routed prefix delegated to the subscriber's LAN, so the customer's own router (in route mode) sub-divides it into /64s and runs SLAAC for their devices — the standard ISP prefix-delegation model. It works with PPPoE, Hotspot and IPoE, and a static IPv6 prefix can be pinned per subscriber for business customers.

How it works

SAMM keeps the hot path close to the database. FreeRADIUS handles every authentication and accounting packet; on each accounting Interim-Update it calls PostgreSQL functions directly to accumulate usage and evaluate limits — there is no Python round-trip while subscribers are online.

Four execution surfaces cooperate through the single database:

  • FreeRADIUS (unlang + rlm_sql) — authenticates every packet; on each Interim-Update it accumulates bytes/uptime and evaluates limits inside Postgres.
  • samm-radius — runs time-driven sweeps (expiry, daily reset, speed windows) and is the only process that sends Change-of-Authorization packets.
  • samm-worker — pings routers and syncs MikroTik device metadata over the API.
  • samm-api — the admin & customer portals; admin actions are queued to the database and applied by samm-radius, never sent as CoAs directly.

The five services

ServiceRole
samm-apiAdmin portal + customer self-service portal + REST API
samm-radiusDrains the CoA outbox; runs expiration / daily-reset / speed-window sweeps
samm-workerPings routers; syncs MikroTik device metadata over the API
samm-notificationDelivers email & Telegram notifications through one throttled queue
samm-telegramRuns the interactive Telegram self-service bot

What SAMM does

AAA core

PPPoE & Hotspot authentication, per-user speed enforcement, hybrid CoA.

Plans & limits

Speed tiers plus four independent limits and scheduled speed windows.

Subscribers

PPPoE, Hotspot, and IPoE/DHCP users plus prepaid hotspot voucher cards with printable PDFs.

Billing

Per-plan pricing, automatic invoices, a double-entry receipts/payments/expenses ledger.

Self-service

A customer web portal and a Telegram bot for usage, invoices, and tickets.

Operations

Live MikroTik inventory, role-based admins, backup & restore, bulk tools.

System

Built-in WireGuard VPN, Cloudflare Tunnel, eight languages, themeable UI.

Notifications

Renewal, expiry, quota and receipt alerts over email and Telegram.

The rest of this manual is a how-to for every one of these areas. Use the menu on the left, or start with Installation.

Getting started

What's new

SAMM updates itself, so every install gets these features on its next update. Each line links to the page that explains how to use it.

6.0

  • Card designs: design your own printed hotspot card (size, background, your logo, a QR code that logs the card in with one scan), or start from ten ready-made designs. Each group keeps one design for printing and one for Quick Print on a thermal printer (80 or 58 mm). Hotspot cards
  • Add one card or import a list: + Card adds a card with the username, password and name you choose; Import brings in a CSV or Excel list with a preview first. Hotspot cards
  • Time and data left on the router: the hotspot status page shows what is left on a card, and the router ends the session when it runs out. Hotspot cards
  • An IP pool per user (for example a CGNAT pool), picked from your routers' pools. CGNAT & IP pools
  • Every time zone in the world, with the Middle East listed first.
  • Deep inspection: choose your MikroTik BNGs and how long to run, then read a report with a score and what to do first, in your language, as a page or a PDF. It only reads the router. Deep inspection
  • SCOOP AI: an assistant at the bottom of every page. Ask in your own words about your users, plans, invoices and routers; money, deletions and router changes wait for your Approve. SCOOP AI
  • Faster user queues: keeps calls and games smooth while a user downloads. The router wizard can set it, and Health offers a one-click fix.
  • Dashboard per role: choose whether a role sees the dashboard. A role without it opens on its first allowed page.
  • Sham Cash: on the non-official connection, a user who forgot the code can confirm the payment with the transfer number and their own address.

5.12

  • Data retention and Lookup: keep sessions for the period the law asks (two years by default), even for deleted users, and find which user had a public address and port at a given time. Every search needs a case reference and is kept in the Lookup log; a daily encrypted file can go to your NAS. Data retention & Lookup
  • CGNAT and IP pools: share public addresses between users with a block of ports each, or let SAMM give users their address itself, per router and plan. CGNAT & IP pools
  • Cisco, Huawei, Nokia and ZTE as NAS, with speeds, disconnects, a ready setup page, the Data Log and CGNAT on Cisco. Other router brands
  • FTTH: OLTs from V-SOL, Huawei, ZTE and Nokia, every ONU with its signal, ONUs linked to users, and the subscriber line lock. FTTH & OLTs
  • Device pages for every brand: CPU, memory, temperature, uptime and charts for OLTs and other routers, like MikroTik; the router form asks for the right login for each type. Other router brands
  • VPN through SAMM per router: Through SAMM or Through Router; Sham Cash payments never go through the VPN. VPN through SAMM
  • User usage: a Selected period card (total, sessions, online time) and a strip with plan, status, expiry, address and MAC; the Telegram bot lists its commands in the user's language. Users
  • We set up your server: order a ready SAMM server with your own .com domain from your dashboard. Set up your server

5.11

  • Cashier: a counter page under Accounting. Find a user by name, mobile number or part of the username as you type, then take their payment, renew them, add quota or top up their wallet in cash. It has its own permission with four ticks, shows no profit or reports, and finds only the users of the cashier's branch. Accounting, Admins, branches & roles
  • Invoice due date you choose: "Invoice due after (days)" in Accounting settings. At 0 an invoice is due when it is issued and an automatic renewal on the day the plan expires, so the grace period counts from the expiry date. Accounting
  • Downgrade compensation: moving a user to a cheaper plan can pay back the unused part of the period to their wallet or in cash, with the amount shown before you save. Change plan is also in the Users list row menu. Users
  • Auto-renew pays from the wallet, and an overdue user's wallet settles the debt before the account is suspended. Accounting
  • Notifications per channel: choose which channels each notification may use, send on all of them, and write a separate SMS text with a live character counter. Notifications
  • VPN through SAMM without a tunnel for routers on the same network as SAMM, and parental control and VPN managed for a user from the admin panel. VPN through SAMM
  • Interface quota that resets properly: Reset quota counts from zero and brings the interface back at once, at any time, with the usage since the last reset on the page. MikroTik manager
  • Websites & Apps lists per router: each router shows whether its list is up to date, with Apply and findings on the Health page; monitor values refresh every 5 seconds. MikroTik manager

5.9

  • External VPN providers: add a NordVPN, Mullvad, IVPN or AirVPN account in one step, pick how many servers and which country, or upload files from any provider such as ProtonVPN. Each user stays on one connection, connections share the load by weight, and if one stops its users keep their internet through SAMM's own line. VPN through SAMM
  • Extra quota as an add-on: sell more data without changing the user's plan or expiry, as a pack or a price per GB, in the panel or in the user portal. Add-ons
  • Wireless sectors: every user radio with the sector it is on, how long it stayed and every move, kept for a year; the switches behind your sectors with the users on each; and on the user page the chain sector › radio › switch › user with signal, range and quality. Network
  • Watch a user for 24, 48 or 72 hours: online time, speed, signal, sector and every disconnect with its cause, then a printable report with charts and a short finding. Users
  • Network map on OpenStreetMap: put your routers, sectors and users where they really are, beside the diagram. Network
  • App list updates: SAMM checks the SecuryTik app list every day; choose Notify me, Apply automatically or Off, and put the previous list back in one click. MikroTik manager
  • From and To dates in every search that has a date, Parental control and VPN filters on the Users list, and the same page open in as many windows as you have screens. Users, Dashboard
  • Move from ADV Radius: bring users and plans over from its backup file, with passwords, expiry dates, static addresses and plan limits. Tools

5.8

  • External VPN: VPN users leave through NordVPN (by access token) or any provider's WireGuard files instead of SAMM's own line, even when SAMM has no public address. VPN through SAMM
  • VPN through SAMM: chosen users send all their traffic, or only the apps they pick, out through your SAMM server instead of their local line. Allow it per user or sell it as an add-on; users switch it on in the user portal. VPN through SAMM
  • SAMM on two screens: open any page, or a single dashboard block, in its own window and keep it on a second monitor. Dashboard
  • Parental control as an add-on: sell parental control for a period, like any other add-on. Add-ons
  • Wi-Fi optimizer: a live spectrum view of every radio, the networks it hears and how busy each channel is, with a channel planner that recommends the quietest channel and best width and can move radios by itself at night. Network
  • Ubiquiti devices: add UniFi access points and airOS radios as monitored devices. UniFi radios show their clients, neighbouring networks and spectrum, and the optimizer really moves them to a better channel and width. MikroTik manager
  • Three monitors for every router on every plan: access points and radios you only watch no longer use up your router allowance. MikroTik manager
  • Bring in the users a router already keeps (PPP, Hotspot and User Manager, RouterOS 6 and 7) with their passwords, plans, limits, names, phone numbers and end dates, in the background. MikroTik manager
  • Take back a renewal: deleting a renewal's invoice can return the user's expiry to where it was, Renew Plan can be undone from the top bar, and the Invoices list shows totals for everything the filter shows. Undo & approvals
  • Backups to your own Google Drive. Connect Google Drive on Backup & Restore with a short code; every automatic backup is then also copied to a SAMM Backups folder in your Drive, and any copy can be brought back to restore it. Tools
  • Fixed renewal time on a plan: every expiry lands on the time you choose, rounded up so a user never gets less than the period. Plans
  • Address list per plan: the router adds each user's address to a list named like their plan, for your own firewall, queue and routing rules. Plans
  • Self Service Collect Mode: guests type their name and mobile number and are online at once, with no passcode; every login is kept for export. Self Service
  • A clearer Connection quality chart with axes, download and upload lines, details on hover and data used, plus e-mail in the Users search and any port in the Data Log search. Users, Data Log

5.7

  • Branches own their devices. Every router and access point belongs to a branch or to Headquarters; branch staff manage their own and only view the ones above them, and a setting lets users log in only through their branch's routers. Admins, branches & roles
  • Role time limits. Cap how many periods or days ahead a role may give, start new users with a fixed time (for example 2 hours), and split Add days from typing an expiry date. Admins, branches & roles
  • SSTP VPN beside WireGuard and L2TP/IPsec, for several routers behind the same public address. VPN
  • RouterOS 6 works everywhere: wizard, Auto-Complete, config delivery, bulk actions, Websites & Apps, QoS and VPN links. RouterOS 6
  • Parental control in the user portal: block categories, apps and websites, always or on a weekly calendar. Parental control
  • Points & rewards for renewals and invited friends, spent on faster speed or free days. Points & rewards
  • Your brand on the admin panel, the user portal and the sign-in pages, with a logo you crop in the browser. Branding
  • Language switches, plan visibility in the portal, SMS template mode and a one-line SAMM install on a MikroTik router. Languages, Plans, MikroTik container

5.6

  • Config delivery: every change sent to your routers is tracked with a result per router, reaches offline routers when they come back, and retries by itself. Config delivery
  • A dashboard that opens in about a second, and a sidebar that stays in place while pages change.

5.5

  • Data Log search across every user: who reached an address, port, protocol or app, in any period. Data Log
  • Detailed permissions under Edit (delete users, extend, change plan, pay invoices, run router scripts…), and a preview of the new expiry before you renew. Roles

5.4

  • Financial by branch: every invoice, payment, expense and cash account belongs to a branch, with a branch selector, cash handovers and a branches report. Accounting & billing

5.3

  • Sham Cash, one checkout for every payment method, a public Pay page and Renew online for 1 to 12 periods. Online payments
  • Invoice discounts, add-ons with free apps, the Activations report, change username and down payments on renewals. Add-ons

5.2

  • Dynamic Speed Booster, Manager actions on many routers at once, add-ons, price lists per branch, user files, custom fields, the Traffic page and the History cleaner. Speed Booster, Manager actions

Getting started

Installation

SAMM installs everything it needs — FreeRADIUS, PostgreSQL, nginx, WireGuard, cloudflared, and the five SAMM services — in one step. The installer is idempotent: re-running it upgrades an existing install in place and never overwrites your config or regenerates your database password.

Installation manual

Every step with screenshots: Windows (including turning on virtualization in the BIOS), Ubuntu, a MikroTik router, a ready server, the licence (pay, link, renew), connecting your routers over the VPN, and the extra features.

SAMM runs anywhere — pick the install path that fits your network:

Prerequisites

  • A fresh server: Ubuntu 22.04 / 24.04 / 26.04 LTS, or Debian 12 / 13. Server-grade Linux only — desktop variants are not supported.
  • Root / sudo access and an internet connection.
  • systemd, and a host where PostgreSQL can be installed locally (one is set up for you).

Installation

Option A — install with one command

On the server, run:

curl -fsSL https://samm.securytik.com/install.sh | sudo bash

This bootstrap script downloads the latest SAMM release bundle from GitHub, extracts it, and runs the full installer automatically. Done in a few minutes.

If github.com is blocked in your country, use the Cloudflare-hosted mirror instead — same installer, nothing fetched from GitHub. (The standard command above also detects a blocked GitHub and switches to this mirror by itself.)

curl -fsSL https://dl.securytik.com/install.sh | sudo bash

Either way, once the installer finishes, open the admin portal and sign in with these credentials:

Login URLhttp://<your-server>/admin · Usernameadmin · Passwordadmin

Change the admin password immediately after your first login.

Installation

Option B — install on Windows (Hyper-V)

SAMM runs on Windows inside its own small Ubuntu 24.04 virtual machine on Hyper-V, created and managed by one installer. The VM joins your network with its own IP address, so your MikroTik routers reach SAMM directly — RADIUS sees each router's real address, and CoA disconnects work — exactly like a Linux server.

Open PowerShell as administrator — not Command Prompt (cmd): right-click the Start button, choose Terminal (Admin) or Windows PowerShell (Admin), answer Yes. Then run:

irm https://samm.securytik.com/install-windows.ps1 | iex

If samm.securytik.com cannot be reached from this PC, use the Cloudflare-hosted mirror instead — the same installer. (The installer itself also switches to the mirror by itself when a download fails.)

irm https://dl.securytik.com/install-windows.ps1 | iex

Either way, once the installer finishes, open the admin portal and sign in with these credentials:

Login URLhttp://<SAMM IP>/admin · Usernameadmin · Passwordadmin
OS login (SSH)samm / samm · Root (console)root / samm

The same defaults as the SAMM Server ISO. Change all of them after your first login. The SAMM Info shortcut on the desktop shows them again, with SAMM's IP address and how to reach the VM over SSH.

What it asks

  1. Which network SAMM should join, when the PC has more than one connected adapter. Press Enter for the recommended one (wired before Wi-Fi).
  2. SAMM's IP address on that network. It suggests a free one; press Enter to accept it, type another, or type dhcp.

If Hyper-V is off, the installer turns it on and asks to restart Windows once; after you sign in again it carries on by itself. The rest — Multipass, the network bridge, the VM and SAMM itself — takes 10 to 20 minutes, with a progress bar.

Requirements

  • Windows 10 / 11 Pro, Enterprise or Education, or Windows Server 2019 and newer (64-bit). Windows Home has no Hyper-V.
  • Hardware virtualization turned on in the BIOS/UEFI (Intel VT-x or AMD-V). The installer checks it and stops with a clear message if it is off — see Turn on virtualization.
  • At least 8 GB of memory, with 4 GB free for SAMM's VM (3 GB is the minimum; other virtual machines — VMware, VirtualBox — count against it), and 40 GB of free disk.
  • A network cable is strongly recommended. Many Wi-Fi drivers cannot bridge a virtual machine onto the network, and then nothing but the PC itself can reach SAMM.

After installing

  • Open the admin panel at http://<SAMM IP>/admin/login (a SAMM Admin shortcut is on the desktop), sign in with admin / admin and change the password at once.
  • Point your MikroTik RADIUS at the SAMM IP (UDP 1812/1813) — the Router Wizard in the panel does it for you.
  • SAMM starts with Windows, before anyone signs in, and the PC is set never to sleep. On a laptop keep the charger connected and set closing the lid to "Do nothing".
  • To remove it: run the same line with -Uninstall, or & ([scriptblock]::Create((irm https://samm.securytik.com/install-windows.ps1))) -Uninstall.

Installation

Turn on virtualization in the BIOS/UEFI

SAMM on Windows runs in a Hyper-V virtual machine, which needs the processor's virtualization feature: Intel Virtualization Technology (VT-x) on Intel, or AMD-V — usually called SVM Mode — on AMD. Most PCs ship with it on; some have it off. Every brand hides it in a different menu, so here are the general steps and where it usually is.

First, check whether it is already on

Open Task Manager (Ctrl+Shift+Esc) → Performance → CPU. Under the graph, Virtualization: Enabled means you are done. (With Hyper-V already on, Windows may show a line saying a hypervisor was detected instead — that also means it is on.)

General steps

  1. Save your work and restart the PC.
  2. Open the BIOS/UEFI setup: press the setup key repeatedly as soon as the screen lights up (see the table). On Windows 10/11 you can also go to Settings → System → Recovery → Advanced startup → Restart now, then Troubleshoot → Advanced options → UEFI Firmware Settings → Restart.
  3. Look in the Advanced, Advanced CPU, Processor, Chipset, Security or Virtualization menu for Intel Virtualization Technology, Intel VT-x, SVM Mode or AMD-V, and set it to Enabled. (Intel VT-d / AMD IOMMU is not needed.)
  4. Save and exit (usually F10), let Windows start, then run the SAMM installer again.

Where it usually is

BrandSetup keyUsual place
DellF2Virtualization Support → Virtualization / Enable Intel Virtualization Technology
HPF10 (or Esc, then F10)Advanced (or Security / System Configuration) → Virtualization Technology (VTx)
LenovoF1 / F2 (or the Novo button)Security (ThinkPad) or Configuration → Intel Virtualization Technology / AMD SVM Technology
ASUSF2 / DelAdvanced Mode (F7) → Advanced → CPU Configuration → Intel Virtualization Technology or SVM Mode
AcerF2Advanced (or Main) → Intel Virtualization Technology
MSIDelOC → CPU Features → Intel Virtualization Tech or SVM Mode
GigabyteDelTweaker (or Advanced) → Advanced CPU Settings → Intel Virtualization Technology or SVM Mode
Servers (Dell iDRAC, HPE, Supermicro)F2 / F9 / DelProcessor Settings → Virtualization Technology — often already on
A virtual machine inside another virtual machine (Windows itself running in VMware, Proxmox or Hyper-V) needs nested virtualization switched on in the outer hypervisor instead — for example "Virtualize Intel VT-x/EPT" in VMware's CPU settings, with the VM powered off.

Installation

Option C — install manually from a release bundle

Download the latest samm-<version>.tar.gz from the GitHub Releases page, then on the server:

tar -xzf samm-<version>.tar.gz
cd samm-<version>
sudo bash install.sh

You can also deploy from a zip produced on another machine — the installer rsyncs the source into /opt/samm itself:

mkdir -p /opt/samm && unzip samm.zip -d /tmp/samm-bundle
sudo bash /tmp/samm-bundle/samm/install.sh

Or clone the repository to /opt/samm and run sudo bash /opt/samm/install.sh.

Either way, once the installer finishes, open the admin portal and sign in with these credentials:

Login URLhttp://<your-server>/admin · Usernameadmin · Passwordadmin

Change the admin password immediately after your first login.

Installation

Option D — install with Docker Compose

If you'd rather run SAMM as containers — same product, packaged differently — use the Docker Compose distribution at github.com/mhdhaidarah/samm-docker. On any host with Docker available:

curl -fsSL https://github.com/mhdhaidarah/samm-docker/releases/latest/download/install.sh | sudo bash

That installs Docker if it's missing, drops a docker-compose.yml into /opt/samm-docker/ with a strong random database password already filled in, and starts the stack. The image mhdhaidarah/samm is built from the same compiled bundle as the bare-OS install — closed source by construction.

Multi-arch — the same tag ships for linux/amd64 and linux/arm64, and the right variant is selected automatically from the tag: docker pull on any Docker host (Intel/AMD, ARM server, Apple-silicon Mac), and MikroTik RouterOS 7.23+ on the router itself. One file, every platform.

On hosts where piping curl to bash isn't allowed (locked-down boxes, strict egress policies), you can fetch the ready-to-run compose file directly:

git clone https://github.com/mhdhaidarah/samm-docker.git
cd samm-docker
# optional: edit docker-compose.yml and replace change-me-strong-random-string
docker compose up -d

A few features are not yet in the Docker variant (staged license lockdown, dynamic FreeRADIUS reload). The built-in WireGuard and Cloudflare Tunnel admin pages are intentionally hidden in the Docker variant — they manage host-level systemd services that aren't reachable from inside the container. Pick Option A or C above if you need those built in, or run cloudflared / wg-quick on the Docker host directly alongside SAMM. See the Docker variant's README for the full v1 caveats and the manual install path.

On Windows (Docker Desktop) — evaluation only

Not recommended for production. Windows sleep / hibernate / lid-close stops the containers; boot-restart only fires when WSL starts (not on Windows boot); the daily auto-update cron only runs while WSL is alive. Use it for evaluation / demo, then deploy production on a Linux VM (Hyper-V, Proxmox, ESXi) or a small physical box (e.g. a NUC running Ubuntu Server).

Install Docker Desktop for Windows (lets it set up the WSL2 backend on first launch). Then from PowerShell — no WSL terminal needed — grab the compose bundle and start the stack:

mkdir C:\samm-docker
cd C:\samm-docker
curl.exe -fLO https://github.com/mhdhaidarah/samm-docker/releases/latest/download/docker-compose.yml
# optional: notepad docker-compose.yml — replace change-me-strong-random-string with your own password
docker compose pull
docker compose up -d

Watch the stack boot in Docker Desktop → Containers — the samm group expands into 8 services. Once they're all green, open the admin portal and sign in with these credentials:

Login URLhttp://localhost:8000/admin · Usernameadmin · Passwordadmin

Change the admin password immediately after your first login.

If a real MikroTik NAS will hit this Windows host for RADIUS, allow UDP 1812 + 1813 through Windows Firewall:

New-NetFirewallRule -DisplayName "SAMM RADIUS" -Direction Inbound -Protocol UDP -LocalPort 1812,1813 -Action Allow

Tear down: docker compose down -v from the install dir (the -v wipes the postgres volume and the Fernet key — back them up first if you've added data).

Installation

Option E — install on a MikroTik router (RouterOS 7.23+)

Same SAMM, no Linux box needed. If your MikroTik device supports the container package and has a USB drive or microSD attached, you can run the whole stack directly on the router — with the same docker-compose.yml used everywhere else. RouterOS 7.23+ pulls the right CPU architecture from the multi-arch image tags automatically, so there is nothing router-specific to download.

Supported: every container-capable MikroTik router — RB5009, hAP ax², CCR2004-1G-12S+2XS, CCR2116, CCR2216, L009, and similar (arm64), plus x86 RouterOS and CHR (amd64). Not supported: armv7 / mipsbe / smips / tile / ppc devices (hEX, RB750, older RB models) — no container support or too little RAM/CPU for SAMM's stack. RouterOS 7.23 or newer is required (older versions can't select the architecture from a multi-arch tag).

The quick way: one pasted line

Open the router's terminal (WinBox → New Terminal, or SSH) and paste this one line:

/tool fetch url="https://samm.securytik.com/install-routeros.rsc" dst-path=samm-install.rsc; /import samm-install.rsc

It checks the router's RouterOS version, CPU and memory, installs the container package, turns on container mode, finds an ext4 disk of at least 30 GB, downloads SAMM with a strong random database password, starts it and waits until the panel answers. When it asks you to (after a reboot, after the power cycle, after you prepare the disk), paste the same line again: each step checks what is already done and carries on. It never formats a disk by itself and never touches anything already running.

Prefer to do it by hand? Follow the steps below.

1. Prepare the router

Install the container package (from extra_packages.zip on mikrotik.com/download — upload the matching container-*.npk via Files, then reboot). Then enable container mode (one-time — it activates only after a hard power cycle, not a soft reboot):

/system device-mode update container=yes
# HARD reboot the router (unplug the power) — a soft /system reboot
# will NOT activate the container feature

2. Format and mount the disk (ext4)

Insert a USB drive or microSD (≥ 8 GB recommended — Postgres + image layers add up). On the router:

/disk print
# note the disk slot, e.g. "usb1-part1" or "disk1"
/disk format usb1-part1 file-system=ext4 label=samm

After formatting, verify the disk mounts and is writable:

/disk print detail
# look for "type=ext4" and a mount point like "/usb1-part1"

Then tell the router where to download the images from (Docker Hub) and where to unpack them — without this every SAMM container fails with "download/extract error: no registry url set":

/container config set registry-url=https://registry-1.docker.io tmpdir=samm/tmp layer-dir=samm/layers
# "samm" = your disk's Mount Point (System > Disks > the disk > Mount Point)
# if layer-dir is refused on your RouterOS version, keep only tmpdir
/ip dns set servers=8.8.8.8,1.1.1.1
:put "ok"
Seeing "no registry url set" or "not enough disk space to download layer"? Run the lines above — the download folder must be on the USB/microSD disk (its mount point), not the router's own small storage. Then in App → samm untick Enabled, Apply, tick it again and Apply: the router downloads every SAMM part again and starts it.

3. Copy the compose file

One file for every platform. Replace change-me-strong-random-string (the Postgres password — use the same strong value everywhere it appears) and change-me-random-token. Then in WebFig/WinBox: Container → Apps → + New → YAML, paste, set the ext4 disk from step 2 as storage, submit. RouterOS 7.23+ pulls the right CPU architecture from the image tags automatically.

Stuck at "waiting for reverse proxy"? On RouterOS 7.23+, untick Use HTTPS in the Apps dialog and re-deploy — that option controls the app's web-UI proxy, not how images are pulled.
docker-compose.yml
name: samm

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: samm
      POSTGRES_USER: samm
      POSTGRES_PASSWORD: change-me-strong-random-string
      TZ: UTC
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U samm -d samm"]
      interval: 10s
      timeout: 5s
      retries: 12

  samm-api:
    image: mhdhaidarah/samm:latest
    restart: unless-stopped
    command: ["api"]
    environment:
      SAMM_ROLE: api
      POSTGRES_HOST: postgres
      POSTGRES_PORT: 5432
      POSTGRES_DB: samm
      POSTGRES_USER: samm
      POSTGRES_PASSWORD: change-me-strong-random-string
      TZ: UTC
      SAMM_API_HOST: 0.0.0.0
      SAMM_API_PORT: 8000
      SAMM_API_WORKERS: 2
      WA_BRIDGE_URL: http://wa-bridge:8787
      WA_BRIDGE_TOKEN: change-me-random-token
      SAMM_SCOOP_URL: http://samm-scoop:4097
    depends_on:
      postgres:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8000/health >/dev/null || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 30
      start_period: 1800s
    ports:
      - "8000:8000"
    volumes:
      - etcsamm:/etc/samm
      - sammvar:/opt/samm/var
      - sammlogs:/var/log/samm
      - sammlocales:/opt/samm/app/locales

  samm-scoop:
    image: mhdhaidarah/samm:latest
    restart: unless-stopped
    command: ["scoop"]
    environment:
      SAMM_ROLE: scoop  # see samm-api notes — parser-agnostic role hint
      POSTGRES_HOST: postgres
      POSTGRES_PORT: 5432
      POSTGRES_DB: samm
      POSTGRES_USER: samm
      POSTGRES_PASSWORD: change-me-strong-random-string
      TZ: UTC
      SAMM_API_URL: http://samm-api:8000
    depends_on:
      samm-api:
        condition: service_healthy
    volumes:
      - etcsamm:/etc/samm
      - sammvar:/opt/samm/var
      - scoopengine:/opt/samm/runtime/scoop
      - scoophome:/var/lib/samm-scoop

  samm-radius:
    image: mhdhaidarah/samm:latest
    restart: unless-stopped
    command: ["radius"]
    environment:
      SAMM_ROLE: radius  # see samm-api notes — parser-agnostic role hint
      POSTGRES_HOST: postgres
      POSTGRES_PORT: 5432
      POSTGRES_DB: samm
      POSTGRES_USER: samm
      POSTGRES_PASSWORD: change-me-strong-random-string
      TZ: UTC
    depends_on:
      postgres:
        condition: service_healthy
      samm-api:
        condition: service_healthy
    volumes:
      - etcsamm:/etc/samm
      - sammvar:/opt/samm/var
      - sammlogs:/var/log/samm

  samm-worker:
    image: mhdhaidarah/samm:latest
    restart: unless-stopped
    command: ["worker"]
    environment:
      SAMM_ROLE: worker  # see samm-api notes — parser-agnostic role hint
      POSTGRES_HOST: postgres
      POSTGRES_PORT: 5432
      POSTGRES_DB: samm
      POSTGRES_USER: samm
      POSTGRES_PASSWORD: change-me-strong-random-string
      TZ: UTC
    depends_on:
      postgres:
        condition: service_healthy
      samm-api:
        condition: service_healthy
    cap_add:
      - NET_RAW
    sysctls:
      - net.ipv4.ping_group_range=0 2147483647
    volumes:
      - etcsamm:/etc/samm
      - sammvar:/opt/samm/var
      - sammlogs:/var/log/samm

  samm-notification:
    image: mhdhaidarah/samm:latest
    restart: unless-stopped
    command: ["notification"]
    environment:
      SAMM_ROLE: notification  # see samm-api notes — parser-agnostic role hint
      POSTGRES_HOST: postgres
      POSTGRES_PORT: 5432
      POSTGRES_DB: samm
      POSTGRES_USER: samm
      POSTGRES_PASSWORD: change-me-strong-random-string
      TZ: UTC
      WA_BRIDGE_URL: http://wa-bridge:8787
      WA_BRIDGE_TOKEN: change-me-random-token
    depends_on:
      postgres:
        condition: service_healthy
      samm-api:
        condition: service_healthy
    volumes:
      - etcsamm:/etc/samm
      - sammvar:/opt/samm/var
      - sammlogs:/var/log/samm

  samm-telegram:
    image: mhdhaidarah/samm:latest
    restart: unless-stopped
    command: ["telegram"]
    environment:
      SAMM_ROLE: telegram  # see samm-api notes — parser-agnostic role hint
      POSTGRES_HOST: postgres
      POSTGRES_PORT: 5432
      POSTGRES_DB: samm
      POSTGRES_USER: samm
      POSTGRES_PASSWORD: change-me-strong-random-string
      TZ: UTC
    depends_on:
      postgres:
        condition: service_healthy
      samm-api:
        condition: service_healthy
    volumes:
      - etcsamm:/etc/samm
      - sammvar:/opt/samm/var
      - sammlogs:/var/log/samm

  wa-bridge:
    image: mhdhaidarah/samm:wa-bridge-latest
    restart: unless-stopped
    environment:
      WA_BRIDGE_TOKEN: change-me-random-token
      TZ: UTC
    depends_on:
      - samm-api
    volumes:
      - wabridge_auth:/data/auth      # multi-device session — persists the QR link

  freeradius:
    image: mhdhaidarah/samm:freeradius-latest
    restart: unless-stopped
    environment:
      POSTGRES_HOST: postgres
      POSTGRES_PASSWORD: change-me-strong-random-string
      TZ: UTC
    depends_on:
      postgres:
        condition: service_healthy
      samm-api:
        condition: service_healthy
    ports:
      - "1812:1812/udp"
      - "1813:1813/udp"

volumes:
  pgdata: {}
  etcsamm: {}
  sammvar: {}
  sammlogs: {}
  sammlocales: {}
  wabridge_auth: {}      # WhatsApp bridge multi-device session
  scoopengine: {}        # SCOOP AI engine (OpenCode) and the previous one, for rollback
  scoophome: {}          # SCOOP AI's saved AI logins and conversations

4. Verify and connect MikroTik to SAMM

Once the SAMM containers are running, open the admin portal in a browser and sign in with these credentials:

Login URLhttp://<router-ip>:8000/admin · Usernameadmin · Passwordadmin

Change the admin password immediately. RADIUS auth + accounting are exposed on UDP 1812 + 1813 on the router itself, so the MikroTik RADIUS client can point at 127.0.0.1 with the shared secret you set in System → RADIUS.

Experimental deployment path. RouterOS's container feature is leaner than Docker Compose — service-name DNS, dependency ordering (depends_on), and live restarts behave differently. If the stack misbehaves on your hardware, fall back to running Docker on a small Linux box (NUC, Pi 4, Linux VM) next to the MikroTik. The same compose file works there with full Compose semantics.

Keep SAMM running after a reboot or a crash

RouterOS creates the app's containers without auto-start. Run this once after the install: every SAMM container starts with the router and restarts if it stops, and a small watchdog starts any stopped one every minute.

/container set [find where name~"^app-samm"] start-on-boot=yes restart-policy=always
/system scheduler remove [find name=samm-watchdog]
/system scheduler add name=samm-watchdog start-time=startup interval=1m on-event=":foreach c in=[/container find where name~\"^app-samm\" and stopped] do={/container start \$c}"
:put "ok"

5. Updating — back up and restore by hand

Updating a MikroTik container app deletes your database. RouterOS cannot change an installed app's version in place — the only way is to remove the app and add it again, and removing it deletes everything the app stored, including SAMM's database. Take a backup and download it to your computer BEFORE you remove the app. A backup left on the router is deleted with everything else.

To move a MikroTik container install to a new version:

  1. In SAMM, go to Tools → Backup, create a backup, and download the file to your computer.
  2. On the router, remove the app and add it again with the new version.
  3. Open the fresh SAMM, go to Tools → Backup and restore the file you downloaded.

This applies to the MikroTik container only. On Docker (Linux, Windows, or a Linux VM) an update is docker compose pull then docker compose up -d, and your data is untouched — the volumes live outside the containers and survive.

Installation

Option F — SAMM Server ISO (appliance install)

The SAMM Server ISO turns any empty machine or VM into a ready SAMM server: boot it, choose DHCP or a static IP on the one screen it shows, confirm, and walk away. It installs Ubuntu Server 24.04 LTS (minimized), names the host samm-server, then installs SAMM on first boot from the ISO itself, with or without internet; as soon as the server is online it updates itself once to the latest release. The console shows a SAMM boot splash and a login banner with the server's IP, the admin-panel address and the default credentials, and a samm-tools command gives one-keystroke access to the maintenance tools (health check, database backup/restore, admin password reset).

The ISO erases the machine's first disk. Boot it only on hardware or a VM dedicated to SAMM. No internet is needed: SAMM is on the ISO and works on a closed network.

Write it to a USB stick (Rufus, balenaEtcher, or dd) or attach it to a VM, boot, and answer the network question. Default logins after install — panel: admin / admin, OS: samm / samm or root / samm — change all of them.

Download SAMM Server ISO 2.5 GB

SHA-2560aa7c06bea4aba8ce7f632aacf243639ac7f78359cc0aa72005d88735930e9be

Installation

Installer reference

Non-interactive options

All prompts can be pre-answered with environment variables, so the installer can run unattended:

VariableEffect
DB_PASSUse this database password instead of an auto-generated one (first install only)
CF_TOKENInstall the Cloudflare Tunnel connector with this Zero Trust token
SAMM_HTTP_PORTForce the nginx listen port (skips the port-80 detection prompt)
SAMM_VERBOSE1 streams raw command output instead of the progress bar
NO_COLOR1 disables colored output
DB_PASS='strong_pw'   sudo bash /opt/samm/install.sh
CF_TOKEN='eyJ...'     sudo bash /opt/samm/install.sh
SAMM_HTTP_PORT=8080   sudo bash /opt/samm/install.sh

What the installer sets up

The installer runs as a live, colored progress display — a percentage bar and a per-phase checklist. Each phase's raw output is captured to /var/log/samm-install.log; on failure the last 30 lines are printed.

ComponentDetails
FreeRADIUS 3Configured with a PostgreSQL backend and dynamic NAS clients; validated with freeradius -CX
PostgreSQLDatabase, schema, and all SQL migrations applied — every migration file is idempotent
Python venvAll dependencies built from requirements.txt; translation catalogs compiled. If the distro's Python doesn't match the compiled bundle, the installer fetches a matching standalone interpreter into /opt/samm/runtime automatically
nginxReverse proxy added additively — existing sites are never removed. Uses port 80 when free; otherwise prompts for an alternate port
5 servicessamm-api, samm-radius, samm-worker, samm-notification, samm-telegram — all enabled as systemd units
WireGuardPackages installed; configured later from System → VPN
cloudflaredBinary always installed; the tunnel token is optional at install or added later from System → Cloudflare Tunnel

All credentials — the database password and the session signing keys — are generated automatically on first install.

Interactive prompts

Any prompts happen up front, before installation begins:

  • Cloudflare token — paste a Zero Trust connector token to publish SAMM online with no open ports, or press Enter to skip and configure it later.
  • HTTP port — if port 80 is already in use, the installer leaves those sites untouched and asks for an alternate port (default 8080).

Install summary

When the installer finishes it prints a summary with the admin URL, the default login, the chosen HTTP port, the database credentials, and the config-file paths:

============================================================
  SAMM is installed and running.
  Admin portal  : http://localhost/admin/login
  Default login : admin / admin   <- CHANGE AFTER FIRST LOGIN
  Config files  : /etc/samm/samm.yaml  /etc/samm/api.env
============================================================

Upgrading

To upgrade, fetch the new source and re-run the installer:

git -C /opt/samm pull        # or unpack a newer release bundle
sudo bash /opt/samm/install.sh

The re-run re-syncs the source, upgrades the venv, re-applies all migrations, reloads the FreeRADIUS and nginx configs, and restarts every service. Your config files and the HTTP port chosen at first install are preserved.

Tip SAMM can also update itself — see Licensing & updates. Enable automatic updates, or apply them on demand, from System → License.
Air-gapped & remote DB SAMM ships only SAMM — FreeRADIUS, PostgreSQL, nginx and the rest are fetched at install time from upstream apt repos, so air-gapped installs must pre-stage those packages. For a remote PostgreSQL, set the DSN in /etc/samm/samm.yaml after install.

Getting started

First steps

Five short tasks take a fresh install to the point where subscribers can connect and be billed.

1 · First login

  1. Open http://<your-server>/admin/ (use the HTTP port from the install summary if it is not 80), or your Cloudflare tunnel URL.
  2. Sign in with admin / admin.
  3. Immediately change the password from System → Admins, or from the profile menu in the top bar.

2 · Add your first router

  1. Go to MikroTik → NAS and click Add Router.
  2. Enter the router's IP, a shortname, and a RADIUS shared secret. For MikroTik devices, optionally add API credentials for live device sync.
  3. On the MikroTik, add a RADIUS server pointing at the SAMM host (ports 1812/1813) with the same shared secret, and enable RADIUS for PPP / Hotspot.

No FreeRADIUS restart is needed — SAMM resolves NAS clients dynamically from the database. See Routers (NAS) for the full procedure, or let the setup wizard configure the MikroTik for you.

3 · Create a plan

A plan defines the speed, the limits, and the price you sell. Go to Users → Plans → New plan. Full field reference: Plans & limits.

4 · Add a subscriber

Go to Users → New customer, fill in the login credentials and pick a plan. The subscriber can connect immediately. For prepaid hotspot access, generate voucher cards instead.

5 · Activate your license

A fresh install runs unregistered at a minimum tier. Open System → License and activate to lift the limits — see Licensing & tiers.

Day-to-day rhythm Add routers → create plans → add subscribers or cards → watch the Dashboard → record payments under Accounting.

Getting started

Migrate from another system

Already running another RADIUS billing system? SAMM reads its data and recreates your plans and subscribers, so you do not retype anything. Subscribers keep their existing service password and expiry date, which means they keep logging in exactly as before.

Go to Tools → Export / Import and pick your old system under Migrate from another system. Like the rest of Tools, it is superadmin-only.

What to upload

Old systemFileWhere it comes from
SAS4 / Radius Manager .sql or .sql.gz A MySQL backup of the old database
Super Speed Radius .sql or .sql.gz A MySQL backup of the old database
Pro Radius .xlsx or .csv Its exported subscriber list — that system offers no backup export

Database backups are often several gigabytes; that is fine, upload the file as-is. Compressed backups do not need unpacking first.

How it works

  1. Upload the file. Nothing is written yet.
  2. Review the preview. It lists the plans and subscribers that would be created, warns about anything it had to skip or correct, and checks the total against your license before you commit.
  3. Choose what happens to usernames that already exist in SAMM — skip them and keep the SAMM record, or update its name and contact from the old system.
  4. Import. Each row is written independently, so a single bad row never rolls back the rest.

What comes across

  • Plans — name, speeds, price, duration and traffic quota where the old system records them.
  • Subscribers — username, service password, name, contact details, expiry date, plan, static IP and MAC.
  • Subscribers disabled in the old system stay disabled.

Billing, invoices, prepaid cards, tickets, accounting and admin logs are deliberately not imported — they belong to the old system's data model and rarely map cleanly.

Values that do not match their column

Real databases are messy: an address typed into the email box, a note in the mobile field, a phone number written on an Arabic keyboard. SAMM checks every value against what its column is supposed to hold. Anything that does not fit is kept out of that field and saved to the subscriber's admin-only notes instead, tagged with where it came from — so nothing is lost and no field is polluted. The preview tells you how many values this affected.

Pro Radius specifics

Pro Radius exports subscribers but not plans, so SAMM works the plans out from each subscriber's service level, taking the speed from its name (a service called "4MBPS" becomes a 4 Mbps plan). Three things are simply not in that file and are set to sensible defaults you should review afterwards:

  • Duration — set to 1 month. Each subscriber's real expiry date is imported unchanged, so this only affects future renewals.
  • Upload speed — set to match the download rate.
  • Price — set to 0.
Review the plans before invoicing After a Pro Radius import, open Plans and set the real price and period for each one. Until you do, those plans bill at zero.

Good to know

  • Run it more than once safely. Re-importing the same file skips everyone already present rather than duplicating them.
  • Your license still applies. If the file holds more subscribers than your tier allows, the preview says so up front and tells you how many would fit — you can upgrade, or import a partial set.
  • Take a backup first if you are importing into an install that already has real data.

Subscribers & plans

Plans & limits

A plan is the service definition assigned to subscribers — it sets the speed, the limits, and the price. Create plans before adding users.

A fresh install already ships 9 ready-to-use plans — eight monthly speed tiers plus an "Expired" throttle plan — so you can sell immediately or create your own. Seeding runs only on first install and never overwrites plans you've added.

Create a plan

  1. Go to Users → Plans.
  2. Click New plan.
  3. Fill in the form and click Save plan.

Each limit is a toggle — enable only the ones you need. The same modal edits an existing plan (open the row's ⋮ menu → Edit).

Plan fields

FieldMeaning
NameUnique plan name, e.g. Home-50M
PriceCharged per billing period when invoicing is used
Download / Upload speede.g. 50M, 512K, 1G — enforced as the MikroTik rate limit
Simultaneous sessionsHow many devices may be online at once on this plan. 1 by default — a second login is refused while the first is still connected. Set 0 for unlimited. A session that stopped reporting is ignored, so a dropped connection never locks the subscriber out
Limit: ExpirationThe subscription ends a fixed period after activation (days/months/hours/minutes)
Limit: QuotaA total data cap (combined, download-only, or upload-only) for the whole subscription
Limit: UptimeA cap on cumulative connected time — the sum of all session durations
Limit: Daily usageA data cap that resets every day at the configured daily-reset time
Unlimited windowQuick-add of one speed window — the full editor lives in the plan's Speed Windows page
IP poolOptional RADIUS Framed-Pool name for address assignment
Auto-renewStart a fresh period on expiry instead of switching plan or disconnecting

The four limits

Each limit is independent and optional. When several are set, SAMM checks them in a fixed order — expiration → quota → uptime → daily — and the first one exhausted decides the action.

LimitTracksOn exhaust
ExpirationCalendar time since activationSwitch to another plan, or disconnect
QuotaTotal bytes usedSwitch to another plan, or disconnect
UptimeCumulative session secondsSwitch to another plan, or disconnect
DailyBytes since the last daily resetThrottle — to speeds you enter, or via a slower plan — until the next daily reset

For each limit you choose what happens on exhaust: pick a next plan to switch the subscriber onto, or leave it as — disconnect —. The daily limit throttles instead of disconnecting: by default you enter the throttle speeds directly (download / upload fields), or pick a slower "next" plan — either way the subscriber reverts to the original plan at the next daily reset automatically.

Speed windows

A speed window overrides the plan's base speed for set hours — for example an unlimited-speed window after midnight. Click a plan row to open its Speed Windows editor, which adds day-of-week control and supports windows that cross midnight. When several windows match, the highest-speed one wins.

Note Throttled or limit-exhausted subscribers are excluded from speed windows — SAMM never lifts speed while a limit is in force.

Two notions of usage

SAMM keeps usage in two places, and never conflates them:

  • Resettable counters — the per-limit state. Zeroed by an admin reset and by the daily reset.
  • Billing counters — non-resettable lifetime totals. Never zeroed, so reports and invoices stay accurate.

Managing plans

The Plans list shows each plan's speed, subscriber count, active limits, and speed windows. From a row's ⋮ menu you can edit, open its speed windows, enable/disable it, jump to its subscribers, or delete it (only when it has no subscribers). Editing auto-renew offers to propagate the change to all current subscribers.

Duplicate copies a plan exactly — speeds, limits, speed windows and price — under a new name, which is far quicker than rebuilding a tariff by hand to change one number. If the name you give is already taken, the next free number is used.

Which plans users see

The Users can see this plan switch on each plan (also a bulk action on the Plans list) decides which plans users see and can choose in their portal. It starts off for every plan, so nothing is shown until you choose; a user always sees their own plan.

Subscribers & plans

Subscribers

A subscriber (customer / user) is a PPPoE or Hotspot account that authenticates against SAMM. Each subscriber is assigned exactly one plan.

Create a subscriber

  1. Go to Users and click New customer.
  2. Complete the form and save — the subscriber can connect immediately.
FieldMeaning
Username *The PPPoE / Hotspot login name — must be unique
Password *The login password (stored for PAP/CHAP RADIUS auth)
First / Last nameThe subscriber's name
Mobile / Email / AddressContact details — used for notifications and invoices
Plan *The service plan to assign
Expiration overrideOptional manual expiry date instead of the plan's computed one
Auto-renewRenew the plan period automatically on expiry

Create many subscribers at once

New batch users creates a numbered run of accounts in one pass — the usual way to hand a block of logins to a village rollout, a hotel, or a reseller. Choose how many, what number to start at, and how many digits to pad to (3 gives 001, 002, …); everything else — plan, expiration, auto-renew — is filled in once and applied to all of them. They share one password.

The invoice choice applies to each user in the batch separately, so a run of fifty either raises fifty invoices or none, and the total is shown before you commit.

The subscriber list

The Users page lists every subscriber with an at-a-glance status dot, the assigned plan, and how much of each limit is left — daily usage with a progress bar, quota remaining, uptime remaining, and days left. Filter by status (All / Active / Suspended / Expired / Online) or search by username, name or mobile.

The plan-swap badge A single badge is the subscriber's plan. Two badges joined by an arrow mean the subscriber hit their daily limit and is temporarily parked on a throttle plan — they revert to the original at the next daily reset.

Managing a subscriber

Right-click a row — or use the ⋮ menu — for every per-subscriber action:

ActionWhat it does
View / EditOpen the detail page, or edit contact details, password and expiry
Enable / DisableSuspend the account — online subscribers are disconnected
Renew PlanAdd the plan's duration on top of any remaining time; generates an invoice if the plan has a price. A Plan choice lets an expired user come back on a different plan in the same step — leave it on "Keep the current plan" to renew as before
Reset Uptime / Quota / DailyZero the chosen limit counter
UsageOpen usage graphs and session history
DeleteRemove the subscriber and all their history — active sessions are disconnected first
How actions take effect Resets, plan changes and renewals are queued to an audit log and applied by the samm-radius tick — typically within a few seconds. If the subscriber is online, SAMM also sends a live refresh. See CoA & live changes.

The detail page can also reveal the subscriber's login password behind an eye-toggle (with one-click copy) — handy when a customer asks for their credentials.

The Usage view

The Usage action opens a detailed traffic page for one subscriber, with a 7d / 14d / 30d / 90d period selector. It reports three headline figures — today's traffic (with the upload/download split and minutes online), this month's traffic, and the cumulative online time for the month. Below them is a daily traffic chart of upload against download, and a full session history table: the start and stop time, duration, bytes down and up, the NAS, and the terminate cause of every session.

Bulk operations

To change owner, expiration, status or auto-renew for many subscribers at once — or to delete many — use the Bulk Changes and Bulk Delete tools. To create subscribers in bulk from a spreadsheet, use Export / Import.

Restrict a subscriber to specific routers

When the branch login setting is on, a user logs in through the routers of their own branch, of the branches above it and of Headquarters (see Admins, branches & roles). From the edit form you can narrow a user (or a whole card group) further to specific routers: with none selected the branch's routers apply; with one or more selected, login is accepted only from those routers, enforced inside RADIUS. Changing the set disconnects any live session on a router that is no longer allowed.

Change username, renew with a preview

Rename a user from their page (the Username button next to Edit) or the Users list menu, after typing the current username to confirm. Sessions, usage and logs follow the new name, the live session is disconnected so the router forgets the old login, and the user is told the new username unless you untick that box. When you renew or change a plan, choose whether the new period continues from the expiry date or starts today, and see — and adjust — the new expiry before saving. A renewal can also take a down payment.

Wireless link

For a subscriber on a MikroTik access point, the user page can read their radio directly: signal (with a plain word for how good it is), speed in each direction, CCQ and uptime. Only MikroTik radios can be read.

User files & custom fields

Upload ID cards, passports, contracts and photos to a user from their detail page; files preview without downloading, and can be shown to the subscriber in their own portal under Files. Custom fields — defined once in Settings — add extra data entry to users, files, plans, card groups, tickets and add-ons.

Subscribers & plans

Hotspot cards

For prepaid Hotspot access, generate a batch of voucher cards instead of individual subscribers. Each card is a username/password pair with its own speed and limits, generated by the thousand and printed for distribution.

Create a card group

  1. Go to Users → Hotspot Cards and click New group.
  2. Fill in the form below and click Create group — SAMM generates every card's credentials automatically.
SectionFields
IdentityUnique group name, description, optional username prefix, how many cards to generate (up to 10,000)
CredentialsUsername and password format (numbers / letters / alphanumeric) and length
Speed limitDownload and upload speed — 256k, 6M, 1G; 0 = unlimited
Limit TransferUnlimited, combined cap, or separate download/upload caps (MB / GB / TB)
Limit TimesUptime cap, expiration after first login, and a group "valid until" shelf date

The expiration counts from each card's first login, while valid until is a hard shelf date — cards cannot be used after it, whether or not they were ever activated.

Managing a group

Open a group's ⋮ menu to enable or disable every card at once, extend the group's "valid until" shelf date, add more cards to the batch, or edit its details. Individual cards can be reset (quota, uptime or expiration) or disabled from the card detail page.

Duplicate group copies every setting exactly and generates the same number of cards with fresh codes — a card code can only ever belong to one card, so a copy is a new print run, not a clone of the old one. It is the fast way to reorder a voucher batch that sold out.

Add one card or import a list

+ Card, on the cards list and on a group's page, adds one card with the username, password and optional name you type, into a group you pick from a search list. On a group's page, Import cards brings in a CSV or Excel file (username, password and an optional name); you see what will be added and what will be skipped before anything is saved.

Card designs

Open Hotspot Cards → Card designs to design the printed card: its size, a background image, your logo, and where the username, password, price, validity and a QR code go. The QR code logs the card in at the hotspot with one scan. Ten ready-made designs are there to start from; edit, copy or delete them like your own.

A design is either an A4 sheet of cards (Export) or a thermal slip, 80 or 58 mm, for Quick Print. Each group keeps its own design for each; a group without one prints the built-in card, and Quick Print uses the ready-made Thermal Pro slip.

Card statuses

StatusMeaning
UnusedGenerated but never logged in
ActiveIn use, within its limits
ExhaustedA limit (quota, uptime or expiration) has been reached
DisabledManually disabled

Printing & tracking

Open a group to see its cards, print them to a PDF for distribution (the print layout uses your ISP logo from Settings), and review per-card usage. Card traffic also appears in Reports under the Cards tab, and each group has its own accounting view.

The router is told what is left on each card, so the hotspot status page shows the time and data remaining, and the router ends the session when the card runs out.

Subscribers & plans

Self Service — guests sign themselves in

The opposite of a voucher: nobody prints anything and nobody stands at a desk. A visitor connects to your hotspot, taps Register on the sign-in page, types their name and mobile number, and SAMM sends them a passcode by SMS, WhatsApp or email. They enter it on the same page and they are online — and you keep a named, exportable record of everyone who used the guest network.

Typical venues: restaurants and cafés, hotels and guest houses, expos and trade fairs, conferences, shopping malls, clinics and waiting rooms, gyms, co-working spaces, salons, airport lounges, stadiums, campuses, libraries, car showrooms, wedding venues, resorts and campsites.

Switching it on

  1. Set up a delivery channel first. Notification Center → enable SMS or WhatsApp and send yourself a test message. Nothing else works until one channel does.
  2. Self Service → Settings: tick Allow guests to register themselves, choose which channels to offer, and set how long a passcode stays valid and how long a guest must wait before asking for another.
  3. Leave Passcodes come from on the Self Service card group unless you have a reason to change it — that group decides the speed and how many devices may share one passcode.
  4. Turn the Register tab on for each login design you use — see below. This is the step people miss.

The login page — the step people miss

The Register tab is per login design, and it is off by default. Open MikroTik Manager → the router → Login Page, edit the design you use and tick Allow Self Service. You can reword every sentence a guest sees on the same screen — the Register tab label, the intro line, the two field labels, the button, and the five replies (“your passcode is on its way”, “you already have one”, “please try again later”, “we could not send it”, “sign-up is not available”).

Then press Push — and press it again after every SAMM upgrade. Hotspot sign-in pages live on the router's own flash storage, not on SAMM. Upgrading SAMM does not re-push them, so a router keeps serving its old page — with no Register tab on it — until you push again. SAMM warns you on the Login Page tab when a router is serving pages older than your installed version, and the Self Service page names every router that cannot show the tab and offers to fix them all at once.

The rules that stop abuse

  • One live passcode per number. Asking again while a code is still valid tells the guest to check their messages instead of sending another.
  • Then a waiting period you set, before that number can request a new one.
  • Validity counts from the moment the passcode is sent, not from first login — so a code that sat unused for a week does not still work.
  • A daily cap set by your license (see below). Once it is used up, guests are asked to try again later and passcodes already issued keep working.
  • Every attempt is recorded against the device's MAC address as the router reported it — which a guest cannot fake from their browser.

The license

Self Service is licensed separately from your plan, by how many passcodes a day the install may issue, and it renews on its own date — so you can be on Free with a paid add-on, or on Unlimited with none. Every install gets 10 a day at no charge; Light raises it to 50, Heavy to 200, and Max removes the limit. See pricing.

The Self Service page shows used / allowed for today and says plainly when the allowance is gone. Buy or renew from your dashboard on securytik.com, or ask from System → License and a SecuryTik admin approves it. A passcode that could not be delivered does not use up your allowance.

Subscribers & plans

Add-ons & vouchers

An add-on is something extra a user buys on top of their plan for a number of days: a speed boost, unmetered days or a night boost for chosen hours. Create them under Users → Add-ons.

  • Sell an add-on from the user's page, let users buy it in the user portal or the Telegram bot (paid from the wallet), or print one-time voucher codes that users redeem in the portal or the bot.
  • Free apps: turn on Unmetered and pick apps by category; only their traffic stops counting toward the user's quota. Leave every app off and all traffic is unmetered. This needs the Data Log.
  • Parental control and VPN: an add-on can switch on Parental control or VPN through SAMM for its period; both switch off by themselves when it ends. Set the length as a value and a unit (days, weeks or calendar months).
  • Users see their active add-ons and end dates on their Plans page. An add-on given to an agent's user is charged to the agent like a renewal.
  • Each branch can have its own add-on prices in Accounting → Price Lists.

Invoice discounts

Give a percent or a fixed amount off an open invoice, with a reason, from the invoice or the user's invoices. A standing discount can repeat on the user's next renewals. Each role has a maximum discount it may give.

Subscribers & plans

Points & rewards

Reward loyal users and let them bring their friends. Points are off until you switch them on under Users → Points & rewards.

  1. Switch points on and set, on each plan, how many points a paid renewal gives and how many the inviting user gets when a friend they referred pays their first invoice.
  2. Create rewards: faster speed (the plan speed multiplied, for some days) or free days, each with a price in points.
  3. Users see their balance, their invite link and the rewards in the user portal, and spend points there. A friend who opens the invite link leaves their details; you create the user and the referral is recorded.

Points are counted from paid invoices, once each. If an invoice is cancelled, its points are taken back. You can also give or take points by hand, and see the top balances and join requests on the same page.

Subscribers & plans

Parental control

Families protect their own line from the user portal. It is off for every user until you allow it: switch on Parental control in the user's add or edit form (it sits right after Allow Password Change), or for many users at once from the Users list's bulk actions.

What the user can block

  • Categories: adult content, drugs, gambling, dating, violence and hate, and proxy or VPN services used to get around the filter. Blocking adult content also turns on SafeSearch on the big search engines and YouTube.
  • Apps and websites from the same catalogue as Websites & Apps, shown with their official logos.
  • When: always, or on a weekly calendar (for example school nights after 22:00).
Light on the router SAMM does not write rules per user. Each router gets a few shared rules, and users are placed in or out of them as their schedules start and end, so the router's load stays low even with many families. The router needs to be managed by SAMM (API access) for app blocking.

Subscribers & plans

VPN through SAMM

Chosen users send their traffic out through your SAMM server instead of the router's own Internet line. It rides the tunnel each router already has to SAMM (WireGuard, L2TP/IPsec or SSTP, see VPN), so there is nothing to install on the user's phone or computer.

Allow it

  • Per user: switch on VPN through SAMM in the user's add or edit form, or for many users at once from the Users list's bulk actions.
  • As an add-on: under Users → Add-ons, turn on VPN in an add-on and sell it for a number of days, weeks or months. It is on for the add-on's period and switches off by itself after.

What the user chooses

Allowed users get a VPN page in the user portal with three choices:

  • Off — nothing goes through the VPN.
  • All traffic — every app and website goes through the VPN, and the user's DNS goes through it too.
  • Chosen apps — only the apps and websites the user picks, from the same catalogue as Websites & Apps; everything else stays on the local line.
If the tunnel goes down Users never lose the Internet because of the VPN: if the router cannot reach SAMM, their traffic falls back to the router's own line until the tunnel is back. Local addresses (your LAN and CGNAT ranges) never go through the VPN. Works on RouterOS 6 and 7; the router must be managed by SAMM.

External VPN: leave through another provider

Under System → VPN → External VPN SAMM can send VPN users out through a commercial VPN instead of its own line, so the VPN works even when SAMM sits on your LAN with no public address.

  • NordVPN: paste an access token from your NordVPN account and choose how many servers to open (up to 10 per account). SAMM gets the key and picks the servers itself.
  • Any other provider (ProtonVPN, Mullvad, Surfshark, your own server): upload its WireGuard .conf files, one connection per file. Script lines in a file are ignored and never run.
  • Connections shows each connection live: status, last handshake, traffic and users. Each user stays on one connection (the same exit address); a weight shares users between connections.
  • If a connection stops working, its users leave through SAMM's own line until it is back; deleting or switching off a connection moves its users to the others.
SAMM needs a public address The VPN is only useful when your SAMM server reaches the Internet from a different place than the users, for example a server in a data centre. If SAMM sits behind NAT on the same network, traffic would leave from the same line, so the user form and the add-on form show a warning, unless an External VPN connection is working.

Getting started

Set up your server

Do not have a server? We set one up for you. You order it from your SAMM dashboard, pay, and receive a ready SAMM server on your own .com domain, with your name on it. There is nothing to install.

What you get

  • A cloud server and a .com domain, in three sizes: 6 cores, 12 GB RAM, 200 GB SSD for $100 a year; 8 cores, 24 GB RAM, 300 GB SSD for $200; 12 cores, 48 GB RAM, 400 GB SSD for $300. You pick the size in the first step.
  • HTTPS on your domain; the server's own address is never published.
  • SAMM installed and branded with your company name, with your licence linked and active at the first login.
  • An e-mail with your panel address (https://your-domain/admin) and a strong admin password.

Order it

  1. Sign in at samm.securytik.com and open Dashboard → Get a server.
  2. Choose a server name and the number of users, then search for your .com domain or pick one of the suggestions.
  3. Pay with any method shown at checkout. The order waits two hours for the payment; after that it is cancelled and you place a new one.
  4. After the payment everything is automatic. When the server is ready you receive the e-mail with your address and login.

SSH access

From Dashboard → Servers you can create your own SSH login with a password, public keys, or both. A step-by-step SSH guide for Termius, Windows, Ubuntu and macOS is on the same page.

Renewal Renew at least one day before the end of the year; renewal opens seven days before. If the server is not renewed, the server, the domain and the data on it end. Keep your own backups too.

Subscribers & plans

CGNAT & IP pools

Both are under Plans, beside the router's own pools.

CGNAT Pools

A CGNAT pool lets several users share one public address. Each user gets a fixed block of ports on that address, so every connection can be traced back to one user.

  1. Open Plans → CGNAT Pools and add a pool: the public addresses, how many users share one address, and how many ports each user gets.
  2. The capacity line shows how many users fit before you save.
  3. Push it to the router. SAMM writes the NAT rules and keeps the history of which user had which address and ports, which the Lookup reads.

IP Pools

With an IP pool, SAMM gives each user their address itself, per router and plan, so the router needs no address pool of its own. The address is freed when the session ends. When a pool is full, the router's own pool takes over.

Daily operations

Data retention & Lookup

Many countries ask an ISP to keep connection records and to say which subscriber used an address at a given time. Data retention does both. It is off until you switch it on.

Switch it on

  1. Open System → Settings → Data retention and switch it on.
  2. Set how long sessions are kept (two years by default). Sessions are kept for that period even for users you delete.
  3. Optionally send a daily encrypted file to your NAS over SFTP, SMB or NFS. Open it with gpg --decrypt.

Lookup: who used this address?

  1. Open Overview → Data Log → Data retention.
  2. Enter the public address, the port and the time from the request you received.
  3. Enter a case reference (SAMM suggests CASE-1, CASE-2…). The result shows the user, the MAC address, the router and the session; it can be searched and exported.
Lookup log Every search is kept in the Lookup log with who searched, when and the case reference, and it cannot be edited. With CGNAT, the Lookup uses the port blocks of your CGNAT pools.

Network & routers

Other router brands

Besides MikroTik, SAMM works with Cisco, Huawei, Nokia and ZTE routers as NAS (BNG).

  • Add the router under Devices → Manager and choose its type. The form asks for the right login: the API for MikroTik, SSH for the other brands.
  • Setup page: SAMM generates the configuration lines for that router, ready to paste.
  • Speeds and disconnects use each brand's own RADIUS attributes, so plan changes reach the router.
  • Data Log from the router's own traffic records (NetFlow or IPFIX).
  • CGNAT on Cisco: SAMM pushes the rules over SSH and the Lookup works as on MikroTik. Cisco routers can also connect to SAMM over L2TP.
  • Device page: CPU, memory, temperature, uptime and charts, like MikroTik.

Network & routers

FTTH & OLTs

SAMM reads OLTs from V-SOL, Huawei (SmartAX), ZTE (C300 and C320) and Nokia (ISAM) over SSH.

  • FTTH page under Devices → FTTH: a list of OLTs with filters, columns and export, like Wireless.
  • Every ONU with its optical signal, and the ONUs waiting to be added.
  • ONUs linked to their users automatically.
  • Subscriber line lock: SAMM learns the line each user connects from and can keep their login to that line.
  • OLT device page: CPU, memory, temperature, uptime and charts.

Network & routers

Routers (NAS)

A NAS (Network Access Server) is a router that authenticates subscribers against SAMM over RADIUS. Every router that carries subscriber traffic needs a NAS record.

Add a router

  1. Go to MikroTik → NAS and click Add Router.
  2. Fill in the fields below and save.
FieldMeaning
NAS IP / hostnameThe router's address, as seen by the SAMM host
ShortnameA friendly label shown across the UI
Typemikrotik unlocks live device sync and config push; other types are RADIUS-only
SecretThe RADIUS shared secret — must match the router exactly, or authentication fails
CoA portUDP port SAMM sends Change-of-Authorization packets to (MikroTik default 3799)
API port / user / passwordMikroTik API credentials SAMM uses to read device info and push config
No restart needed SAMM resolves NAS clients dynamically from the database — adding or removing a router never requires a FreeRADIUS restart.

The NAS list

Every router shows in one table — ID, NAS IP / hostname, shortname, type, a masked secret (click the cell to reveal it), the CoA and API ports, and a live ping result with round-trip time. The search box filters by IP, shortname or description.

Each row's ⋮ menu carries the per-router actions — View Device and Refresh Info (MikroTik only), Edit, Push RADIUS config (MikroTik only), and Delete. Opening a mikrotik-type row jumps straight to its device page.

Discover neighbours

Click Discover neighbors to scan the network for MikroTik devices (via MikroTik's neighbor-discovery protocol) and add them as NAS records without typing each address by hand. A discovered router can be added by IP, or Auto-added — a one-click bootstrap that creates a SAMM management user on the router, pushes a management IP and clears the factory bridge.

Auto-add is for fresh routers The one-click bootstrap is intended for factory-fresh (or reset) devices — on a router that already carries configuration it can overwrite or break the existing setup.

Push RADIUS config to the router

For MikroTik NAS records, the row's ⋮ menu offers Push RADIUS config — SAMM configures the router for you over the API instead of you typing it by hand. You confirm the SAMM server IP (it must be reachable from the router) and the auth, accounting and CoA ports; SAMM then creates or replaces a RADIUS entry on the router:

SettingValue
CommentSAMM — the tag SAMM uses to find and update this entry later
Servicehotspot, ppp
Address / secretThe SAMM host, with the shared secret from this NAS record
Timeout3000 ms
CoA incomingAccepted, on the CoA port you confirmed

The dialog shows a result log when the push finishes.

Configure the MikroTik side

If you configure the router manually instead:

  • Add a RADIUS server pointing at the SAMM host, with the same shared secret, enabled for PPP / Hotspot.
  • Use auth port 1812, accounting port 1813.
  • Accept incoming CoA on port 3799.
  • Set the accounting Interim-Update interval to about 5 minutes (SAMM's wizard default) — this is how often SAMM accumulates usage and evaluates limits; shorter intervals tighten limit latency at the cost of more accounting traffic.

Monitor-only devices

A router added as a monitor appears in the MikroTik inventory and is pinged and synced, but has no RADIUS role — it cannot authenticate subscribers. Use it to keep an eye on routers that aren't subscriber NASes.

SAMM Fallback

If SAMM stops answering, the routers you choose keep logging subscribers in on their own — from a disabled copy of every active user that SAMM keeps synced on them. When SAMM is back, everyone reconnects through it. Off by default; turn it on per router from Settings → Advanced.

Fallback switches on after the delay you set, or by hand, and the router reports it over Telegram. A status table shows each router's sync state, how many users failed to sync and why, and flags a router whose backup has gone stale or that cannot reach SAMM's health address.

Network & routers

MikroTik manager

When a router has API credentials, SAMM manages it directly over the MikroTik API — no WinBox, no SSH. The MikroTik section is a live inventory of every router, and each device opens a detail page with fifteen tabs that configure almost every part of RouterOS from your browser.

MikroTik Monitor

MikroTik → Monitor shows one card per router, laid out as a grid. Each card reports — refreshed by samm-worker and live-polled every 30 seconds — the reachability dot, RouterOS version, CPU load and core count, memory use, active session count, uptime, and the time of the last sample.

A card is tagged either NAS (a router that also authenticates subscribers over RADIUS) or monitor (a device added for monitoring only). Add MikroTik registers a new device; Refresh now forces an immediate poll. Monitor-only cards carry a right-click menu — Open, Edit, Refresh Info, Delete.

Ubiquiti devices

When you add a monitor you choose its type: MikroTik, Ubiquiti airOS or Ubiquiti UniFi access point. Ubiquiti devices are reached over SSH with the device's own login; a Probe page shows what the device reports. A UniFi access point appears in the Wireless pages with one row per radio — its channel, width and SSIDs, the connected clients with signal, noise and rate, and the neighbouring networks it hears — and takes part in the Wi-Fi optimizer and channel planner.

Every plan allows three monitors for every router (a plan with unlimited routers has unlimited monitors), so watching your access points never uses up your router allowance.

Users kept on a router

SAMM finds the PPP logins, Hotspot users and User Manager users a router keeps itself (RouterOS 6 and 7) and lists them on the router page. Before anything moves, each row shows what SAMM will create: username, password, name, mobile, plan (marked new when SAMM creates it), expiry, limits, MAC and IP. Names, phone numbers and end dates written in router comments, in Arabic or English, are read too. Tick the users and bring them in: it runs in the background and the Users list fills as they arrive.

The device page — fifteen tabs

Open any device for its full management page. The tabs fall into four groups.

Monitoring

TabWhat it shows
OverviewDevice info, system info, and performance-history charts (CPU, memory, sessions over time)
InterfacesEvery interface with its live state, plus per-interface traffic history
Websites & AppsThree sub-views: Monitor (websites & apps seen on the router with traffic history), QoS (application-aware priority, below), and App Filter (DNS-based content blocking from the catalog)

Manager

The Manager → General tab is the housekeeping page for the device: Identity (the router name), Time (clock, timezone and NTP), and Tools (reboot, ping and other one-click router actions).

Network configuration

TabWhat you configure
BridgeCreate LAN bridges and choose which physical interfaces (ports) belong to each
VLANAdd and manage VLAN interfaces
IPThree sub-tabs — Static (static and dynamic addresses), DHCP client (pull an address from upstream), DHCP server (hand out addresses, with a live lease table)
DNSDNS servers and cache (the app/site content filter lives under Websites & Apps)
WiFi / CAPsMANWi-Fi interfaces with their configurations and security profiles; and the CAPsMAN controller — configurations, provisioning rules and remote CAPs

Services & maintenance

TabWhat you configure
PPPoEPPPoE servers, PPP profiles, IP pools, and the RADIUS accounting interim-update interval
HotspotHotspot servers, hotspot profiles and user profiles, DHCP/IP pools, and the captive-portal login page
InternetWAN uplinks — SAMM-managed WANs and default routes, with any existing non-SAMM WANs shown read-only
FirewallFilter rules, a router-security analysis, connectivity & targets, security modules, and firewall backups — Auto-Security snapshots the firewall before applying and can arm a timed auto-revert, so a ruleset that locks you out rolls back automatically
UpdateRouterOS updates — pick an update channel, check and apply, and review installed packages
WizardThe guided first-time setup, below

The PPPoE interim-update interval

On the PPPoE tab, Interim update sets how often the router sends RADIUS accounting Interim-Update packets to SAMM. SAMM uses those packets to accumulate byte and uptime counters and to evaluate the quota, daily and uptime limits — without them, limit enforcement and the live-session counters stall. The recommended value is 5m.

The Hotspot login page

From the Hotspot tab you manage the captive-portal login page: keep the MikroTik default pages, apply one of the built-in templates, or apply one of your saved designs. SAMM includes a visual design editor and a template gallery — customise a login page and push it straight to the router's hotspot.

Application-aware QoS

The QoS view (a sub-tab of Websites & Apps) turns the apps and sites SAMM already sees on the router into a download-priority plan. Drag each app from the pool into one of eight priority slots — slot 1 is served first under contention, slot 8 last; apps left in the pool are not shaped. Optionally cap any app's download speed (for example 10M) and set a total download ceiling for priority to compete for. Auto-distribute by category arranges everything in one click — messaging first, then AI services, then stores, with everything else below.

When you push, SAMM compiles the slots into a MikroTik queue tree (tagged SAMM:qos, parent=global) with matching packet-mark firewall rules, highest priority first. It is built on the same Websites & App filter catalogue that powers monitoring, so only apps actually seen on the router appear — and removing SAMM QoS strips every SAMM:qos object back off the router, leaving your counters untouched.

The setup wizard

The Wizard tab collects everything in ten short steps and pushes the full configuration to the router in one batch at the end. Nothing is sent until you confirm on the final review step.

  1. Welcome & detect — SAMM probes the router and shows what is already configured, so you can skip those items in the push.
  2. Bridge interface — name the LAN bridge.
  3. Bridge ports — pick which physical interfaces join the bridge.
  4. DNS — set upstream resolvers (one-click presets for Google, Cloudflare, Quad9 and more), cache size, and optionally a DNS content filter.
  5. NTP — set the router's clock source (NTP client, and optionally serve time to the LAN).
  6. Internet — add one or more WAN uplinks (Static / DHCP / PPPoE).
  7. RADIUS to SAMM — point the router at your SAMM host for authentication, accounting and CoA.
  8. Services — choose whether the wizard creates a PPPoE server, a Hotspot server, or an IPoE / DHCP service, and optionally turn on IPv6 dual-stack (opt-in, off by default): pick the delegated (DHCPv6-PD) prefix length and the IPv6 blocks and the wizard builds the pools and attaches them to the PPP profile.
  9. PPPoE / Hotspot details & Firewall — pools, profiles, lease times, the firewall & NAT rules, and an optional Expired pool & internet block that redirects expired subscribers to SAMM's "subscription expired" page instead of a dead connection.
  10. Review & push — see the exact list of commands that will be sent, then push them all to the router.
Per-user speed comes from RADIUS The wizard creates a single PPPoE / hotspot profile — it does not push per-tier profiles. Each subscriber's speed is delivered by SAMM in the RADIUS reply at login, so plan changes never need a router edit.

Network & routers

Deep inspection

When a network feels slow, Deep inspection does what an engineer would do: it watches one router for a while, reads everything it can, and tells you what is wrong and what to do first. It only reads: it never changes anything on the router, and any fix stays your decision.

Start an inspection

  1. Open Devices → Network Health and press Deep inspection, or right-click a router on the page.
  2. Switch on the routers to inspect. All switches start off. Only MikroTik BNGs with a saved login are listed.
  3. Choose how long: 15 minutes, 30 minutes, 1 hour or 2 hours. A longer run is more reliable; run it at a busy hour.
  4. Press Start inspection. It runs in the background, so you can close the page. One inspection runs per router, at most two at a time.

Reports, next to the button, lists every inspection with its progress, result and score. You can stop one early and keep what it measured so far.

What it checks

  • Internet lines: loss and delay to the internet and on each line, spikes, and whether large packets get through.
  • User experience: test messages to a changing sample of online users, and how long the answers take.
  • User queues and speed: whether users lose data when their plan is full, upload and download, and rules that can skip the speed limits.
  • Access network and ports: each access side, towers and devices behind the router, port errors, drops, speed and fibre signal.
  • Load balancing: how the lines share traffic, and whether the balancing rules are complete and notice a dead line.
  • Router health: processor load and each core, memory, temperature, restarts, firmware and the router's log.
  • Logins and RADIUS: answers on time, refused logins, sessions that end early, and packet size settings.
  • Security: whether the router is closed to the internet, firewall order, protections, extra services and failed logins.
  • Routing: BGP sessions, OSPF neighbours and dead routes.

Every Network Health check is included. A check that could not be read is left out of the report, never counted as good.

The report

It starts with a score out of 100 and a verdict in plain words, then a scorecard for each area and a list of what to do, most important first. Below that are the details and the numbers. It follows your panel language, and Export PDF saves it with the SAMM logo and "Prepared by SAMM" on every page.

The inspection is light, and it stops pinging users while the router's processor is very busy. If the router stays overloaded it ends early and says so.

System

SCOOP AI

SCOOP AI is an assistant at the bottom of every admin page. Ask in your own words and your own language about your users, plans, cards, invoices, payments and routers, and get a plain answer in seconds. It is installed and switched on by itself.

Connect an AI

In Settings → SCOOP AI, connect Google Gemini (free key), ChatGPT (sign in, no key), Claude, OpenAI, OpenRouter or DeepSeek. Keep several saved logins and switch between them, and choose a model or leave it on Automatic. A key the AI itself refuses is stopped when you save it, and a help page shows how to get a key for each AI.

What keeps it safe

  • It works with each admin's own rights: an admin sees and changes only what their role allows.
  • Money, deletions and router changes are held until you press Approve.
  • Every router change keeps an undo on the router itself and never touches SAMM's own link to the router.
  • The SCOOP AI log keeps every question, answer and approval of every admin.

What you can ask it to do

  • Answer questions about your data, in your language.
  • Balance the internet between your lines by percentage, send chosen apps or a VPN through a chosen line, and set faster DNS.
  • Send you a report every Monday, or remind you at a time.

Permissions have a SCOOP AI block: use it, see the log, change the settings. Each admin can hide it for themselves from the robot's menu or their Profile.

Network & routers

Network map, health, Data Log & connection quality

Network map

Devices → Network Map is drawn from what each router reports about its neighbours — there is no diagram to maintain. Switch layers for ports, IP addresses, subnets and CPU, or show the path each device takes to the internet. Drag nodes into place and save the arrangement; Discover now reads the neighbours again.

Network health

Devices → Network Health lists every router worst first: healthy, with warnings, answering but broken, or unreachable. Each finding says what is wrong in plain words — CoA disabled, RADIUS secret mismatch, clock out of sync, Telnet or FTP left open. The checks only read the router. From a router's Diagnose view, common findings have a one-click fix that shows a preview first and can be reverted. Open findings raise alerts in the Alert Center.

For a longer look at one MikroTik BNG, with a full report, use Deep inspection.

Both pages are behind one switch, Settings → Advanced → Network Health. While it is off, SAMM does not contact the routers for them. When it is on you also choose how often each router is checked, how many routers one pass reads (busy installs are spread over several passes) and whether neighbours are discovered for the map.

A router that has been down for a long time can be paused, so it stops raising alerts until it answers again.

Wi-Fi optimizer

Devices → Wireless → Wi-Fi optimizer shows, for every radio, a spectrum view of the band it works in (signal in dBm across the frequencies, the networks it hears and where they overlap), a list of those networks, and a channel chart that marks each channel Quiet, Busy or Crowded. Survey now listens across the whole band, one radio at a time so a site with several sectors never drops all its clients together; the button tells you what it costs before it starts. Live sweep draws the last, peak and average readings while you watch.

The channel planner recommends the quietest channel and the best channel width for each radio. Choose Off, Suggest or Auto for each radio, separately for its channel and its width, or let it follow its network; set many radios at once from the Wireless list. In Auto, SAMM moves radios at 04:00, one at a time, and surveys each radio again on its new channel. Apply moves a radio now and Undo moves it back. It works on MikroTik radios (wifi and wireless packages, CAPsMAN) and on Ubiquiti UniFi access points.

Data Log

Open a user and choose Data Log to see where their traffic goes: top destinations by host and app — YouTube, Facebook, WhatsApp — with upload, download and connections, or a timeline. SAMM reads the router's own flow export (IPFIX), falling back to its connection table, and names apps from the same catalogue the App Filter uses. SAMM never sits in the traffic path.

  • Record user Data Log turns it on, under Settings → Advanced → Data Log.
  • Hourly detail is kept for a few days, then compacted to one row per site per day — about a twenty-fourth of the size. The page and the export read both, so nothing disappears from view.
  • Destinations per hour keeps the busiest destinations of each user per hour and drops the long tail of one-off addresses; 0 keeps everything.
  • Retention sets how long rows are kept before the nightly clean-up removes them.
  • A backup with Skip usage leaves the Data Log out, so it stays small.
Off until you turn it on A superadmin enables the Data Log in Settings and chooses how long it is kept. The figures are indicative; billing always uses RADIUS accounting.

Connection quality

While a user is online, SAMM can record their average speed every few minutes, from the accounting it already receives, and measure delay and loss with a short test from their router. The user page shows a Connection quality card with the latest figures, a speed history against the plan and a Test now button; the users list has an optional column and the export can include the figures. History is kept for two days.

Off until you turn it on Turn it on in Settings → Advanced → Connection Quality, where you also set how often users are sampled and how many users one router tests per round (least recently measured first). It is light by design: the speed costs no router traffic, and the test load on each router is capped. A device that blocks the test shows no reply even when the line is fine. Test now works even while the feature is off.

Network & routers

CoA & live changes

CoA (Change-of-Authorization) is how SAMM changes a subscriber's session while they are online — to lift or drop their speed, or to disconnect them — without waiting for them to reconnect.

How a change reaches a live subscriber

SAMM never pushes a router change straight from a button click. Every admin action follows one safe path:

Admin action → Audit log → samm-radius tick → CoA outbox → Router
  1. The action is recorded in an audit log as a queued command.
  2. The samm-radius service drains the queue on its next tick, applies the change, and — if the subscriber is online — enqueues a CoA.
  3. The CoA outbox is drained and the packet is sent to the router.

Time-driven events — expiry, speed-window edges, daily resets — feed the same outbox. The upper bound on latency is one samm-radius tick (30 s by default; lower it in Settings for tighter enforcement).

Hybrid CoA

SAMM sends a CoA-Update first to change the session in place. If the router rejects it after the configured retries, SAMM automatically falls back to a Disconnect-Request — the subscriber reconnects and picks up the new settings. This hybrid strategy works across MikroTik firmware versions.

The CoA Outbox page

Users → CoA Outbox is the live view of that queue. samm-radius is the only sender — the admin panel never pushes a CoA directly — and it drains the queue every tick. The page auto-refreshes every 30 seconds.

Six counters head the page — Pending, Sent, NACK (retrying), Done, Failed and Total. Filter the table by status, by action (update or disconnect), or search by username, NAS IP or reason.

StatusMeaning
pendingQueued, waiting for the next samm-radius tick
sentDispatched (transient — the send and its result are recorded in the same tick, so rows rarely stay in this state)
nackThe router rejected the CoA-Update — SAMM is retrying, then falls back to a disconnect
doneApplied successfully
failedGave up after the retry limit — hover the badge for the last error

Each row shows the user, router, action, attempt count, reason, and the created and sent times. Per-row actions let you Retry a failed or nack'd packet, Cancel one still in flight, or open Attributes to inspect the exact RADIUS attributes the packet carries. The sidebar badge counts pending rows; the Dashboard tracks 24-hour failures. A healthy system keeps this queue near-empty.

Stale-session reaper

If a router crashes or loses connectivity, its Accounting-Stop packets can be lost — and on many systems those subscribers stay "online" forever. SAMM sweeps for sessions that have stopped sending Interim-Updates and closes them automatically (terminate cause Reaped-Stale), so the live-session list, simultaneous-use counts and usage figures stay truthful. The timeout is the stale_session_timeout_seconds setting (default 900 s = 15 minutes; set 0 to disable), and it takes effect live — no restart needed.

Daily operations

Dashboard & live sessions

The two screens under Overview are where you start every shift — the Dashboard for the health of the whole system, Live Sessions for exactly who is connected right now.

Two screens: open in a new window

Every page has an Open in a new window button in the top bar: the page opens on its own, without the sidebar and top bar, ready to drag to a second monitor. Links inside that window stay in the same mode. Each dashboard block has the same button in its corner: the block fills its own window and keeps refreshing with the dashboard, so you can keep Live Sessions, router health or a chart in view all day without changing your dashboard layout.

Dashboard

Overview → Dashboard is the operator home screen. A period selector at the top — Today, 7d, 14d, 30d, 90d — sets the window for the trend chart and the date-bounded figures.

The six KPI tiles

Each tile is a live counter and a shortcut — click it to jump straight to the filtered list behind the number.

TileShowsOpens
Online nowSubscribers with a live RADIUS session right nowUsers filtered to Online
Active subscribersActive accounts, with the total subscriber count beneathUsers filtered to Active
ExpiredSubscribers whose subscription lapsed with no next plan setUsers filtered to Expired
Open ticketsSupport tickets not yet resolved (excludes done & closed)Users → Support Tickets
RoutersTotal NAS records, plus the count currently unreachableThe MikroTik monitor
Unpaid invoicesInvoices still needing payment follow-upInvoices filtered to Unpaid

Users & live sessions chart

A daily-snapshot line chart plots three series across the selected period — active users, online sessions, and expired users — so growth and churn are visible at a glance.

Pipeline health

This panel is the heartbeat of the enforcement engine. On a healthy system the queues sit at or near zero — a number that stays high points to a stuck service or a router rejecting changes.

MetricWhat it means
samm-radius queuePending CoAs waiting for the next tick — should clear within seconds
Failed CoA (24h)Zero on a healthy system; a non-zero count means a router is rejecting CoAs
Audit log pendingQueued admin actions not yet applied by samm-radius
Sessions throttledSubscribers currently held at a reduced speed by a limit — expected, not an error
Sessions snapshotThe live session count — should track Online now
Active plansThe size of your plan catalogue
The enforcement path Admin actions are queued to samm.audit_log; the samm-radius tick drains them and emits CoAs into samm.coa_outbox. The full path is in CoA & live changes.

Recent-activity tables

Four tables under the chart give a rolling view of what just happened, each with a View all link to its full page:

  • Recent CoA outbox — action, user, status (done / pending / nack / failed), attempt count, reason, and time.
  • Recent admin actions — action, target, the actor who triggered it, whether it is applied yet, and time.
  • Recent subscribers — the newest accounts with their status and last authentication time.
  • Routers — every NAS with a reachable / unreachable / no-data health dot.

Live Sessions

Overview → Live Sessions lists every subscriber the routers currently report as online over RADIUS accounting. The page auto-refreshes every 30 seconds; a manual Refresh button sits in the header.

Filtering the list

  • Search — matches username, framed IP, or NAS IP, submitting as you type.
  • Router — narrow the list to the sessions on a single NAS.
  • Only throttled — show just the subscribers a limit is holding at a reduced speed.
  • Per page — 20, 50, 100 or 200 rows.

What each row shows

ColumnMeaning
UserUsername — links to the subscriber's detail page
Framed IPThe address the router assigned to this session
RouterThe NAS shortname and its IP address
PlanThe subscriber's current plan
Effective speedThe speed enforced on the router right now — the plan speed adjusted by any active speed window. A throttled badge means a limit is holding the subscriber at a reduced speed.
Down / UpLive byte counters for the session
OnlineHow long the session has been up
StartedWhen the session began

Disconnecting a session

The Disconnect button on a row enqueues a CoA-Disconnect for that exact session (reason admin_manual) after a confirmation prompt. The subscriber drops immediately; if their account is still active they are free to reconnect. Track the packet in the CoA Outbox.

Daily operations

Reports & analytics

Overview → Reports is the analytics view — subscriber trends, traffic over time, and the heaviest users and cards on your network.

Choosing the range

Every figure on the page is bound to a date range. Pick a preset — 7d, 14d, 30d, 90d — or type explicit start and end dates and click Apply. A loading overlay covers the page while a long-range query such as 90d runs.

Subscriber & session trends

A line chart with three series over the chosen range: Active subscribers, Online sessions, and Expired subscribers. Use it to spot growth, churn, and the busy hours of your network.

Daily traffic

A stacked bar chart of upload and download bytes per day. Hovering a day shows the upload and download figures plus a combined total in the tooltip footer.

Top 10 lists

Four tables surface your heaviest-traffic accounts, each ranked by volume in GB:

ListRanks
Top 10 download todayLargest download since the last daily reset
Top 10 upload todayLargest upload since the last daily reset
Top 10 download monthLargest download this calendar month
Top 10 upload monthLargest upload this calendar month

Traffic by entity

A paginated, searchable table of per-account traffic. Two tabs switch what it lists:

  • Users — each subscriber with their name, plan, today's upload/download in MB, and this month's upload/download in GB.
  • Cards — each hotspot card with its group, status, and the same today / month traffic split.

The search box filters the table as you type; the per-page selector takes 20 to 200 rows. Every row links through to that subscriber's or card's detail page.

Exporting Reports is an on-screen analytics view. For raw rows to crunch in a spreadsheet, use Tools → Export / Import to download users, plans or NAS as CSV / XLSX.

Live Traffic page

A separate, live view of current throughput for users, routers and interfaces, refreshing down to once a second. Bookmark the combinations you check often so they are one click away next time.

Daily operations

Accounting & billing

SAMM has a complete double-entry bookkeeping system built in — invoices, expenses, receipts, payments, resellers, fixed assets and full financial statements. There is no separate billing product to integrate, and no accountant needed to keep the books straight.

You never touch debits and credits Every action — recording a payment, adding an expense, selling a card group — posts a balanced journal entry to the ledger automatically. You work in plain terms (invoices, expenses, receipts); SAMM keeps the double-entry books behind the scenes and proves they balance in the Trial Balance.

The Accounting page is organised into eleven tabs.

Overview

The financial snapshot. Four headline figures sit at the top:

FigureMeaning
Cash on handTotal balance across all cash & bank accounts
Money you're owedReceivables — unpaid customer and reseller invoices
Money you owePayables — unpaid expenses
Profit this monthIncome minus expenses for the current month

Below: a table of every cash & bank account with its balance, and an income vs expenses chart over the last 1, 2, 3, 6 or 12 months.

Books by branch

Every invoice, payment, expense, asset and cash account belongs to a branch or to the General company. An invoice keeps the branch its user had when it was issued, even if the user moves later. A Branch selector at the top of every tab shows the whole company, the General company only, or one branch with its sub-branches, and lists can be filtered, sorted and grouped by branch. A branch admin with the Financial permission sees only its own branch's books.

Cash handover: a branch sends cash from its own cash account to a company cash account; it is recorded when the company confirms it arrived. Reports → Branches puts every branch side by side: revenue, expenses, net, collections, outstanding, active users and revenue per user.

Invoices

An invoice is a bill you issue. Click New invoice and fill in:

FieldMeaning
CustomerType-ahead search for the account being billed
Revenue categoryWhich income account the sale posts to
Issue / Due dateBlank issue date = today; blank due date = the issue date
Tax rate % / tax groupDefaults to the rate in Settings → Billing; assign a tax group to apply several rates (VAT/GST and more) at once, each posting to its own tax account
Line itemsOne or more description / quantity / unit-price rows — subtotal, tax and total compute live

How much to charge — full, segmented, or nothing

Anywhere SAMM is about to bill a subscriber — activating, renewing, changing a plan, extending an expiration, or doing any of those in bulk — the same invoice picker appears, and it shows the money before you commit:

ChoiceWhat it charges
Full invoiceWhole plan periods only — a part period rounds up to a whole one.
Segmented invoiceThe exact time, pro-rating the last part period. The total is rounded to the nearest whole amount, with the difference posted as a rounding adjustment so the books still balance.
No invoiceChange the service and charge nothing — a goodwill extension, a migration, a correction.

Set the length with the periods multiplier for whole plan periods, or type an exact date and let SAMM work out what that costs. Either way the panel shows the line items, the tax and the total as you change them, and Paid records a cash payment for the full amount straight away.

"No invoice" is a right, not a checkbox Charging nothing is a financial decision, so it is gated by a per-role permission in Settings → Admins. It matters most with agents: an agent whose subscribers bill to their own prepaid balance could otherwise renew, change plans and extend expirations all day without ever paying for them. New roles get the right switched off.

Dunning & prepaid wallet

Beyond one-off invoices SAMM automates the whole collection cycle. A dunning schedule sets a bill day, a due day and an automatic block day — with optional late fees — so overdue subscribers are reminded, then cut off, without you watching a spreadsheet. A prepaid wallet mode lets subscribers hold a balance that automatically settles invoices on renewal; they top it up themselves from the customer portal by card or crypto, and every top-up and deduction posts to the ledger.

Grace plans: invoice first, renew on payment

A common setup is a chain of plans: the paid plan expires into a short grace plan at full speed, then a slow plan, then the user is disconnected. Turn on Raise the renewal invoice when a paid plan expires into its next plan in Accounting → Settings and SAMM raises the renewal invoice at the moment the user moves to grace, due when grace ends. As soon as it is paid — at the counter, online or from the wallet — the user goes back to their plan, dated from the day it expired, so the billing day never drifts. Unpaid users simply continue down the chain.

Do not press Renew plan for these users Renew plan restores full service at once, paid or not. With the setting on, the invoice and the payment do the renewal for you. The setting is off until you turn it on.

Invoices are also generated automatically when a subscriber's plan is renewed (from the user's Renew Expiration action or by auto-renew), provided the plan has a price. The list filters by status — unpaid, partial, due, paid — and searches by invoice number or customer. Open any invoice for its detail page and a printable PDF; subscribers can download their own copies from the customer portal and Telegram bot.

Expenses

An expense is money spent running the ISP. New expense records a category (the expense account), the vendor paid, the amount, the date incurred and an optional due date. Each expense has the same unpaid / partial / due / paid lifecycle as an invoice, a detail page, and a printable voucher PDF.

Receipts & Payments

These two tabs record cash actually moving — distinct from the invoice or expense that caused it.

  • Receipts — money in: cash received from a customer, a reseller, or other income, landing in one of your cash accounts. An invoice is the bill; the receipt is the money arriving against it.
  • Payments — money out: cash paid against an expense or to a reseller.

Recording a receipt or payment moves the related invoice or expense toward paid and posts the matching ledger entry.

Customers & Card sales

The Customers tab lists each customer's running balance — what they owe you. Card sales covers prepaid hotspot revenue: it tracks sold card groups and resellers. A reseller buys whole card groups from you on an invoice, then resells the individual cards to end users; their balance owed is what they still need to pay you.

Agents — wholesale billing

An agent sells your service on to end customers on a prepaid wholesale model — think a franchise or a sub-dealer who runs their own book of subscribers but rides on your network. It is entirely optional: if you never create an agent, billing behaves exactly as it always has.

Two debts, cleanly separated The agent owes you the wholesale price (in your books, it is your revenue); the customer owes the agent the retail price (off your books — the agent's own receivable). Your commission is the gap between the two, booked as a trade discount, never as an expense.

Create an agent in Settings → Admins by giving a new admin the built-in Agent role. An agent is a scoped admin login with:

SettingMeaning
Commission %The agent's cut of the retail price (e.g. 40% — you keep 60% as wholesale revenue). Editable per agent, any time.
Credit limitHow far the agent's prepaid balance may go negative before renewals are refused. Set 0 for strict prepaid.
Prepaid balanceTop it up when the agent pays you; each renewal draws the wholesale price from it.

When one of the agent's subscribers renews, SAMM charges the agent's balance the wholesale price, posts your revenue, and raises a real retail invoice to the end customer that is payable to the agent and stays off your ledger. Agent-side dunning — its own switch under Settings → Billing, on by default, with an editable grace period — automatically suspends a non-paying customer (issuing a CoA disconnect); when the agent records the customer's payment, the subscriber reactivates on the spot.

An agent signs in to a scoped view: their own dashboard, a My Balance wallet page, a My Customers list with each customer's invoices and payments, and a My Statement — all limited to their own book. Your company-wide books, other agents and other admins' customers stay hidden.

Assets & Cash accounts

  • Assets — register fixed assets (routers, vehicles, equipment). SAMM tracks their value and depreciation over time.
  • Cash — manage your cash & bank accounts, and your capital accounts: owner's equity, where a contribution is money the owner puts into the business and a withdrawal is money taken out. Capital is not revenue and never appears in Profit & Loss.

Reports — the financial statements

The Reports tab is the accountant's view. Five statements, each date-ranged and exportable to PDF:

ReportAnswers
Profit & LossIncome vs expenses and net profit over a date range. Accrual basis — income counts when invoiced, expenses when incurred, not when cash moves.
Balance SheetAs of a date: what you own (assets) against what you owe (liabilities) plus equity. A balanced badge confirms the two sides match.
Cash FlowPer cash account — opening balance, money in, money out, closing balance over a range.
AgingOutstanding receivables and payables sorted into age buckets, so you can chase overdue invoices and stay ahead of bills.
AdvancedThe raw books: General Ledger (every line on one account with a running balance), Trial Balance (the balanced-books check), the Journal, and an activity log.
The balanced check In the Trial Balance every account's debit and credit columns must total equal — that is the proof the books are sound. If it is ever out of balance, it points to a posting error worth investigating.

Export to accounting software

Under Accounting → Reports → Export, download the books as CSV for QuickBooks, Xero or any spreadsheet: General Journal, Chart of Accounts, Invoices, Trial Balance, Profit & Loss and Balance Sheet. General Journal, Invoices and P&L use the date range; the rest are as-of today. The same data is available over the API at GET /api/v1/accounting/export/{kind} (format=json|csv, scope accounting:read) for BI pipelines and Zapier. Exports exclude voided entries, so a download always reconciles with the on-screen reports.

Daily operations

Undo & approvals

Most mistakes in an ISP panel are money mistakes: the wrong subscriber renewed, a payment recorded twice, a plan changed on the wrong account. SAMM gives you a five-minute undo window on those actions, and — where an action hands money back — a superadmin approval gate before it takes effect at all.

The undo window

Every admin action that moves money or state is recorded as it happens. For the next five minutes the topbar carries an Undo button and an Action history list — click the arrow to reverse the last action, or open the history and jump back to any point within the window. Redo puts it back.

Why only five minutes An undo is not a time machine — it is a safety net for the click you just made. Beyond a few minutes the world has moved on: the subscriber has been online, an invoice has been paid, someone else has edited the record. SAMM would rather refuse than quietly rewrite history, so the step simply leaves your history when the window closes.

An undo refuses — with the reason on screen — when reversing it would destroy something it did not create:

RefusalWhat it means
That record no longer existsThe subscriber, invoice or payment was deleted after your action — there is nothing left to put back.
That record exists againSomething has been re-created in its place; undoing would overwrite the newer record.
This record changed after your actionSomeone else edited it in the meantime — undoing would silently discard their edit.
That step is no longer in your historyThe five-minute window has closed.

Undo is a reversal, not a delete: the original action and its undo both stay in the Audit log, so the record of what happened is never lost. Actions that create something warn you plainly — undoing this will delete what it created — before they run.

The agent approval gate

An agent pays for a subscriber out of their own prepaid balance the moment they activate one. That makes reversing an action a way of getting money back — and a way to cheat: activate a subscriber, let them use the whole month, then delete them on the last day and reclaim the charge.

So SAMM splits an agent's actions by which way the money moves:

DirectionExamplesBehaviour
Costs the agent money Activate, renew, change plan, collect a customer payment Immediate. An agent's day job never waits for anyone.
Hands money back Undo, delete a subscriber, delete an invoice, void a collection Parked as a request. Nothing changes until a superadmin approves it.

Gated actions do not half-happen. The request is stored with everything needed to carry it out later, and approving replays it through the same code the agent would have run — never a second implementation that could drift from the first. Rejecting leaves the world exactly as it was, and the agent keeps the charge.

Working the queue

Requests land in Accounting → Agents Approval with the agent, the action, what it refers to and how much money it returns — the number that makes the decision. Filter by agent or status, search, tick several and approve or reject them together; a rejection can carry a short reason, which the agent sees.

Delegate it Reviewing agents all day is rarely the superadmin's job. The Agents Approval right can be granted to any role in Settings → Admins, so the person who actually does the reviewing gets exactly that power — and nothing else. Creating and managing agents stays superadmin-only. Nobody can decide their own request.

What the agent sees

An agent gets a My Account → Pending Approvals page listing everything they have asked for: what is still waiting, and what was approved or rejected — with the reviewer's reason. Without it a refusal would be indistinguishable from a request that vanished, and they would simply ask again.

They can withdraw their own pending requests — one at a time or several at once — because asking for something you cannot unask is its own trap. A withdrawn request never ran, so nothing changes; a decided one is history and stays. An invoice waiting on review also says so on its own page, so an agent who clicked Delete and saw nothing happen understands why.

For your subscribers

Online payments

SAMM can let your subscribers pay their own invoices online — by bank card (Stripe or PayPal), with crypto (Binance), or with Sham Cash in Syria. When a subscriber pays, SAMM marks the invoice paid, records it in your books, and — if they were cut off for non-payment — reconnects them automatically. You are never charged: each gateway uses your own account, so the money goes straight to you.

Turn it on (any gateway)

  1. Open Financial → Online payments (superadmin only).
  2. Click a gateway to expand it — Stripe, PayPal or Binance.
  3. Fill its fields, tick Enable this gateway, and click Save. SAMM won't let you save until the required fields are filled.
  4. Click Run test to confirm your credentials work.
  5. Done — your subscribers now see a Pay button on their unpaid invoices in the portal (and on the "subscription expired" page).

You can enable more than one gateway — the subscriber chooses which to use.

Stripe — bank cards, worldwide

  1. Create a free account at stripe.com. Keep Test mode on while you try it out.
  2. Go to Developers → API keys and copy the Secret key (it starts with sk_).
  3. In SAMM, expand Stripe, paste the Secret key, choose the currency and the cash account that receives it, then Save and Run test.
  4. Recommended: add a webhook so payments confirm reliably. In Stripe go to Developers → Webhooks → Add endpoint, set the URL to https://YOUR-SAMM/pay/webhook/stripe, choose the event checkout.session.completed, then copy its signing secret (whsec_…) into SAMM's Webhook signing secret field.
Going live Test mode works anywhere. Receiving real money through Stripe requires a Stripe-supported country and a linked bank account.

PayPal — cards & PayPal balance

  1. Create a PayPal Business account, then at developer.paypal.com create a REST App and copy its Client ID and Secret.
  2. In SAMM, expand PayPal, paste the Client ID and Client secret, choose Sandbox (testing) or Live, then Save and Run test.
  3. Recommended: add a webhook at developer.paypal.com → your App → Webhooks, URL https://YOUR-SAMM/pay/webhook/paypal, subscribe to CHECKOUT.ORDER.APPROVED and PAYMENT.CAPTURE.COMPLETED, then paste the Webhook ID into SAMM so incoming notifications are cryptographically verified.

Binance — crypto, works everywhere, no bank needed

This is the best option where cards and PayPal are not available. Your subscribers pay in crypto; SAMM watches your Binance account and marks the invoice paid automatically. You need three things: an API Key, an API Secret, and a place to receive — a wallet address and/or a Binance Pay ID.

Step 1 — create a read-only API key

Safety first Create the key with reading access only. Never enable Withdraw or Trade — SAMM only needs to read your incoming payments, never move funds.
  1. Log in to Binance → open Account → API Management (or search "API Management").
  2. Click Create API → choose System generated → name it e.g. "SAMM" → finish the security check.
  3. Binance shows the API Key and the Secret Key — copy both now (the Secret is shown only once).
  4. Click Edit restrictions and keep only "Enable Reading" ticked. Leave Spot Trading and Withdrawals OFF. (Optional: restrict the key to your server's IP address.)
  5. Paste the API Key and API Secret into SAMM's Binance card (Key first, then Secret — the same order Binance shows them).

Step 2 — get your receiving wallet address

  1. In Binance go to Wallet → Spot → Deposit (Deposit Crypto).
  2. Choose the coin USDT.
  3. Choose the network — TRC20 is the cheapest and most common; BEP20 and ERC20 also work. Use the same one you select in SAMM.
  4. Copy the deposit Address and paste it into SAMM's On-chain receiving wallet address field. Make sure SAMM's Network dropdown matches the network you chose.

Step 3 — (optional) Binance Pay ID

For subscribers who prefer Binance Pay (instant, no network fee): in the Binance app open Pay and note your Pay ID (your email or phone also works). Paste it into SAMM's Binance Pay ID field. Subscribers can then pay by Pay ID as well as on-chain.

Finally, tick Enable, click Save, then Run test (it checks the key can read your account). You're live.

Exact amount, correct network A subscriber must send the exact amount SAMM shows (the last small digits identify their invoice) on the correct network. A different amount or the wrong network will delay or lose the payment.

Sham Cash — Syria

Your users pay from their Sham Cash app or the Sham Cash website, and SAMM is told the moment the payment is done. The money goes to your own Sham Cash commercial account.

  1. Open a verified Sham Cash commercial account, then ask Sham Cash support to create an electronic payment service for you (they ask for your logo address and the name your users will see).
  2. Sham Cash gives you three values: the Agent Key, the Secret Key and the Base URL. A test service and the real service each have their own three values.
  3. In SAMM open Financial → Online payments → Sham Cash, keep Connection on Official API, paste the three values, choose the currency (USD or SYP, the same as your SAMM currency) and Save, then Run test.
  4. SAMM must be reachable from the Internet so Sham Cash can confirm each payment. If your SAMM is published under another address, enter it in Public SAMM address for the callback. Nothing has to be set up on the Sham Cash side for this: SAMM sends its own address with every payment.
Test service or real service With the test values every payment is a simulation: the payment page accepts the code 000000, SAMM shows the invoice paid, and no money reaches any account. Real payments need the values of your real service from Sham Cash support. Check the Base URL you saved: the test one is not the real one.

What the user does: on the payment card they press Open Sham Cash. On a phone it opens the Sham Cash app (version 2.2.5 or newer), otherwise the Sham Cash website; they check the amount and confirm with their transfer confirmation code (set up in their Sham Cash app). On a computer the card also shows a QR code to scan with the phone camera. Each payment link works for 10 minutes; the card confirms by itself as soon as Sham Cash does.

Sham Cash's own app can also take payments for you: give it a token with only the Payment apps permission (see the REST API section). It looks a user up by username and records the payment it took.

Sham Cash without merchant keys (Non-official API)

No merchant service from Sham Cash? SAMM can take Sham Cash payments through shamcash-api.com, an independent service (not Sham Cash) that reads the transfers arriving in your own Sham Cash account. It can only read: it cannot send money.

  1. Create an account at shamcash-api.com and link your Sham Cash account: in the Sham Cash app open My account → Linked devices and scan their QR code. Start its subscription and create a read-only API key.
  2. In SAMM open Financial → Online payments → Sham Cash, set Connection to Non-official API (shamcash-api.com), paste the API key, choose the currency and Save. SAMM reads your Account ID and your Sham Cash address from the key. Then Run test.

What the user does: the payment card shows your Sham Cash address (and its QR code), the amount and a short code such as SM-1234. The user sends the amount from their Sham Cash app and writes the code in the transfer note. SAMM confirms the payment within a minute. A transfer without the code, for less than the amount or in another currency is kept for your review instead of being applied.

Pay page and renewing online

Settings → Billing → Pay page turns on a public page at /pay: a user types their username, sees what they owe and pays, without logging in. The same Pay page is in the user portal for logged-in users.

  • Renew: users can renew their plan online for 1 to 12 periods, before or after it expires. Paying ahead keeps the time they still have; an expired user is back online as soon as the payment arrives. Two switches decide where it is offered: Renew on the Pay page and Renew in the user portal (both on by default).
  • Find users without their prefix or suffix: for usernames like 858000@inet, typing 858000 (at least 6 characters) finds the account. When more than one account matches, the user is asked for the full username. Off by default.
  • Choose what the page shows about the account (name masked, plan, expiry date and more); only the masked name is shown by default.

What the subscriber sees

  1. They log in to the customer portal → My invoices.
  2. On an unpaid invoice they click Pay (or "Pay · Stripe" / "Pay · Binance" if several are enabled).
  3. Card: they're taken to the gateway's secure page. Crypto: they see the exact amount, your address with a QR code, and/or your Pay ID.
  4. Once paid, the invoice turns Paid, it posts to your books, and if they were expired they're reconnected automatically — expired subscribers even get a "Pay & reconnect" button on the expired page.
Your books stay exact Every online payment posts one balanced double-entry (Dr Cash / Cr Accounts Receivable) and records the method (Stripe / Binance) on the invoice, in the payment history, and on the PDF — so you always know how each payment arrived.

Daily operations

Support tickets

SAMM has a built-in help desk. Subscribers raise tickets from the customer portal or the Telegram bot, an admin can open one on a subscriber's behalf, and your team works them all from Users → Support Tickets.

The ticket queue

The queue lists every ticket — number, customer, subject, priority, status, the opened and last-updated dates, and the message count. Filter it with:

  • Status chips — one per ticket status, each carrying a live count, so the workload is visible at a glance.
  • Priority — Normal, Moderate or Critical.
  • Active / Withdrawn — a customer can withdraw a ticket they no longer need; withdrawn tickets are dimmed and hidden by default.
  • Search — by ticket number, subject, or customer.

The sidebar badge counts open tickets so nothing is missed.

Opening a ticket

New ticket lets an admin raise a ticket for a chosen customer — pick the customer, then set a subject, priority and description. Subscribers also open their own from the customer portal or the Telegram bot.

Working a ticket

Open a ticket to read the full conversation thread. From there you can:

  • Reply to the customer — a public message the subscriber sees on their portal and through the Telegram bot.
  • Add an internal note — a staff-only message, hidden from the customer, for handover notes between your team.
  • Change the ticket's status and priority.

Right-click any row — or use its ⋮ button — for the same status, priority, reply and internal-note actions without leaving the queue.

Daily operations

Notification Center

SAMM keeps subscribers informed automatically — over email, Telegram, SMS and WhatsApp — and lets you broadcast messages. The samm-notification service delivers everything through one throttled queue. The System → Notification Center page has six tabs.

Overview

The landing tab — live counts (queued, sending, sent today, failed, skipped, opted-out), the state of each delivery channel, and a feed of the most recent notifications.

Channels

Configure how messages leave SAMM. Email uses its own notification account, kept separate from the password-recovery SMTP in Settings. Telegram uses a bot token, SMS goes through a generic HTTP gateway or Twilio, and WhatsApp uses the official Meta WhatsApp Cloud API (created in Meta for Developers), with an optional unofficial QR-linked bridge at your own risk — the bridge installs in one click on a bare-OS server and ships as a ready-to-run container on Docker. All channel secrets are stored Fernet-encrypted. Each subscriber, from the customer portal, picks which channels they want and can opt out entirely.

SMS gateways can also send in template mode, for carriers that only accept approved templates: you give the template name and SAMM sends the values in the order the template expects. Choose the number format each gateway wants (international with + or 00, or national with or without the leading 0). Paste a working gateway link from your provider and SAMM fills in the fields, the template mode and the number format for you.

Messages

The message templates, one set per event. Edit the wording of any notification — renewal reminders, receipts, and the rest — so every message goes out in your own voice and language.

Rules & Timers

This tab governs when and how automatic notifications fire. For each event you control:

  • Whether the rule is on.
  • Ignore opt-out — when set, the message reaches every subscriber even if they opted out. Reserve it for important transactional messages.
  • Timing — for example, how many days before expiry a renewal reminder is sent.
  • Delivery & throttling — the worker drains the queue one batch per tick; the batch size and tick interval together pace how fast messages go out, so a large broadcast never floods your mail server.

The events SAMM can emit on its own include the renewal reminder (before a subscription expires), the expiry notice (when it lapses), the quota warning (as a data cap runs low), the payment receipt (when a payment is recorded), and plan renewed.

Broadcast

Send a one-off message — a maintenance window, a price change — to a chosen set of subscribers. The broadcast flows through the same throttled queue as automatic notifications.

Outbox

Every message SAMM has queued or sent, with its per-message delivery status, so you can confirm a notification reached the subscriber or see why it did not.

System

VPN: WireGuard, L2TP/IPsec, SSTP

SAMM runs its own VPN server on the SAMM host so routers anywhere — behind NAT, on a mobile line, in another city — reach SAMM for RADIUS and management. Everything is under System → VPN; no shell needed. New installs come with all three ready, each switched off until you turn it on.

TypeUse it for
WireGuardRouterOS 7 routers, phones and laptops. The fastest and simplest.
L2TP/IPsecRouterOS 6 and 7 routers, and devices that have no WireGuard.
SSTPTwo or more routers that reach the Internet through the same public address, on RouterOS 6 or 7.

Server tab

  1. For WireGuard, click Generate Keys to create the server keypair.
  2. Check the listen port, the server tunnel address and the client address range, or keep the defaults.
  3. Turn the server on. A pop-up confirms each change.

If the SAMM host has a private address and your public address is forwarded to it, SAMM finds the public address (or you type it once on the VPN page) and gives it to every client and router.

Add a router in one paste

Click Add Client and give it a name. For a MikroTik, copy the one-line install link and paste it into the router's terminal: it sets up the tunnel, the router's own SAMM login, its RADIUS configuration and the expired-users page in one step. Choose how SAMM adds the router:

  • Managed NAS — the router authenticates your users through SAMM and SAMM manages it.
  • Monitor only — for access points and other devices you want to watch (health, map, the Wireless page) without users logging in through them.

A router added by branch staff belongs to their branch. WireGuard clients can also be added with a config file or a QR code for the mobile app. Clients can be renamed, switched off or deleted; their colour shows whether they are connected, stale or never seen.

Regenerating keys is destructive Regenerate Keys changes the WireGuard server keypair. Every client already set up stops connecting until it gets the new configuration. The panel asks you to type a word to confirm.

Network & routers

RouterOS 6 and 7

SAMM manages routers on RouterOS 6 and RouterOS 7 side by side. You do nothing different: SAMM reads each router's version and sends commands that version understands.

Everything works on both: the setup wizard, Auto-Complete, config delivery, Manager actions, Websites & Apps, QoS, NTP, the expired-users page and the WireGuard (RouterOS 7), L2TP/IPsec and SSTP links. On RouterOS 6, Websites & Apps lists are built from the catalogue's domain names, because version 6 has no DNS address lists.

Old routers with no WireGuard RouterOS 6 has no WireGuard. Bring those routers in over L2TP/IPsec or SSTP.

Network & routers

Config delivery

Every change SAMM sends to your routers — RADIUS, the expired page, the wizard, the DNS filter, Websites & Apps, QoS, Auto Security, DNS, NTP and parental control — is one delivery you can follow under Devices → Config delivery.

  • A progress bar and the result for each router, with the exact reason when a router refuses a change.
  • A router that is offline gets the change as soon as it comes back; failed changes retry by themselves, and Retry is one click.
  • Each change is checked on the router after it is applied, and RADIUS and QoS are never left empty while it is being made.

Network & routers

Manager actions on many routers

In Devices → Manager, tick routers and open Actions to run one job on all of them: push Websites & Apps, push the RADIUS configuration, set up the expired-users page, Router Security, backup and export, RouterOS update, run a script, or reboot.

Each dialog starts from the fullest settings found among the routers you picked. Jobs run in the background: you can leave the page, and a pop-up tells you when each router finishes or why it failed. Risky actions ask you to type a word to confirm. The Manager also shows each router's branch.

Network & routers

Dynamic Speed Booster

While a router's Internet sits unused, give its users more speed for free — and take it back the moment the line gets busy. Turn it on under Tools → Speed Boost → Dynamic (off by default) and pick the plans it may boost.

  • Everyone online on that router gets the same multiple of their download speed, up to 3 times by default.
  • The booster learns each router's busy and quiet hours (3 days by default, recent days count most), plans every 15 minutes, looks an hour ahead and raises a boost step by step.
  • A guard checks every minute and ends a boost as soon as traffic returns. Routers that are busy most days are never boosted.
  • Users see a Boosted badge in their portal; the Users list has a Boosted column and filter.

Daily operations

Activations & Data Log

Activations

Overview → Activations shows which plans are activated the most this week, month, year or between two dates, against the period before: renewals, new users and plan changes. The By plan and By user lists have search, filters, sorting and Excel or CSV export.

Data Log

Overview → Data Log searches every user's Data Log at once: find who reached an address or a range, a port, a protocol or an app, in any period. Group the results, save views and export to CSV or XLSX. How long the history is kept is your choice, set in the History cleaner.

Accept Log

The Accept Log shows which router each login attempt came from, with search, grouping, sorting and export by router.

System

Branding: your logo, name and colour

Make SAMM look like your company. Everything is on System → Settings → ISP.

Your logo

  1. Press the logo tile or Upload logo and choose a PNG, JPEG, WebP or GIF picture (up to 5 MB).
  2. Drag the picture to place it and use the slider to zoom. A transparent background stays transparent.
  3. Press Use logo: it is saved at once as a 400×400 px square. Remove takes it away.

The logo is used on invoices, receipts, printed hotspot cards, the expired page and the login pages your routers show.

Branding on the panels

Switch on Use my brand on the panels and set the name, the colour and a footer line (for example your support number), then press the ISP tab's Save. Your brand then replaces SAMM's on the admin panel, the user portal and both sign-in pages. Switch it off and everything looks as it always has.

System

Cloudflare Tunnel

A Cloudflare Zero Trust tunnel publishes SAMM to the public internet without opening any firewall ports — useful when the SAMM host sits behind NAT. It is managed from System → Cloudflare Tunnel.

Service status

The page opens on a status card that reports the connector's state:

StateMeaning
RunningThe tunnel is active and forwarding traffic
StoppedConfigured but not currently running
Not configuredThe binary is present — paste a token to set it up
Not installedRe-run install.sh to install the cloudflared binary

It also shows the cloudflared version and whether the connector is set to auto-start at boot.

Configure the tunnel

  1. In the Cloudflare Zero Trust dashboard (one.dash.cloudflare.com), open Networks → Tunnels and Create a tunnel.
  2. Choose the Cloudflared connector, name the tunnel, and save. On the install step, copy only the token — the long string after --token.
  3. Paste it into SAMM and click Configure Tunnel. SAMM hands the token to cloudflared and starts the connector.
  4. Back in Cloudflare, add a Public hostname: your chosen address, type HTTP, URL localhost:80 (proxied by nginx — recommended) or localhost:8000 (direct to the API).

Within a few seconds the status badge turns green and SAMM is reachable on the public hostname. Once configured, one-click actions let you Start, Stop or Restart the connector, Replace Token to rotate it, or Remove tunnel (a type-REMOVE-to-confirm action).

No open ports, token never in the database The tunnel makes an outbound connection to Cloudflare's edge — no firewall port is ever opened on the server. The token is forwarded to cloudflared and stored under /etc/cloudflared/; SAMM never persists it in the database. TLS terminates at Cloudflare's edge, so SAMM itself runs plain HTTP on the loopback.

System

Settings

System → Settings holds the live, hot-reloadable tunables. The daemons re-read them on their next tick — no service restart is needed. Settings are organised into tabs.

General tunables

SettingDefaultControls
samm-radius interval30 sHow often time-driven events are evaluated and CoAs sent
samm-worker interval5 sRouter ping + MikroTik API sync cadence
Acct interim interval60 sThe accounting interval pushed to routers
Daily reset time00:00When daily usage counters roll over
Server timezoneUTCTimezone for speed windows and the daily reset
CoA default port3799Default UDP port for CoA packets
CoA retry max3Retries before the Disconnect-Request fallback

Lower the samm-radius interval for tighter enforcement; raise it to reduce load.

ISP identity, logo, currency & billing (the ISP tab)

Everything most operators ask "where do I change this?" lives on System → Settings → ISP. Edit a field and click Save — the change is live immediately (no restart) and flows onto invoices, receipts, PDFs and the customer portal.

What you changeWhere it shows
ISP nameInvoices, receipts, hotspot cards, portal header
Support phone & emailInvoices and printed hotspot cards
Tax / registration numberPrinted on invoices
ISP logo (upload PNG/JPEG/WebP/GIF)Upload, then drag and zoom to crop it in the browser; appears on invoice/receipt PDFs, printed hotspot cards and router login pages. See Branding.
Currency code (e.g. USD)The ISO currency on invoices and the ledger
Currency symbol (e.g. $)Every amount shown in the admin UI, customer portal and PDFs
Tax on/off, label & rateAdds a VAT/GST line to invoices (e.g. label VAT, rate 11 = 11%)
Change the money symbol To switch the currency shown everywhere (e.g. from $ to £ or a local symbol), set Currency symbol on the ISP tab and Save — it updates the admin panel, the customer portal and all PDFs at once. Set the Currency code (USD, EUR, …) alongside it for the ISO code printed on invoices.

Privacy — anonymous install statistics

When SAMM checks for updates it can send SecuryTik a random install ID, the SAMM version, your plan tier and a coarse country (from your IP, via Cloudflare) — no subscriber or customer data. It only helps us count active installs and prioritise support and languages. Turn it off any time under System → Settings → Privacy; see the privacy policy.

Email tab

Configure the SMTP server used for password-recovery codes sent to admins and customers (host, port, SSL/STARTTLS, username, from-address, password). Click Test connection to verify the credentials without sending mail.

Two email accounts The Email tab here is only for OTP / password recovery. The account used for customer notifications is configured separately in the Notification Center.

System

Admins, branches & roles

System → Admins is where you decide who can sign in to the admin portal, what each person can do, and which users they can see. Since 5.1.0 the admins form a tree of branches and staff. The page has two tabs: Admins and Roles.

Branches and staff

NodeWhat it is
BranchA place — an office, a city. It owns the users created in it. Nobody signs in as a branch: it has no password and no role.
Admin (staff)A person who signs in. Placed under a branch, they are its staff: every user and card they create belongs to that branch.
SuperadminAlways at the top of the tree, never under a branch. Sees and can do everything.

Use + Branch and + Admin to build the tree, and drag a node onto another to move it. Only a branch can have admins under it. An agent is an admin who sells and owns what they sell; staff placed under an agent use the agent's wallet and approval rules.

Who sees what

Visibility follows the tree. A branch — and everyone working in it — sees its own users and the users of the branches below it. It never sees a sibling branch or the branch above. HQ sees everything. An admin's permissions are never more than the admins above them allow, and an admin can only grant what they hold themselves.

Limits per branch

LimitWhat it counts
Max usersHow many users the branch and the branches under it may hold. Deleting a user frees a place.
Max cardsHow many hotspot cards may be printed in the branch.

A new user or card is refused when any limit at or above the admin creating it is reached, and the message says which limit and how much is left. Leave a limit empty for no limit. Both can be changed later from the Edit dialog.

Devices of a branch

Every router, access point included, belongs to a branch or to Headquarters. Open a branch's menu and choose Assigned devices to tick the devices that belong to it; a device you untick goes back to Headquarters, which every branch shares. A device added by branch staff (from the Manager, the monitor form or a VPN install link) lands in their branch; one added by Headquarters starts at Headquarters.

WhoA device of the branch
Staff of that branch, of the branches above it, and HeadquartersManage it
Staff of its child branchesSee it, read-only
Other branchesDo not see it
Users of that branch and of its child branchesCan log in through it

The map, the Wireless page, health and router lists follow the same rule. The login part is the setting Users log in only through their branch's routers in Settings → Authentication: on for new installs; an updated install whose devices were given to branches starts with it off, so nobody is cut off — switch it on when your devices are assigned. Users of the General company may use any router.

Alert recipients per branch

A branch's menu also has Alert recipients: e-mail addresses, WhatsApp and SMS numbers and Telegram chats, one per line. When a device of that branch (or of a branch below it) goes down, has a fault, blocks an attack or misses its configuration, they are told. Headquarters still gets every alert.

Price Lists

Financial → Price Lists (superadmin only) sets a price for every plan and add-on, per branch. A sub-branch follows its parent's prices unless given its own, and a new branch starts from the plan's card price. Change many prices at once by a percent or a fixed amount, with rounding; Reset All drops a branch back to its parent, and the list exports for review.

Roles & permissions

A role grants per-area access. SAMM ships four ready-made roles you can edit or delete — Manager (day-to-day operations), Reseller, Accountant (financials) and Monitor (read-only) — and two locked built-in roles: superadmin (full access) and Agent, which turns the admin into a wholesale reseller with a prepaid balance and a commission split (see Accounting & billing → Agents).

For each area of SAMM (users, plans, routers, accounting, settings, and so on) a role is set to one of three levels:

LevelMeaning
Not allowedThe area is hidden from the sidebar entirely
ViewRead-only access
EditFull access — create, change, delete

Admins & roles, Tools, API and Payments stay with HQ whatever a role says.

Two rights sit beside the area levels, because each one is a money decision rather than a screen:

RightWhat it allows
Allow "No Invoice" Change a user's service — renew, change plan, extend — and charge nothing for it. Off by default on every new role.
Allow Agents Approval Review and decide the requests agents file to reverse a charge. Creating and managing agents stays superadmin-only. See Undo & approvals.

Detailed permissions

Under Edit, Users, Cards, Financial and Routers open into individual rights — for example delete users, renew, change plan, pay invoices, give discounts, run router scripts. Turn any of them off for a role; the buttons for a right the role lacks are hidden.

Time a role may give

Stop staff from handing out months of service. On each role:

SettingEffect
Max periods aheadThe expiry may be at most this many plan periods from now — on create, renew, add days, edit and bulk changes.
Max days aheadThe same, counted in days.
New users start with (hours)A user this role creates gets exactly this much time (for example 2 hours) and no invoice; someone allowed to give more extends it later.

Add days and Type an expiry date are separate rights under Users, so a role can renew without being able to type any date it likes. Leave a field empty for no limit; the superadmin is never limited. A bulk change skips the users it would take past the limit and says why.

A role can also be allowed to see every user & card on the install, regardless of the tree. With it off, the role sees its own branch and the branches beneath it.

The dashboard is never taken away Whatever else a role is denied, every admin keeps their own dashboard and profile — a login that lands on a permission error is a broken login, not a secure one.
License is always reachable The System → License page is a normal permission block — but whenever the device is in a lockdown state (grace, soft or hard) SAMM forces it reachable for every signed-in admin regardless of role, so the recovery path is never walled off.

System

Tools

The Tools section bundles bulk and maintenance utilities. It acts on the entire dataset, so it is available to superadmins only.

Backup & Restore

Create a full database snapshot before any major change. A backup is a gzipped pg_dump archive stored on the server, each with a SAMM header.

  • Create backup — optionally add a note; tick Skip usage & history for a smaller, faster dump that omits bulky log tables.
  • Download a backup to your PC, or upload a previous SAMM backup back to the server.
  • Restore overwrites the current database — gated by a type-RESTORE-to-confirm dialog.

High availability

For a deployment with no single point of failure, run SAMM across two nodes: PostgreSQL streaming replication (a primary with a seconds-behind hot standby) plus a standby AAA node, and promote + repoint on failure. The full operator runbook — replication setup, planned and unplanned failover, failback, an optional synchronous-replication mode, and a post-failover verification checklist — ships as docs/HA.md with the source. Note that replication is not a backup (a bad delete replicates instantly), so keep the scheduled backups above running too.

History Cleaner

Permanently delete old log and history rows to reclaim database space. Pick a retention preset and confirm. The cleaner trims closed RADIUS sessions, post-auth records, daily-usage rollups, router/interface history, limitation logs, applied audit entries, and finished CoA rows. It never touches live sessions, queued commands, pending CoAs, or the non-resettable lifetime usage totals.

Take a backup first History Cleaner deletes permanently. Run a backup before cleaning if you might want the data later.

Export / Import

Bulk export and import for Users, Plans and NAS as .csv or .xlsx. Download a template (the right columns plus a sample row) or a snapshot of current data, fill it in, and upload it back. Every row is validated and shown on a preview screen — duplicates and invalid rows are surfaced, and you choose whether to skip duplicates or update them in place — before anything is written.

Bulk Changes

Apply one change — owner, expiration date, status, auto-renew, or whole plan periods — to every subscriber matching a filter, in a single run. Pick the change, build the filter (status / plan / owner / search), review the matching list, and confirm.

Add whole plan periods is the renewal-in-bulk option: each subscriber gains that many periods of their own plan, so a 7-day plan gains 7 days per period and a monthly plan gains a calendar month — on the same run, without splitting the list by plan first. Subscribers whose plan has no expiration period are skipped rather than guessed at. Add days remains available where you want a flat number of days and no counter reset.

Speed Boost

Raise or lower the speed of whole plans at once by a percentage — a holiday weekend at double speed, or an emergency throttle while a backhaul is degraded. It takes effect immediately, for new logins and for sessions already online.

ControlWhat it does
PercentagePositive multiplies, negative divides: +100% → double speed, −100% → half speed, −500% → a sixth of it. Speed never reaches zero.
Plans to boostTick any number of plans; each row shows the plan rate, the boost in force and the effective speed right now.
Revert automatically afterHours until the boost lapses on its own. 0 keeps it until you reset it by hand.
A boost outranks a speed window The boost is measured from the plan rate and replaces any speed window while it is live — a plan on a 20M night window does not become 40M, it becomes whatever the boost makes of its plan rate. Windows resume the moment the boost lapses.

A subscriber who has exhausted a limit is never lifted back to full speed by a boost. For the same reason, a plan used as a throttle target is skipped by Select all and labelled as such — boosting it would speed up exactly the people you are throttling. You can still tick it by hand if that is what you intend. Reset everything to normal removes every boost and puts live sessions back on their plan speed.

Bulk Delete

Permanently delete many subscribers or hotspot cards at once, selected by filter. Deleting a subscriber also removes their usage history, sessions, RADIUS accounting and invoices, and disconnects any live session. Gated by a type-DELETE-to-confirm dialog.

System

Languages & themes

Languages

The admin and customer portals are fully translatable. Eight languages ship built in: English, Arabic (right-to-left), Russian, Persian (right-to-left), Turkish, French, Spanish and German. Each user picks their language from the top bar or their profile; the choice is remembered per account.

Switch a language off

In System → Translations each language has an on/off switch (superadmin only). A language that is off cannot be chosen by anyone: pickers stop offering it, people who had chosen it see English, and messages to them are written in English. English always stays on. A new install starts with every language on.

The translation editor

A superadmin can edit translations live from System → Translations — no restart, no file editing. The editor also creates entirely new languages and imports/exports translation workbooks as .xlsx, so you can localise SAMM into any language you serve.

Themes

SAMM ships 16 visual themes, light and dark. Each user picks a theme from the top bar; the preview updates instantly and is saved per account. IT terminology is never translated, so technical screens stay precise in every language.

System

Audit log & activity

System → Audit Log answers one question: what happened, and who did it. One list holds every change an admin made, what the system did on its own (such as expiry), and the changes users made to their own account in the portal or on Telegram — plan changes, renewals, payments, profile and password edits.

ColumnWhat it shows
WhenThe time, in your timezone
WhoThe admin, "ali, in the portal", "ali, on Telegram", an API token, or System
What happenedOne sentence, with only the fields that moved, old → new — for example "Edited the user: Expiry: 01 Oct → 15 Oct"
TargetWhat it was done to — User · ali, Plan · Gold 20M, Router · Hamra, Admin · rami

Filter by Who and Period, or type a name in the search box. Logins and exports are hidden unless you tick Show logins & exports. Via, Action, Category, Severity and ID are in the column picker. Select rows to Export or Print — the file has the same columns as the screen. The ⓘ button on a row shows the full before-and-after table.

User timeline

Open a user and choose Timeline for everything that ever happened to that one account — created, renewed, plan changed, suspended, limits reached — with invoices, payments, wallet and agent charges in an Amount column. Filter by kind or period, or money only, and export to CSV or Excel. Timeline rows are never pruned and survive the user being deleted.

Accept Log and Access Log

Overview → Accept Log lists every login attempt the routers sent and RADIUS's answer, newest first, with the reason for each refusal. It is the page to open when a user cannot connect. A refusal that keeps repeating is one line with a count. Overview → Access Log lists the sessions that did start, from RADIUS accounting.

Also a command queue Resets, plan changes and renewals queued from the CLI or the API are written to the same table and applied by the samm-radius service on its next tick, which then refreshes a live session with a CoA. The sidebar badge counts those still pending.

Licensing

Licensing & tiers

Each SAMM installation is licensed per device — the plan lives on that install, so you can run several SAMM servers, each on its own tier. The tier sets four numeric caps.

TierAAA usersHotspot cardsNAS / routersMonitors
Unregistered252513
Free1005026
Lite5001,500412
Plus1,0003,000618
Pro2,0006,0001236
Mega5,00015,0002472
Max10,00030,000unlimitedunlimited
Unlimitedunlimitedunlimitedunlimitedunlimited

A fresh install runs unregistered at the minimum floor. Every feature is available at every tier — the tier only sets the caps. Creating a subscriber, card or NAS past the cap is blocked until you upgrade; no data is ever lost.

Monitors are the access points and links SAMM only watches. They have their own allowance, three per NAS, so watching an access point never uses up a router slot.

Activate & upgrade

  1. Open System → License.
  2. Activate by signing in with your SecuryTik account — or use Link this device, which shows a code you approve on samm.securytik.com without typing your password on the server. The device activates on Free.
  3. To go higher, pick a plan from the same page, or subscribe from your dashboard. A request from the page is reviewed and approved by a SecuryTik admin.

The License page also re-checks the license on demand and shows your current usage against each cap. Unlink device drops the install back to the unregistered tier without deleting any data.

If a paid license lapses

SAMM never deletes data. A lapsed license steps down gracefully:

StageWhat happens
WarningA reminder banner; everything keeps running
GraceA short window to reactivate; subscribers stay online
Soft lockdownBackground services stop; RADIUS keeps authenticating for about 7 days
Hard lockdownServices stop except the reactivation page

Reactivating at any stage restarts every service automatically — all subscriber data and history are intact.

Automatic updates

Auto-update is independent of licensing — every tier updates, and a lapsed license never blocks it. SAMM checks for a new signed release daily. From System → License you can switch between notify (the default — a banner with an Apply now button) and auto (apply unattended). Each update is verified, backed up, and applied in place. You can also re-run the installer at any time — it upgrades idempotently.

For your subscribers

Customer portal & bot

SAMM gives every subscriber two self-service surfaces — a web portal and a Telegram bot — so they can check usage and pay without contacting you.

The customer portal

Subscribers sign in at the SAMM site root (/) with their SAMM username and password. The portal has:

PageWhat the subscriber sees
OverviewAccount status, plan, expiry, today's and this month's usage, any outstanding invoice
Usage & sessionsTotal downloaded/uploaded, uptime budget, and full session history
My plansThe current plan plus the catalogue of available plans
My invoicesBilling history with one-click PDF download
Support ticketsOpen and follow support tickets
ProfileEdit contact details, change password, set language & theme, manage notifications

From Profile, a subscriber connects their Telegram account, orders their preferred notification channels, or opts out of notifications entirely. If they forget their password, an OTP code is emailed to them (this needs the Email tab configured).

The Telegram bot

The samm-telegram service runs an interactive self-service bot. A subscriber sends /start, verifies once with their SAMM username and password (the bot deletes the password message immediately), and can then, entirely from chat:

  • Check their plan, quota, usage and expiry date
  • View and download invoices as PDF
  • Update their profile and change their password
  • Open and follow support tickets

The bot also delivers the automatic notifications — renewal reminders, expiry notices, quota warnings and receipts — to subscribers who connected Telegram.

The expired-subscriber landing page

When a subscriber expires, the router (configured by the wizard's "Expired pool & internet block") redirects their browser to a friendly "subscription expired" page served by SAMM on port 81 — with your ISP logo and a login button into the portal — instead of a silently dead connection.

System

REST API

System → API manages the public /api/v1 interface. The API is dormant until you create the first token, so an install that never uses it exposes nothing. Everything below is also available as interactive OpenAPI documentation — with a try-it console and full request/response schemas — on your own install at /api/v1/docs.

Interactive docs (Swagger UI)

Every install serves a live API console at /api/v1/docs — reachable straight from the API panel in the admin portal. Click Authorize, paste a token, and any endpoint can be executed against your own data with Try it out; each call shows the real response plus a ready-to-copy curl command.

Every endpoint declares a complete, typed schema — request bodies and responses alike — so field names, types and examples are visible without calling anything. The same schema is served as machine-readable OpenAPI at /api/v1/openapi.json, which generates a fully typed client in the language of your choice:

openapi-generator-cli generate \
  -i https://YOUR-SAMM/api/v1/openapi.json \
  -g python -o ./samm-client

samm-openapi.json · SAMM 6.0.0 · 187 endpoints

Quick start

  1. Open System → API (superadmin only), press New token, give it a name, an expiry and turn on only the permissions the integration needs (Read or Write, one line per area).
  2. Copy the secret immediately — it is shown exactly once and only its hash is stored on the server.
  3. Verify it works and see what the token can do:
curl -H "Authorization: Bearer samm_YOUR_TOKEN" https://YOUR-SAMM/api/v1/me

List active subscribers, then create one:

curl -H "Authorization: Bearer samm_YOUR_TOKEN" \
  "https://YOUR-SAMM/api/v1/customers?status=active&limit=20"

curl -X POST -H "Authorization: Bearer samm_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username":"john","password":"secret1","firstname":"John",
       "lastname":"Doe","plan_id":3}' \
  https://YOUR-SAMM/api/v1/customers

Authentication, tokens & scopes

Every request sends Authorization: Bearer <token>. A token carries a name, a per-minute rate limit, an expiry (30–360 days or never) and a set of scopes — per-resource read/write grants; a write scope automatically includes the matching read. The secret is shown exactly once; the server stores only a hash. A token can be revoked (calls fail immediately, reversible) or deleted outright.

Responses follow one set of conventions: list endpoints take limit/offset and return {"total", "items"}; errors use standard status codes — 401 missing/invalid/expired token, 403 missing scope, 404 not found, 409 duplicate, 422 validation error, and 429 when the rate limit is hit (with Retry-After and X-RateLimit-* headers).

Money in the payment, wallet and webhook data is a decimal string such as "12.50"; times are ISO 8601 with the install's offset.

Endpoint reference

AreaEndpointsScope
Token & commands GET /commands · GET /me any token
Users GET /customers · POST /customers · POST /customers/bulk · GET /customers/{customer_id} · PATCH /customers/{customer_id} · DELETE /customers/{customer_id} · POST /customers/{customer_id}/activate · POST /customers/{customer_id}/assign-plan · PUT /customers/{customer_id}/custom-fields · GET /customers/{customer_id}/data-log · POST /customers/{customer_id}/disconnect · POST /customers/{customer_id}/renew · POST /customers/{customer_id}/reset-limit · POST /customers/{customer_id}/suspend · GET /customers/{customer_id}/timeline · GET /customers/{customer_id}/usage · GET /customers/{customer_id}/timeline/export.{fmt} coa:write customers:read customers:renew customers:write diagnostics:read
Plans GET /plans · POST /plans · GET /plans/{plan_id} · PATCH /plans/{plan_id} plans:read plans:write
Invoices GET /invoices · POST /invoices · GET /invoices/{invoice_id} · DELETE /invoices/{invoice_id} · POST /invoices/{invoice_id}/pay · GET /invoices/{invoice_id}/pdf · POST /invoices/{invoice_id}/unpay billing:read billing:write
Payments, discounts & wallet GET /cash-accounts · GET /customers/{customer_id}/wallet · GET /invoices/{invoice_id}/balance · POST /invoices/{invoice_id}/discounts · POST /invoices/{invoice_id}/payments · POST /customers/{customer_id}/wallet/pay-invoice · POST /customers/{customer_id}/wallet/topup · POST /customers/{customer_id}/wallet/withdraw · DELETE /invoices/{invoice_id}/discounts/{discount_id} billing:read billing:write
Payment apps (collect) GET /collect/lookup · POST /collect/payments · GET /collect/payments/{channel}/{reference} collect:read collect:write
Accounting export GET /accounting/export · GET /accounting/export/{kind} accounting:read
Add-ons & price lists GET /addons · GET /price-lists · DELETE /user-addons/{user_addon_id} · GET /customers/{customer_id}/addons · POST /customers/{customer_id}/addons addons:read addons:write
Hotspot cards GET /cards/groups · POST /cards/groups · GET /cards/{card_id} · GET /cards/groups/{group_id} · POST /cards/{card_id}/disable · POST /cards/{card_id}/enable · GET /cards/groups/{group_id}/cards · POST /cards/groups/{group_id}/cards · POST /cards/groups/{group_id}/disable · POST /cards/groups/{group_id}/enable · POST /cards/groups/{group_id}/extend · GET /cards/groups/{group_id}/print.pdf · POST /cards/{card_id}/reset/{kind} cards:read cards:write
Sessions & CoA GET /coa-outbox · GET /sessions · POST /coa-outbox/cancel · POST /coa-outbox/retry · POST /sessions/disconnect · POST /sessions/reconnect coa:write sessions:read
Webhooks GET /webhooks · POST /webhooks · GET /webhooks/events · PATCH /webhooks/{endpoint_id} · DELETE /webhooks/{endpoint_id} · GET /webhooks/{endpoint_id}/deliveries · POST /webhooks/{endpoint_id}/disable · POST /webhooks/{endpoint_id}/enable · POST /webhooks/{endpoint_id}/roll-secret · POST /webhooks/{endpoint_id}/test · POST /webhooks/deliveries/{delivery_id}/resend webhooks:manage
User files GET /customers/{customer_id}/files · POST /customers/{customer_id}/files · GET /customers/{customer_id}/files/{file_id} · DELETE /customers/{customer_id}/files/{file_id} customers:read customers:write
Branches GET /branches · PUT /customers/{customer_id}/branch admins:write customers:read
Admins GET /admins customers:read
Self Service (guests) GET /self-service/handouts · GET /self-service/summary guests:read
Statistics GET /stats/overview stats:read
Routers & router control GET /routers · POST /routers/jobs · GET /routers/playbooks · GET /routers/{router_id} · GET /routers/jobs/kinds · GET /routers/jobs/prefill · GET /routers/jobs/{job_id} · GET /routers/{router_id}/log · POST /routers/{router_id}/probe · GET /routers/{router_id}/probes · GET /routers/{router_id}/radius · GET /routers/{router_id}/ros · POST /routers/{router_id}/ros · POST /routers/{router_id}/scoop-change · GET /routers/{router_id}/scoop-changes · POST /routers/{router_id}/script · GET /routers/{router_id}/test · GET /routers/{router_id}/traffic · POST /routers/jobs/{job_id}/cancel · GET /routers/wireless/by-user/{customer_id} · GET /routers/{router_id}/ppp/{username} · GET /routers/{router_id}/scoop-change/preview · POST /routers/{router_id}/scoop-change/{change_id}/undo routers:diagnose routers:jobs routers:read routers:write
Network map & health GET /network/findings · GET /network/health · GET /network/topology · PUT /customers/{customer_id}/features · GET /network/ftth/olts · GET /network/ftth/onus · GET /network/wireless/aps · GET /network/wireless/stations · GET /routers/{router_id}/reach · POST /routers/{router_id}/reach · DELETE /routers/{router_id}/reach/{reach_id} customers:write routers:read
Bulk import POST /imports/users imports:write
Backups GET /backups · POST /backups · GET /backups/schedule · PUT /backups/schedule · DELETE /backups/{name} · GET /backups/{name}/download · POST /backups/{name}/restore backups:read backups:write
History cleaner POST /history/clean · GET /history/schedule · PUT /history/schedule · GET /history/space history:read history:write
VPN clients GET /vpn/l2tp/clients · POST /vpn/l2tp/clients · GET /vpn/sstp/clients · POST /vpn/sstp/clients · GET /vpn/wireguard/clients · POST /vpn/wireguard/clients · PUT /vpn/l2tp/clients/{cid} · DELETE /vpn/l2tp/clients/{cid} · PUT /vpn/sstp/clients/{cid} · DELETE /vpn/sstp/clients/{cid} · PUT /vpn/wireguard/clients/{peer_id} · DELETE /vpn/wireguard/clients/{peer_id} · GET /vpn/l2tp/clients/{cid}/config · GET /vpn/l2tp/clients/{cid}/mikrotik · POST /vpn/l2tp/clients/{cid}/toggle · GET /vpn/sstp/clients/{cid}/config · GET /vpn/sstp/clients/{cid}/mikrotik · POST /vpn/sstp/clients/{cid}/toggle · GET /vpn/wireguard/clients/{peer_id}/config · GET /vpn/wireguard/clients/{peer_id}/mikrotik · POST /vpn/wireguard/clients/{peer_id}/toggle vpn:read vpn:write
Diagnostics GET /diagnostics diagnostics:read
Support & logs GET /audit · GET /auth-log · GET /audit/actors · GET /support/alerts · GET /support/backups · GET /support/database · GET /support/errors · GET /support/license · GET /support/logs · GET /support/notifications · GET /support/payments · GET /support/probe · GET /support/queues · GET /support/self-test · POST /support/service-restart · GET /support/services · GET /support/settings · PUT /support/settings · GET /support/system · GET /support/update · GET /customers/{customer_id}/why-blocked · GET /support/errors/{incident} · GET /support/payments/incoming customers:read diagnostics:read errors:read logs:read services:write settings:write
Reports GET /reports/activations · GET /reports/financial · POST /retention/lookup · GET /customers/{customer_id}/statement accounting:read customers:read retention:lookup
Scoop GET /scoop/schedules · POST /scoop/schedules · DELETE /scoop/schedules/{schedule_id}

Invoices, payments, discounts & wallet

Every money call goes through SAMM's double-entry books, exactly like the panel. An invoice owes total − paid − discount; its status moves from unpaid/due to partial and paid (or discounted when discounts alone settled it).

# what an invoice still owes
curl -H "Authorization: Bearer $T" https://YOUR-SAMM/api/v1/invoices/501/balance

# a 10 percent discount (or "kind":"fixed","value":"2.00")
curl -X POST -H "Authorization: Bearer $T" -H "Content-Type: application/json" \
  -d '{"kind":"percent","value":"10","reason":"Loyalty"}' \
  https://YOUR-SAMM/api/v1/invoices/501/discounts

# a partial payment into a cash account (GET /cash-accounts)
curl -X POST -H "Authorization: Bearer $T" -H "Content-Type: application/json" \
  -d '{"amount":"5.00","cash_account_id":1,"memo":"Counter"}' \
  https://YOUR-SAMM/api/v1/invoices/501/payments

# prepaid wallet: top up (pays open invoices oldest first), then read it
curl -X POST -H "Authorization: Bearer $T" -H "Content-Type: application/json" \
  -d '{"amount":"25.00","cash_account_id":1}' \
  https://YOUR-SAMM/api/v1/customers/42/wallet/topup
curl -H "Authorization: Bearer $T" https://YOUR-SAMM/api/v1/customers/42/wallet

POST /invoices/{id}/unpay reopens a paid invoice and DELETE /invoices/{id} closes one out correctly (a part-paid remainder is written off). The books export as JSON or CSV from GET /accounting/export/{kind}.

Payment apps

Money-transfer apps and shop agents (Wish Money, Sham Cash…) get their own scopes, collect:read and collect:write, and three calls: look a user up by username (masked name, amount due, open invoices), record a payment, and read it back. A payment is idempotent on its reference: sending the same one again returns the first answer and books nothing.

curl -H "Authorization: Bearer $T" "https://YOUR-SAMM/api/v1/collect/lookup?username=ali"

curl -X POST -H "Authorization: Bearer $T" -H "Content-Type: application/json" \
  -d '{"username":"ali","amount":"20.00","reference":"WM-88213","channel":"wishmoney"}' \
  https://YOUR-SAMM/api/v1/collect/payments

Queued commands

Mutations that touch live accounting state — limit resets, card and group enable/disable, validity extensions — are not applied inside the request. They are queued into the audited command queue and applied by samm-radius within one tick (a few seconds), exactly like the same clicks in the admin portal. Such endpoints reply {"queued": true}; poll GET /commands to see your token's queued commands flip to applied.

Webhooks

Register an endpoint URL in System → API → Webhooks or with POST /webhooks, and pick events: single ones, a whole group such as invoice.* (later events of that group included) or * for everything. The signing secret is shown on the endpoint's page and can be rolled.

Every delivery is JSON with id, type, api_version, created_at and data. The id is the same for every endpoint and every retry: process each id once. Answer 2xx within 10 seconds; anything else is retried with backoff for about two hours, and an endpoint that keeps failing is disabled automatically. Each delivery is logged with the HTTP code your server returned and can be sent again.

Verify X-SAMM-Signature-256: t=<unix>,v1=<hex>, an HMAC-SHA256 of t.body, before trusting a delivery:

import hmac, hashlib, time

def verify(raw: bytes, header: str, secret: bytes) -> bool:
    p = dict(x.split("=", 1) for x in header.split(","))
    if abs(time.time() - int(p["t"])) > 300:      # replay window
        return False
    mac = hmac.new(secret, p["t"].encode() + b"." + raw,
                   hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, p["v1"])
EventWhen
customer.createdA user account was created
customer.updatedA user account was updated
customer.renewedA plan was renewed (expiration extended)
customer.plan_changedA user moved to another plan
customer.expiredA user expired (expiration sweep)
customer.suspendedA user was suspended (by an admin or for not paying)
customer.restoredA suspended user was restored
customer.deletedA user account was deleted
limit.exhaustedA usage limit was exhausted (quota / daily / uptime / expiration)
invoice.createdAn invoice was created
invoice.updatedWhat an invoice owes changed (payment, discount, reversal, write-off)
invoice.paidAn invoice was marked paid
invoice.deletedAn invoice was deleted
payment.receivedA payment was received and posted (online, payment app)
payment.reversedA payment was voided or an invoice reopened
wallet.topupMoney was added to a user's prepaid wallet
addon.addedAn add-on was given to or bought by a user
session.startedA user session started (off unless enabled in settings)
session.stoppedA user session stopped (off unless enabled in settings)
alert.openedAn alert opened (router down, service down, rogue DHCP server, new crash)
alert.resolvedAn alert cleared on its own or was resolved
webhook.testManual test event (sent from the test button)
Same rules as the portal API mutations go through the same audited command queue and service layer as the admin portal — a reset or plan change via the API behaves exactly like one clicked in the UI, CoA and all.
The link to SAMM is locked Router-control tokens cannot touch the link between SAMM and the router itself — its logins, its API service, its RADIUS settings, SAMM's own security rules, or the address SAMM reaches it on. SAMM checks it can still log in after every change, and every change or script run is kept in the Admin Log.

Reference

Operating SAMM

Almost everything is done from the admin portal. This page is the shell reference for the rare times you need it.

Service management

# Restart all SAMM services
systemctl restart samm-api samm-radius samm-worker samm-notification samm-telegram

# Live logs for one service
journalctl -u samm-api    -f
journalctl -u samm-radius -f

# Validate the FreeRADIUS config after any change
freeradius -CX

# Port 8000 stuck after a crash (admin portal unreachable)
kill -9 $(lsof -ti:8000); systemctl restart samm-api

Admin CLI

For quick subscriber operations from the shell. Each command is queued to the audit log and applied on the next samm-radius tick — exactly like the UI actions.

CLI="sudo -u samm /opt/samm/venv/bin/python -m samm_radius.cli"

$CLI reset-quota      alice          # reset a limit counter
$CLI reset-daily      alice
$CLI reset-uptime     alice
$CLI reset-expiration alice
$CLI change-plan      alice home-50M # switch a subscriber's plan
$CLI encrypt-pw                       # encrypt a router API password for the DB

Configuration files

FileHolds
/etc/samm/samm.yamlThe database DSN, connection-pool sizes, log level
/etc/samm/api.envPortal session secrets and the password-recovery SMTP settings
/etc/samm/secret.keyThe encryption key for stored router API passwords

These files are preserved across upgrades and never overwritten by a re-run of the installer. Runtime tunables (loop cadences, daily-reset time, CoA ports) live in Settings instead, and apply with no restart.

Updating SAMM

Either let SAMM update itself from System → License, or re-run the installer — see Installation → Upgrading. Both paths re-apply migrations and restart services; your config and data are untouched.

Backup & recovery

Use Tools → Backup & Restore for a full database snapshot before any major change. To rebuild on a fresh host, install SAMM and then restore the backup.

Maintenance tools (external)

Some maintenance jobs are destructive enough that they do not belong in the admin panel, where a stray click could destroy a live business. SAMM keeps them as standalone, root-only scripts you download and run deliberately from the shell — never as a button. They live in the public distribution repository under tools/.

Reset a locked-out admin password

Locked out of the admin panel? Set a new password for a superadmin account straight in the database — no working login needed. It also re-enables the account if it was disabled, and touches nothing else.

curl -fsSL -o samm-reset-admin-password.sh \
  https://raw.githubusercontent.com/mhdhaidarah/samm/main/tools/samm-reset-admin-password.sh

sudo bash samm-reset-admin-password.sh --list   # list the superadmin accounts
sudo bash samm-reset-admin-password.sh          # reset (prompts for the new password, twice)

Run it as root on the SAMM server. If there are several superadmins, pass --user <name> to choose one.

Reset the books (wipe financial data)

Clears every financial transaction so an ISP can start its accounting from zero, while leaving all subscriber and AAA data completely intact. Useful when taking over an install, or after a trial/testing period, when the books are full of data the operator wants gone but the customer base must stay exactly as it is.

Danger — irreversible data loss This permanently destroys all invoices, payments, receipts, wallet balances and ledger history. There is no undo. The only way back is a database backup. Never run it on a production install you have not backed up and verified first.

Removed: invoices and their line items, the double-entry ledger (payments, receipts, adjustments, wallet top-ups and withdrawals), online-payment transactions, expenses, fixed assets and the accounting activity log. Invoice numbering resets, so the next invoice starts at #1.

Kept: every subscriber, plan, speed window, limit, usage counter, plan history, hotspot card, router, session and RADIUS accounting record — plus your accounting configuration (chart of accounts, cash accounts, tax groups, payment gateways). Cash, wallet and receivable balances are derived from the ledger, so they simply read zero afterwards.

Download it, read it, then run it. Always do a dry run first:

curl -fsSL -o samm-wipe-financials.sh \
  https://raw.githubusercontent.com/mhdhaidarah/samm/main/tools/samm-wipe-financials.sh

sudo bash samm-wipe-financials.sh --dry-run   # show what would be deleted, change nothing
sudo bash samm-wipe-financials.sh             # do it
Do not pipe it straight into a shell Never run this as curl … | sudo bash. For a script that destroys data you want to read it first, and a truncated download must not be able to execute half a wipe. Download, inspect, then run.

The script refuses to run as a non-root user, prints exactly what it is about to delete, then asks you to type YES to confirm you hold a verified backup and WIPE to proceed. It offers to take its own database dump first (into /var/backups/samm/) and aborts if that dump fails. The wipe runs as a single all-or-nothing transaction, and RADIUS is deliberately left running throughout, so subscribers stay online while the books are cleared.

Reference

FAQ & troubleshooting

What operating systems does SAMM support?

Ubuntu 22.04 / 24.04 / 26.04 LTS and Debian 12 / 13. Server-grade Linux only — desktop variants aren't supported. The installer expects systemd, a fresh PostgreSQL install (one is set up for you), and root access.

Do I need an internet connection to run SAMM?

No. SAMM runs entirely on your own server and authenticates subscribers locally over RADIUS. The only outbound traffic is a periodic license heartbeat to the SecuryTik license server so your plan stays validated.

Can I run SAMM in the cloud, or does it need to be on-prem?

Either works. Most operators run on-prem next to their core routers; some run on a small cloud VM with a Cloudflare Zero Trust tunnel back. The only requirement is that the MikroTik routers can reach the SAMM server on the RADIUS ports (1812/1813 UDP) and that SAMM can reach the routers over the MikroTik API.

Do I have to restart FreeRADIUS when I add or remove a router?

No. SAMM resolves NAS clients dynamically from the database, so adding, editing or removing a router in MikroTik → NAS takes effect with no restart.

How fast does a plan change or counter reset take effect?

Admin actions are queued and applied by the samm-radius service on its next tick — within 30 seconds by default. If the subscriber is online, SAMM also sends a live CoA to refresh the session. Lower the samm-radius interval in System → Settings for tighter timing.

What happens to my data if a paid license lapses?

Nothing is ever deleted. A lapsed license steps down through warning, grace, a soft lockdown (RADIUS keeps authenticating for about a week) and finally a hard lockdown. Reactivating at any stage restarts every service with all data intact.

Is SAMM free? What does Pro add?

The Free tier is free forever and includes every feature. The paid plans don't unlock features — they raise the caps on AAA users and hotspot cards, and remove the limit on routers. See Licensing & tiers.

A subscriber can't authenticate — where do I start?

Check that the router's RADIUS shared secret matches the NAS record exactly, that the router is enabled for PPP / Hotspot RADIUS, and that the subscriber's account is Active and not expired. Watch journalctl -u samm-api -f and the FreeRADIUS log, and confirm the router can reach the SAMM host on UDP 1812/1813.

Need more help?

Email samm@securytik.com to report a bug or request a feature.