Sova documentation

Getting started

How Sova works

1. The hub owns the plan. Every address in the fleet is derived from a site number and a network type, so nothing is typed twice and two sites can never overlap.
2. Branches dial out. Each branch router opens a WireGuard tunnel to the hub (UDP, its own port per site) and, as backup, an L2TP/IPsec tunnel. Outbound connections pass any NAT.
3. OSPF shares the routes. The branch advertises its own networks; the hub learns them and advertises the whole fleet back. A new branch is learned by every other branch automatically.
4. The hub is the checkpoint. All site-to-site and remote traffic passes through the hub, so policies, remote-user access and route validation are enforced in one place — a branch cannot widen its own access or claim another branch's addresses.
5. Local internet stays local. Only company traffic crosses the tunnels. Branches keep using their own internet; remote users choose split or full tunnel.

Getting started

Requirements

Hub

• A VPS with Ubuntu 24.04 or 26.04 (amd64), freshly installed, root access.
• A public IPv4 address on the VPS (not behind NAT) — branches and users dial it.
• 1 vCPU / 1 GB RAM for up to ~10 sites; 2 vCPU / 2 GB for dozens of sites and users; 10 GB disk.
• If your provider has an external firewall, allow inbound: TCP 80 (panel), UDP 51001–51254 (site N uses 51000+N), UDP 51820 (remote users), UDP 500, 4500 (IPsec) and your SSH port. Sova configures the VPS firewall itself.

Branches

• MikroTik with RouterOS 7 (any model, CHR included) and working internet.
• A free port for each network you want Sova to build (see Creating sites).
• The branch must not already use addresses inside its future block 10.N.0.0/16 or 172.31.0.0/16.

Remote users

• WireGuard app (Windows, macOS, Linux, Android, iOS), or the L2TP/IPsec client built into Windows, macOS, iOS and Android.

Getting started

Installation

On the fresh VPS, as root:

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

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/sova-install.sh | sudo bash

The bootstrap downloads the latest signed release from GitHub (github.com/mhdhaidarah/sova) — or from the dl.securytik.com mirror when GitHub is blocked — verifies its checksum and runs the installer inside it. The installer:

