Oversight Docs

Overview

Oversight is a multi-tenant ISP management platform. It gives you a single dashboard for PPPoE wired subscribers, Hotspot WiFi sessions, M-Pesa billing, SMS messaging, and router infrastructure — all talking directly to your MikroTik devices via the RouterOS API.

Getting started

Follow these steps to go from sign-up to your first live subscriber.

1. 1

   Create an account

   Sign up at /auth/signup. Your first workspace is created automatically and you are assigned SUPER_ADMIN.

2. 2

   Connect a router

   In the Network section, register your MikroTik via WireGuard VPN (recommended) or a public IP. The router must be reachable before anything else works.

3. 3

   Choose your service

   PPPoE for wired subscribers, Hotspot for WiFi sessions, or both. Each has its own workspace created separately.

4. 4

   Create packages

   Define your bandwidth plans — each package maps to a MikroTik profile with a speed, price, and billing duration.

5. 5

   Configure M-Pesa

   Link your Safaricom Daraja credentials in the Payment settings. Without this, only manual/free activations work.

6. 6

   Add subscribers

   Create PPPoE users (provisioned to the router) or let Hotspot users self-onboard via the captive portal.

PPPoE management

The PPPoE module manages wired internet subscribers. Each subscriber is provisioned directly to your MikroTik as a PPP secret. Subscriptions are tied to M-Pesa payments — when a customer pays, their connection is enabled automatically.

Subscriber statuses

Every subscriber has one of three statuses. These are distinct — do not substitute one for another.

How billing works

1. 1

   Customer pays via M-Pesa PayBill

   The customer uses their assigned account number as the BillRefNumber. This is set per-subscriber in Oversight — it is not assumed to be their phone number.

2. 2

   Balance is credited

   The payment is credited to the subscriber's balance.

3. 3

   Subscription is created or extended

   The system creates a new subscription or extends an active one based on the package price and available balance.

4. 4

   PPPoE secret is enabled

   The subscriber's PPPoE secret is enabled on MikroTik — they can connect immediately.

5. 5

   Automatic expiry

   When the subscription end_at passes, a background job disables the secret and the subscriber loses access until they pay again.

Subscription policies

• Rolling expiry — subscription ends exactly N days after payment
• Fixed-time expiry — subscription always ends at a specific time of day (e.g. midnight)
• Partial subscriptions — allow subscribers with less than a full package price to receive proportional days
• Minimum days — prevent tiny partial subscriptions below a configurable threshold

Packages & burst

A package maps to a bandwidth profile already configured on your MikroTik. The package gives it a price, duration, and display name.

• Profile name must exist on the router before creating the package in Oversight
• Burst lets a subscriber briefly exceed their base speed — configured per package under Packages → Burst
• Burst limit: the peak speed allowed. Burst threshold: average usage must be below this to trigger burst. Burst time: how long the peak can be sustained.
• Use burst for a premium feel on standard-tier plans — it is time-limited, not a permanent upgrade

Sync & reconciliation

Over time your database and MikroTik router will drift apart. The Sync page (Users → Sync) detects and resolves four types of mismatch:

Admin actions

• Create or extend a subscription from the subscriber's Subscriptions tab
• Adjust end_at of an active subscription without affecting billing history
• Deactivate a subscription early — disconnects the subscriber immediately
• Manually enable, disable, or expire a subscriber from the Users page
• Soft-delete or hard-delete a subscriber record

Hotspot WiFi

The Hotspot module deploys a branded captive portal on MikroTik routers and handles session-based billing. Customers pay per session using M-Pesa STK Push and are connected automatically — no manual work needed.

Captive portal flow

1. 1

   Customer connects to your WiFi

   MikroTik intercepts the first HTTP request and redirects them to your branded Oversight portal page.

2. 2

   Customer selects a package

   Available packages are shown with price, speed, and duration. Free plans can also be offered.

3. 3

   Payment via M-Pesa STK Push

   A payment prompt appears on the customer's phone. They enter their M-Pesa PIN to complete the transaction.

4. 4

   Session is activated

   On payment confirmation, Oversight creates a throwaway username/password, provisions the MikroTik hotspot user, and logs the customer in automatically.

5. 5

   Session expires

   A background job runs every 30 minutes. When a session's duration window passes, the hotspot user is removed from MikroTik and access ends.

Packages

Hotspot packages define what each WiFi plan offers. When you create or update a package, it is automatically synced to every setup-complete router in your workspace.

• Rate limit — written as "upload/download" (e.g. "2M/10M"). Becomes the MikroTik user profile speed cap.
• Duration — session length in minutes. The hard cutoff after which the user is disconnected.
• Idle timeout — disconnects inactive users early, freeing slots for new customers.
• Shared users — how many devices can share one session purchase (default 1).
• Profile sync — package changes propagate to all routers automatically. No manual MikroTik edits needed.

Setup wizard

A router must complete the 6-step wizard before it can accept sessions. An incomplete wizard means no portal on that router.

• Step 1 — Inspect: reads existing interfaces, pools, and profiles from the router over SSH
• Step 2 — Bridge: creates a network bridge for the hotspot interface
• Step 3 — Pool: assigns an IP address pool (e.g. 10.5.0.2–10.5.0.254)
• Step 4 — Hotspot Profile: configures the captive portal server profile
• Step 5 — Hotspot Server: ties bridge + pool + profile together
• Step 6 — Push login page: generates a branded login.html and uploads it to the router via SFTP

