Quick Start Guide

Follow these steps to get your ISP up and running on MTBS ISP Cloud from zero to fully operational.

Step 1 — Tenant Account Setup

Step 2 — Add Your Infrastructure

Step 3 — Provision Your First ONU

Step 4 — Set Up Your Team

Logging In

Access MTBS ISP Cloud at isp.mtbs.cloud/login from any modern web browser.

Login Process

1. Navigate to isp.mtbs.cloud/login
2. Enter your Email Address and Password
3. Click Sign In
4. You will be redirected to the Dashboard

Forgot Password

Click the "Forgot your password? Reset it here" link on the login page. Enter your email address and check your inbox for a reset link.

Security Notes

• All connections use HTTPS — your credentials are always encrypted in transit
• Passwords are hashed with bcrypt — even database admins cannot read them
• The web UI uses CSRF tokens on every form to prevent cross-site request forgery
• The API uses JWT tokens — access tokens expire in 15 minutes, refresh tokens in 7 days

Dashboard

The dashboard is your main operational hub. It shows real-time KPIs, active alarms, and a summary of your network health at a glance.

Dashboard Sections

NOC Dashboard

Navigate to /dashboard/noc or click NOC View in the dashboard header. This is a full-screen, auto-refreshing display designed for wall-mounted TV monitors in your NOC.

OLT Management

OLTs (Optical Line Terminals) are the central devices in your fiber network. MTBS ISP Cloud supports ZTE, Huawei, and Fiberhome OLTs via SNMP and SSH.

Adding an OLT

1. Go to OLTs in the sidebar
2. Click Add OLT
3. Fill in the form:
• Name: A descriptive name (e.g., "OLT-01-Karachi")
• Vendor: Select ZTE, Huawei, or Fiberhome
• Model: Select the specific model (e.g., C300, MA5800)
• Management IP: The OLT's reachable IP address
• SNMP Community: Read-only SNMP community string
• SSH Username / Password: For configuration push operations
• Site: Assign to a physical site
4. Click Save & Sync to save and immediately pull card/port data

OLT Detail Page

Click View on any OLT to see its detail page with tabs:

Syncing an OLT

Click Sync on the OLT list or the Sync Now button on the detail page. This creates a background job that pulls the latest card, port, and ONU data from the device via SNMP. Watch the job progress on the Jobs page.

Required Permissions

olts.view to view OLTs   olts.manage to add, edit, sync, and delete OLTs

ONU Provisioning

ONUs (Optical Network Units) are the customer-premises devices. This section covers discovery, provisioning, and day-to-day management.

ONU Discovery

When a customer plugs in a new ONU, it appears on the PON port as a "rogue" (unprovisioned) ONU.

1. Click Discover on the ONU list page
2. Select the OLT and the PON Port to scan
3. Click Discover Rogue ONUs
4. Any unprovisioned ONUs appear in the list with status Discovered

Provisioning an ONU

Provisioning Form Fields

ONU Actions

• Reboot — Sends a reboot command to the ONU via the OLT. Takes effect in ~30 seconds.
• Suspend — Blocks the ONU's service without removing its configuration.
• Factory Reset — Resets the ONU to factory defaults and removes it from the OLT config.
• Edit — Change the customer name, profile, or VLAN assignment.

Required Permissions

onus.view to view ONUs   onus.manage to provision, reboot, suspend, and delete

Switch Management

The switch management module gives you complete visibility and control over your L2 and L3 switches via SNMP.

Switch Detail Tabs

Required Permissions

switches.view to view   switches.manage to add, edit, and control ports

Alarms & Monitoring

The alarm system continuously monitors your network and generates alerts when conditions breach configured thresholds.

Alarm Severity Levels

Alarm Workflow

Required Permissions

alarms.view to view   alarms.manage to acknowledge, assign, and resolve

Billing & Finance

The billing module manages your customers, service packages, invoices, and payments all in one place.

Billing Modules

Required Permissions

Only users with the Billing Manager role or ISP Admin role can access billing. The billing.view and billing.manage permissions control granular access within the module.

WireGuard VPN

The WireGuard module lets you manage VPN servers and peers directly from the web UI — useful for securing remote management access to your network equipment.

Adding a Peer

1. Enter a peer name (e.g., "field-eng-john") and allowed IP (e.g., 10.8.0.10/32)
2. Enter a peer name (e.g., "field-eng-john") and allowed IP (e.g., 10.8.0.10/32)
3. The system generates a key pair and creates the peer config automatically
4. Click Download Config or Show QR Code to get the WireGuard config for the client device
5. Import the config into the WireGuard app on the client (mobile, laptop, or router)