1. installs WireGuard, FRR (OSPF), strongSwan + xl2tpd (L2TP/IPsec), nftables, Unbound (DNS), PostgreSQL and nginx;
2. creates the database and the sova service account, and the Sova services;
3. detects the public IP and serves the panel on it (http://<server-ip>/admin/);
4. prints the panel address and a random first password.

Re-running the same command on an existing hub upgrades it in place and keeps every setting and site. The full log is in /var/log/sova-install.log.

Services it installs

Getting started

First login

The first password is also stored in /etc/sova/first-admin-password (root only). For HTTPS on your own domain, use Cloudflare Tunnel. After signing in:

1. change the password under Profile (top right) and add your email for password recovery;
2. check System → Settings → Hub — the public address must be what branches can reach;
3. activate the install with your SecuryTik account under System → License — until then only that page opens.

Getting started

Hub settings

System → Settings:

The page also shows the hub's WireGuard public key, the port plan and the result of the last configuration apply.

Building the network

Address plan

Example: with type Servers = 1 and Printers = 3, branch 2's file server lives in 10.2.1.0/24 and branch 5's printers in 10.5.3.0/24. The hub infrastructure range is deliberately outside 10.0.0.0/8 because many ISPs and home routers use 10.0.x.x on the WAN side.

Existing branch LANs are re-addressed into the site's block. If a branch must keep an old LAN for a while, leave it on its port and let Sova build the new networks on other ports; move devices over, then retire the old LAN.

Building the network

Network types

Network → Network types. A type fixes the third octet across the whole fleet. Sova ships with Servers (1), Users (2), Printers (3), Cameras (4), Voice (5) and Guests (6); add your own (1–254) with a name, a short name (used in DNS names) and a colour.

Because a type means the same octet everywhere, one policy or one remote-user rule can say "printers at every site" instead of listing addresses. A type in use by a site cannot be deleted.

Building the network

Creating sites

1. Network → Sites → + Site. Enter the name, keep or change the site number (it becomes the second octet), the management port (the port you manage the router from — Sova never builds a network on it), and whether to add the L2TP/IPsec backup and let the Manager control the router.
2. On the site page, add networks: pick a type, the physical port (e.g. ether2) and the DHCP range. One port per network — no VLANs needed. The port is taken out of any bridge.
3. Copy the RouterOS script or press Make a one-line install link and paste the one-liner into the router (see The branch script).

The site page shows the live state: WireGuard and L2TP up/down, which path OSPF is using, latency, loss, the routes the branch advertises (and any the hub rejected) and a 24-hour latency chart.

Rotate keys issues a new WireGuard key and L2TP password (the branch goes offline until the new script is pasted). Delete site closes its tunnels and removes its routes everywhere.

Changing a site later

On the site page: Edit site (name, enabled, L2TP backup, managed, notes), + Network, and the ⋮ / right-click menu on each network to change its port or DHCP range or remove it. The Sites list itself has row selection with bulk enable / disable / delete, a column chooser, search, filters and export.

Building the network

The branch script

Each site shows one command. Paste it into the router's terminal (WinBox → New Terminal, or SSH):

/tool fetch url="http://<hub>/s/<token>.rsc" dst-path=sova.rsc; :delay 2s; /import sova.rsc; /file remove sova.rsc

The link works once, for 24 hours, and only for that site; New link on the site page makes another. The script:

• checks first — it stops without changing anything if the router already uses the site's block or 172.31.0.0/16, and warns about other 10.x addresses;
• builds the networks (address, pool, DHCP server with the hub as DNS);
• creates the WireGuard interface and peer, the L2TP/IPsec client, OSPF with import/export filters;
• adds firewall rules that accept fleet traffic for this site's block and skip NAT for it;
• adds the Manager login (usable only from the hub) when the site is managed;
• turns on the NTP client (time.cloudflare.com, pool.ntp.org), so the router's clock is right;
• never touches the WAN, the default route or anything not tagged SOVA.

Paste it again at any time — after adding a network, rotating keys or changing the hub address. It removes its own SOVA entries and re-creates them. To remove Sova from a router, delete the objects whose comment starts with SOVA.

Apply to router

For a managed site, Apply to router on the site page sends the current script over the tunnel: the router downloads it from the hub and imports it in the background. The tunnel blinks for a few seconds. Paste the script by hand once first, so the Manager login exists.

Building the network

Routing & failover

• OSPF runs on every tunnel (hello 5 s, dead 20 s). WireGuard has cost 10, L2TP cost 100, so WireGuard is always preferred.
• Failover: if WireGuard stops (blocked UDP, ISP issue), traffic moves to L2TP/IPsec within about 20 seconds and returns automatically. The dashboard and alerts show when a site is on the backup path.
• Route checks: the hub installs a branch's routes only when they fall inside that branch's own block and arrive over its own tunnels. Anything else is rejected and raises an advertises foreign routes alert — a misconfigured branch cannot hijack another branch's traffic.
• The hub advertises summaries of the whole fleet, so every branch always sends company traffic to the hub.

Network → Routes (under Overview) lists what each site advertises, what was rejected and the hub's OSPF neighbours.

Networks made on the router

Each site has a Share networks made on the router toggle (on by default). On: any interface the branch admin adds by hand inside the site's block is announced to every site. Off: only the networks Sova built are shared. Networks outside the site's block are never shared — they would clash between branches; give such an interface an address in the site's block instead.

Building the network

Remote users

Remote Access → Remote users → + Remote user.

New key & password invalidates the old profile. Disabling or deleting a user disconnects them immediately.

Groups (Sales, IT, Contractors…) gather remote users so one policy covers them all: create them under Remote users → Groups, tick users and choose Set group. A policy can also name one single remote user.

Building the network

Connecting clients

WireGuard (recommended)

Install the official WireGuard app, then scan the QR code on the user's page (phones) or import the downloaded .conf (computers). Works from any network, including behind other NATs.

L2TP/IPsec (built in)

• Server: the hub's public address · Type: L2TP/IPsec with pre-shared key · the key, username and password from the user's page.
• Windows behind NAT needs, once, the registry value HKLM\SYSTEM\CurrentControlSet\Services\PolicyAgent\AssumeUDPEncapsulationContextOnSendRule = 2 (DWORD) and a reboot.
• Corporate profile on Windows: untick "Use default gateway on remote network" and add routes to 10.0.0.0/8 and 172.31.0.0/16 via the VPN.
• Two L2TP/IPsec users behind the same public IP interfere with each other — give them WireGuard.

Remote users get the hub (172.31.0.1) as DNS, so internal names work.

Handing out the settings

From the Remote users list (⋮ or right-click) or the user's page: Copy WireGuard config, Export WireGuard (.conf), Copy L2TP details, Export L2TP details (.txt).

Building the network

Policies

By default every site reaches every site. Network → Policies adds allow/deny rules between any networks of the fleet, enforced on the hub:

• From / To: any network inside the fleet — a site block, one network, all remote users (10.255.0.0/16)…
• Protocol and port (e.g. TCP 445), and whether the rule applies in both directions.
• Order: rules are checked top to bottom; the first match wins. A deny also cuts connections that are already open.

Example: deny 10.0.0.0/8 → cameras 10.1.4.0/24, then allow the security office 10.2.2.0/24 → cameras above it. Remote users are governed by their own access rules; policies apply on top.

Several sources and destinations

In the rule pop-up, choose a kind (whole fleet, site, site network, remote users, IP / network), then Add to the list to put several of them on the same side of one rule.

Blocking apps and websites

Choose App / website as the destination and tick the apps (TikTok, Instagram, games, streaming…). Branch internet does not pass through the hub, so these rules are pushed to the source sites' routers — managed sites only. Sova switches the apps on in each router's Website & app filter and adds drop rules tagged SovaPolicy:. The same blocks can be made from a router's Websites & Apps tab in the Manager (Blocked for networks). Use Push app rules to routers after re-pasting a script or adding a site.

Building the network

Internal DNS

The hub answers for the internal zone (Settings) on 172.31.0.1 and forwards everything else to public DNS. Branch DHCP and remote users use it automatically. Names created for you:

Add your own under Network → DNS, e.g. erp.hq → 10.1.1.10 becomes erp.hq.corp.

Operating

Dashboard

The dashboard is made of blocks you arrange: drag a block by its header, resize it from the corner, remove it with ×, add more with Add block and save the arrangement — or save several named dashboards, which appear under Dashboard in the menu. The default top row is a chart of connected sites and Remote Access users online over time, beside System Health (version, CPU and RAM with history, disk, uptime, services, last monitor pass, licence, last hub apply). Other blocks: open alerts, tunnel latency & loss, tunnel traffic, sites, routes, remote users, managed devices, device health and recent admin actions. Charts pick their sites and time window from their own header.

Operating

Network map & tools

Network → Network map draws the fleet as it is right now: the Internet, the hub, every site with its live tunnel (WireGuard, L2TP backup or down), its transit addresses and networks, and Remote Access. Drag boxes to arrange it — the arrangement is remembered — and save arrangements as bookmarks. Layers switch interfaces, IP addresses, networks, CPU and the traffic flow on and off. Right-click a site to open it, ping or traceroute it, or manage its router.

Tools → Network runs ping, traceroute and DNS lookup on the hub or on any managed branch router: a target that answers from the hub but not from a branch points at that branch's path.

Operating

Monitoring & alerts

Every 30 seconds the hub checks each tunnel (handshake, OSPF neighbour, ping), each remote user and each managed device, and keeps 30 days of history (Overview → Monitoring).

Alerts resolve by themselves and are sent (opened and resolved) to Telegram, email and WhatsApp as configured in Settings. The bell at the top of every page shows what needs attention.

Handling alerts

Overview → Alerts: open alerts are under Needs attention. I am on it moves one to Being handled (still open, no longer counted in the bell); Quiet 1h / Quiet a day hide it for a while. The history below is searchable and exportable.

Notification center

System → Notifications: set up Telegram, email and WhatsApp Cloud API under Channels, choose which events go where under Admin alerts, and see every message sent or failed in the Outbox.

Operating

Managing branch routers

Every site page has two tabs: Site (addresses, tunnels, script) and Manage (the router itself, controlled through the tunnel). For a site Sova does not manage yet, the Manage tab offers Manage this router: paste the install command once, and from then on changes deploy over the tunnel. Sites → All routers lists every router at once for bulk actions, and routers added by address. On each router:

• Overview: model, RouterOS version, CPU, memory, uptime, interfaces with traffic, health history.
• General: identity, time zone, NTP and DNS servers, reboot.
• Website & app filter: block websites and apps by category (see next topic).
• Update: check, download and install RouterOS updates.
• Tools: ping and traceroute from the router, ping from the hub.

Bulk actions: tick several devices and set the time zone, NTP or DNS servers, check or install updates, take a backup, reboot or run a ping — with a result per device.

The router login the branch script creates (sova-mgr) accepts connections only from the hub's tunnel range.

Traffic history

The router's Overview tab shows Interface traffic (download / upload per interface) and App traffic (per app and website, with totals) for windows from 10 minutes to 7 days. Samples are taken every minute and kept 30 days. App traffic counts the apps switched on in Websites & Apps.

Live changes. On a managed router, saving a network (port, DHCP, range), a policy or the hub's DNS servers updates the router at once, record by record over its API: the script is not re-imported and the tunnel never drops. Policies between two networks of the same site — traffic that never reaches the hub — are enforced on that site's router, in the panel's order. The site page shows the last router sync and a Sync now button, and the hub re-checks every managed router every 10 minutes.

Operating

Website & app filter

On a device's Website & app filter tab, tick the apps and categories to block (social networks, video, games, messaging…). Sova pushes DNS-based blocking to the router from SecuryTik's maintained catalogue and keeps it updated when you press Update. Its rules are tagged separately, so re-pasting the branch script does not remove them; Remove takes them all off.

Operating

Search, filters & export

Sites, remote users, devices, alerts and the audit log share the same list tools: type to search, add filters from the menu, group by any field, build custom rules (e.g. latency above 80 ms), sort by clicking a column, save a search as a favourite (private or shared) and export to CSV or Excel. The search button at the top of every page (Ctrl K) finds sites, users, DNS names and pages.

Operating

Admins & roles

System → Admins adds administrators. A role sets, per area (sites, remote access, policies, DNS, monitoring, Manager, settings…), whether the admin cannot see it, can view it or can edit it. Sova ships with Super Admin (everything), Manager (runs the network) and Monitor (read-only); you can create your own. Only a Super Admin manages admins, roles and API tokens.

Branches. Admins are arranged in a tree. A branch owns its sites and remote users: its admins see and manage only those (and the branches below it), while admins whose role sees everything see the whole hub and choose the branch when they create or edit a site or a remote user.

Forgot password: the sign-in page sends a one-time code to the admin's email (configure SMTP in /etc/sova/smtp.env).

Each admin picks their own panel language and theme under Profile. A superadmin can edit any translation under System → Translations (applied live), add a language, or export a language to Excel and import it back.

Operating

Reset admin password

Locked out and no email recovery? Run the standalone reset tool on the hub, as root. It sets a new password for a Super Admin account straight in the database and re-enables the account — no working login needed, and no site, tunnel or user data is touched.

curl -fsSL -o sova-reset-admin-password.sh \
  https://raw.githubusercontent.com/mhdhaidarah/sova/main/tools/sova-reset-admin-password.sh
sudo bash sova-reset-admin-password.sh --list   # list the superadmin accounts
sudo bash sova-reset-admin-password.sh          # reset (asks for the new password twice)

With several Super Admins, pick one with --user NAME. The password is typed hidden, never on the command line, and stored hashed exactly like the panel does. The tool also ships inside every install at /opt/sova/tools/.

Operating

Audit log

System → Audit Log records every change with who made it, when, from which address and what changed — from the panel and from the API — plus sign-ins and failed sign-ins.

Operating

Backup & restore

Tools → Backup & Restore takes a full backup of Sova's database (sites, keys, users, policies, settings, admins), schedules a daily automatic backup with retention, downloads and uploads backups, and restores one. After a restore the hub re-applies itself within seconds.

Moving to a new VPS: install Sova on the new server, copy /etc/sova/secret.key from the old one (the keys in the backup are encrypted with it), upload and restore the backup, then point the public address (Settings) at the new server and re-paste the branch scripts.

Operating

Updates

Sova checks for a new release every day. System → Update shows the installed version, what is new and the release history; Apply update downloads the release, verifies SecuryTik's signature and checksum, backs up the current version, installs, migrates the database and restarts the services. Tunnels keep running during an update. Unsigned or tampered releases are refused.

Operating

Licensing & plans

Each install is licensed on its own, by the number of sites and remote users.

Yearly billing is 10 × the monthly price (Unlimited: 2,000 USDT a year). System → License: sign in with your SecuryTik account or press Link this device and approve the code on your dashboard. Request a plan from the same page — every requested plan is approved for one month free — then pay in USDT or USDC on the dashboard. The licence is signed and verified offline: the hub keeps working through an internet outage, warns before a plan ends and gives a grace period before new sites and users are limited. When the grace period ends without renewal the hub locks and its tunnels stop until the licence is renewed.

Activation is required. A new hub opens only System → License until it is registered with a SecuryTik account; the Free plan starts at registration.

Operating

Cloudflare Tunnel

To reach the panel on your own domain (e.g. vpn.company.com):

1. In Cloudflare Zero Trust → Networks → Tunnels, create a tunnel and copy its token.
2. In Sova, System → Cloudflare Tunnel: paste the token and save — Sova installs and runs the connector.
3. In Cloudflare, add a public hostname on the tunnel pointing to http://localhost:80.

Only the panel goes through Cloudflare; the VPN tunnels always connect directly to the hub's public address.

Reference

REST API

System → API → New token (Super Admin). Pick the scopes the token needs — sites, ra, policies, dns, stats, devices, audit, each read or write — an optional expiry and a rate limit. The secret is shown once.

curl -H "Authorization: Bearer sova_…" http://<hub>/api/v1/sites

The interactive reference with every field is at http://<hub>/api/v1/docs. Every write is recorded in the audit log; writes are refused while the licence is locked.

Reference

Webhooks

System → API → Webhooks: add an https URL and the events to send — site.created, site.updated, site.deleted, ra.created, ra.updated, ra.deleted, alert.opened, alert.resolved. Each delivery is a JSON POST signed with the endpoint's secret:

X-Sova-Event: alert.opened
X-Sova-Signature: sha256=<HMAC-SHA256 of the raw body>

Failed deliveries are retried with back-off; an endpoint that keeps failing is disabled. Use the test button to try an endpoint.

Reference

Security model

• The hub firewall allows only the panel, SSH and the VPN ports; everything between sites passes the hub's policy chain.
• Private keys and passwords are encrypted at rest with the install's own key (/etc/sova/secret.key); a database dump alone reveals nothing.
• The panel process has no network privileges; a separate root agent applies validated configuration.
• Branch scripts contain the branch's keys — install links expire after 24 hours; rotate keys if a script leaks.
• Updates and licences are signed by SecuryTik and verified offline.

Reference

Troubleshooting

Logs: journalctl -u sova-agent -u sova-monitor -u sova-api. Last configuration apply: System → Settings.

Reference

FAQ

Do branches need a public IP?

No. Branches dial out to the hub; only the hub needs a public IP.

Does branch internet go through the hub?

No. Only company traffic crosses the tunnels. Remote users on Full passthrough are the only ones whose internet goes through the hub.

Can I add a branch later?

Yes — create the site and paste its script. The other branches learn it automatically.

Which routers are supported?

MikroTik RouterOS 7 for branches. Remote users on any device with WireGuard or L2TP/IPsec.

What happens if the hub goes down?

Branches keep their local networks and internet; site-to-site traffic resumes when the hub is back. Keep backups off the VPS to rebuild quickly.

Need more help?

Email [email protected].