Billing & payments

Payment channels

A payment channel is a configured Safaricom PayBill shortcode. One shortcode can serve both a PPPoE tenant and a Hotspot tenant simultaneously — the system routes each incoming payment to the correct service.

Required Daraja credentials

• Shortcode — your M-Pesa PayBill number
• Consumer Key and Consumer Secret — from your Daraja app
• STK Passkey — for STK Push prompts (Hotspot)
• C2B Validation and Confirmation URLs — must be registered with Safaricom

STK Push vs C2B PayBill

Payment routing logic

When a C2B payment arrives on a shared channel, the system resolves which service it belongs to in order:

1. Check if the payer's phone (MSISDN) matches a pending Hotspot STK request on this channel → Hotspot payment
2. Check if the BillRefNumber matches a pending Hotspot manual reference → Hotspot payment
3. Look up the BillRefNumber as a PPPoE account number → PPPoE payment
4. If none match, the payment is logged but not routed

Messaging & SMS

The Messaging module lets you send SMS to subscribers — manually or automatically. It connects to your SMS provider (Africa's Talking, etc.) and powers subscription expiry reminders that run without any manual work.

Setup

Go to Messaging → Setup and select your provider. Enter the required credentials (API key, username, sender ID). Without a configured channel, no SMS can go out.

• Each workspace (PPPoE or Hotspot) has its own SMS channel configuration
• Check your provider balance from the Setup page at any time
• Delivery reports are supported for providers that offer webhooks — configure the callback URL in your provider dashboard

Expiry reminders

Configure trigger rules under Messaging → Reminders. The system runs every hour and sends to all matching subscribers automatically.

Template variables

Use these placeholders in your reminder message templates — they are filled in per-subscriber at send time:

Compose & manual sends

• Send to individual subscribers by name or phone search
• Bulk-send to a filtered group: all active, all expired, or all subscribers
• GSM-7 encoding: 160 characters per SMS part. Unicode (emoji, Arabic, etc.): 70 characters per part — switching encoding costs more
• Live character and part count shown before sending — check cost before dispatching large batches
• All manual sends are logged in History alongside automated reminder sends

History & delivery statuses

Network & routers

Oversight talks to MikroTik routers via the RouterOS API. Two connectivity modes are supported — choose based on whether your router has a public IP and how much exposure you are comfortable with.

WireGuard VPN (recommended)

Your MikroTik connects outward through an encrypted WireGuard tunnel. The router does not need a public IP and the RouterOS API is never exposed to the internet.

• Works behind NAT, CGNAT, or dynamic IPs
• Traffic stays end-to-end encrypted
• No open ports on the router side

WireGuard infrastructure is organised in three levels:

Public IP (direct)

If your router has a static public IP, you can connect directly without a VPN tunnel. Register the IP, API port, and credentials under Network → Public IP.

• Simpler setup — no tunnel configuration needed
• Register multiple IPs per server for failover (system tries them in order)
• Requires API service enabled on MikroTik: IP → Services → api (port 8728) or api-ssl (port 8729)

Enabling the RouterOS API

1. 1

   Open WebFig or Winbox

   Navigate to IP → Services.

2. 2

   Enable the api service

   Set port to 8728 (or custom). Ensure "Available From" is not blocking the Oversight server.

3. 3

   For Hotspot SSH push

   Also enable the ssh service (port 22). The wizard uses SFTP to upload login.html to the router.

4. 4

   For router backups

   Both api and ssh must be enabled. Use the "Check Services" button in Backups to verify both are on before configuring a backup schedule.

Router backups

Configure a daily backup for any connected router under Network → Backups. The system pulls a binary .backup file from the router at the scheduled time each day.

• Supports both Public IP and WireGuard-connected routers
• 12-day retention — files older than 12 days are deleted automatically
• Manual trigger available at any time — useful after making config changes
• Files can be downloaded individually at any time from the Backups page
• Backup requires both API (8728) and SSH (22) enabled on the router

Router health monitoring

The Routers page shows live metrics for every connected device. Check here first when a subscriber reports connectivity issues.

• CPU load — sustained above 80% outside peak hours usually signals a routing policy issue or incoming attack
• Memory usage — high memory (>90%) can cause slow API responses or dropped connections
• Disk usage — RouterOS logs accumulate over time; clear if disk is near full
• Interface traffic — select any interface to see live RX/TX bytes per second
• RouterBoard info — shows hardware model, firmware version, and uptime. Unexpected recent reboots are worth investigating

Users & roles

Oversight uses role-based access control per workspace. PPPoE and Hotspot have separate role sets — the same user can have different roles in each.

PPPoE roles

Hotspot roles

Inviting team members

1. 1

   New member registers an Oversight account

   They must sign up at /auth/signup before they can be added to any workspace.

2. 2

   SUPER_ADMIN opens Roles page

   Go to PPPoE → Roles or Hotspot → Roles and click "Add user".

3. 3

   Select the user and assign a role

   Search by email or username. Choose the appropriate role. Access takes effect immediately.

Multi-tenant context switching

A single Oversight account can belong to multiple workspaces. Use the tenant selector in the sidebar to switch context — all pages show data for the currently selected workspace. Your selected workspace is preserved across sessions.

FAQ