Required Permissions

wireguard.view to view servers and peers   wireguard.manage to add, edit, and remove peers

Sites & Devices

Sites are physical locations (data centres, exchange buildings, field cabinets). Devices are any network equipment at a site that doesn't have its own dedicated management module.

How to Use Sites

• Create sites first, then assign OLTs and switches to them when adding those devices
• Each site shows a summary of all equipment assigned to it
• Alarms are tagged with site information for quick geographic triage

Required Permissions

sites.view to view sites   devices.view to view devices   devices.manage to manage

Users & Roles

Every person who uses MTBS ISP Cloud needs their own user account. Each account has exactly one Role. The role determines what pages the user can see and what actions they can perform.

Creating a User

1. Go to Users → Add User in the sidebar
2. Enter the person's First Name, Last Name, and Email address
3. Set a temporary Password — the person should change it on first login
4. Select the appropriate Role from the dropdown (see table below)
5. Click Create User
6. Share the email and temporary password with the person through a secure channel (not plain email)

Understanding Roles

A role is a named group of permissions. When you assign a role to a user, they automatically get all the permissions that role includes.

MTBS Platform Roles (MTBS Staff Only)

ISP Tenant Roles (Your Team)

Permission Reference

Behind the scenes, every role contains a set of permission slugs — short codes that unlock specific features. You don't manage slugs directly — you manage roles — but understanding them helps when reading the docs.

Tenant Management

Tenants are the top-level organisational unit — each ISP customer of MTBS is a separate tenant. Tenant management is only available to Platform-level roles.

Creating a New Tenant

1. Log in as a Platform City Admin
2. Go to Tenants → Add Tenant
3. Enter the ISP name, contact email, and plan details
4. Click Create Tenant
5. Go to Tenants → Add Tenant

Tenant Isolation Guarantee

• All database queries are automatically scoped to the active tenant's ID
• There is no way for a user in Tenant A to access Tenant B's data through the web UI or API
• WireGuard peers are isolated per tenant
• Billing data is isolated per tenant

Job Queue

Long-running operations (ONU provisioning, OLT sync, bulk operations, report generation) run as background jobs so the web interface stays responsive. You can monitor all jobs from the Job Queue page.

Job Statuses

Retrying a Failed Job

Click on a Failed job to see the error detail. If the issue is transient (e.g., device temporarily unreachable), click Retry to re-queue the job. The system automatically retries jobs up to 3 times with exponential backoff before marking them as permanently failed.

Flutter Mobile App

The MTBS ISP Cloud mobile app for iOS and Android gives your field engineers and NOC staff full network management capability from anywhere. Built with Flutter for a native feel on both platforms.

App Screens

Session & Security

• JWT tokens are stored in Flutter Secure Storage (iOS Keychain / Android Keystore)
• Access tokens refresh automatically in the background — no re-login required
• If your session expires (e.g., device offline for 7+ days), you are redirected to the login screen
• Logout clears all tokens from secure storage

API — Authentication

All API requests (except login) require a valid JWT access token in the Authorization header.

Base URL

Login

Using the Access Token

Refresh Token

Get Current User

Change Password

Error Responses

API — OLT Endpoints

ONU Discovery & Provisioning

API — Other Endpoints

Switches

Alarms

WireGuard

Sites & Devices

Notifications

Jobs

OpenVPN

OpenVPN is a VPN (Virtual Private Network) technology that creates an encrypted tunnel between your team members' devices and your ISP management network. This allows field engineers, NOC staff, and administrators to securely access internal systems from anywhere.

OpenVPN Servers

An OpenVPN Server is the central endpoint your clients connect to. You will typically have one server per city or data centre.

Adding a Server

1. Click Add Server on the OpenVPN page
2. Fill in the form:
• Name — A descriptive label (e.g., "KHI-VPN-01")
• Public IP — The server's public internet IP address that clients will connect to
• Port — Typically 1194 (default) or 443 (to bypass firewalls)
• Protocol — UDP (faster) or TCP (more reliable through strict firewalls)
• VPN Subnet — The IP range for VPN clients (e.g., 10.200.0.0/24). Must not overlap with your management network.
• DNS Server — Optional internal DNS to push to clients (e.g., your management network DNS)
3. Click Save Server
4. The system generates the OpenVPN server configuration and CA certificate automatically

OpenVPN Clients

A "client" in OpenVPN terms is one device (or one person) that connects to the VPN server. You create a client config for each person or device that needs VPN access.

Adding a Client (Creating a VPN Config for a Staff Member)

1. Click Clients next to the appropriate server on the server list
2. Click Add Client
3. Enter a Client Name — use a descriptive slug (e.g., "field-eng-john", "noc-laptop-01"). No spaces.
4. Optionally enter a Static IP from the VPN subnet if you need the person to always get the same IP (useful for firewall rules)
5. Click Create Client
6. The system generates a unique certificate and builds the .ovpn configuration file automatically
7. Click Download to get the .ovpn file and send it to the staff member

Installing the Client Config (Staff Member's Steps)

• Windows / macOS / Linux: Install the free OpenVPN Community Client, import the .ovpn file, and connect
• iOS / Android: Install OpenVPN Connect from the App Store / Play Store, tap the + button, import the .ovpn file
• Linux CLI: sudo openvpn --config staff-member.ovpn

Server Health Page

Click Health next to any server to see real-time statistics: connected client count, bytes sent/received, uptime.

Revoking a Client (When Someone Leaves)

When a staff member leaves or a device is lost, click Revoke next to their client. This immediately adds their certificate to the CRL and they cannot reconnect.

Required Permissions

Use openvpn.view to view servers and clients   openvpn.manage to create servers, add/revoke clients

Security Dashboard

The Security Dashboard is a single page that gives you an instant overview of how secure your server is. It runs 12 automated checks and produces a security score.

You do not need to be a security expert to use this page. Each check has a plain-language explanation of what it is checking and what to do if it fails.

Understanding the Score

The 12 Security Checks — Explained Simply

Renewing Your SSL Certificate

SSL certificates expire every 90 days (when using Let's Encrypt, the most common free provider). The Security Dashboard shows the days remaining.

1. Click Renew SSL (only visible to users with security.manage permission)
2. A confirmation modal appears explaining that certbot will be run and Apache will need a manual reload
3. Click Proceed
4. The system runs sudo certbot renew on the server
5. After it completes, reload Apache: SSH in and run sudo systemctl reload apache2

Required Permissions

Use security.view to view the Security Dashboard and all 12 check results   security.manage to trigger SSL renewal

System & Health

The System section gives platform administrators (MTBS staff) visibility into the server's health and the ability to manage running services.

System Health Page

The System Health page shows the current status of the core infrastructure components that MTBS ISP Cloud depends on. Each component is checked automatically every few minutes.

Health Checks Explained

Managing Server Services

The Services sub-page lists the key Linux services that power the platform. From here you can Start, Stop, and Restart individual services.

• Apache needs restarting after a configuration change (e.g., SSL renewal)
• The OpenVPN service needs to be started after adding a new server
• The job worker process has stalled and needs restarting

API Keys

API Keys allow external systems (scripts, monitoring tools, third-party integrations) to authenticate with the MTBS ISP Cloud REST API without using a username and password.

Creating an API Key

1. Go to System → API Keys
2. Click Create API Key
3. Enter a Name for the key (e.g., "Zabbix Integration", "Billing Export Script")
4. Select the User account whose permissions the key will inherit
5. Optionally set an Expiry Date for the key
6. Click Generate
7. Copy the key immediately — it is only shown once and cannot be retrieved again

Required Permissions

system.health to view System Health, manage services, and manage API keys

Audit Logs

The Audit Log is a chronological record of every significant action taken in the system — who did it, what they did, when they did it, and from where.

Audit logs are essential for:

• Security investigations — If something was deleted or changed without authorisation, the audit log tells you who, what, and when
• Compliance — Many regulatory frameworks (ISO 27001, PCI-DSS, local telecom regulations) require that you keep records of who accessed what
• Troubleshooting — If a device was accidentally misconfigured, the audit log shows which user made the change
• Staff accountability — Knowing that actions are logged encourages responsible use of admin access

Understanding Each Column

Filtering the Audit Log

The audit log can be filtered by:

• Date range — view logs from a specific period
• User — see all actions performed by a specific person
• Action type — filter to only show DELETEs (useful for investigating accidental deletions)
• Resource type — e.g., show only ONU-related events

Exporting Logs

Click Export CSV to download the current filtered view as a CSV file. This is useful for submitting to compliance auditors or doing offline analysis.

Required Permissions

audit.view to view and export audit logs (read-only — no write permission exists by design)

By default this permission is granted to: Tenant Admin (ISP Admin), Platform City Admin, System Administrator, and DevOps SRE roles.