MikroTik RouterOS Hotspot Setup Guide — Captive Portal, Vouchers & Bandwidth Limits

The MikroTik RouterOS Hotspot server is the most powerful and flexible hotspot platform available at the price point of MikroTik hardware. Widely deployed by ISPs, hotel WiFi operators, campus network managers, and commercial hotspot businesses across Uganda and East Africa, it gives you granular per-subscriber control — login authentication, bandwidth limiting, session time quotas, data caps, voucher generation, and RADIUS integration — all built into RouterOS with no additional licensing fees.

This guide goes deeper than the basic setup covered in our MikroTik Hotspot Setup with Subscriber Billing guide — here we cover the advanced configuration that separates a professionally operated hotspot from a basic home network: captive portal customisation, structured voucher systems, per-tier bandwidth queue management, session control, and RADIUS billing integration. ISPs and hotspot operators managing 20+ subscribers should pair this configuration with our ISP Billing System to automate the subscriber and billing layer on top of this RouterOS foundation.

Recommended Hardware for RouterOS Hotspot in Uganda

All MikroTik RouterOS hotspot configurations in this guide apply to the following hardware available at NetEdge Supplies Uganda:

• Budget hotspot / small premises (up to 20 users): MikroTik hAP lite RB941-2nD — 32MB RAM, 4 ports, USB modem, RouterOS L4 at UGX 120,000. Sufficient for café, guesthouse, and small SOHO hotspot deployments.
• Mid-range hotspot / ISP CPE (20–50 users): MikroTik hAP RouterBOARD with PoE — 64MB RAM, 5 ports with PoE in/out at UGX 180,000. PoE out allows you to simultaneously power an outdoor AP from port 5.
• ISP CPE / distribution (50–200 subscribers): MikroTik RB951Ui-2HnD RouterBOARD — 128MB RAM, 5 ports, USB modem failover, PoE out at UGX 250,000. The most widely deployed ISP CPE router in Uganda.
• ISP edge/core router upstream of hotspot CPE: MikroTik hEX RB750Gr3 5-Port Gigabit Router — wired Gigabit routing, PPPoE termination, and upstream traffic management for multi-CPE ISP deployments.
• Wide-area hotspot sector coverage: MikroTik MANTBox 12s 2.4GHz Sector Integrated Antenna — outdoor sector AP for neighbourhood-scale or campus hotspot coverage, powered via the MikroTik RBGPOE Gigabit PoE Injector.
• Dual-band outdoor AP: MikroTik wAP ac RBwAPG-5HacT2HnD Dual-Band Outdoor AP — 2.4GHz + 5GHz outdoor access point for premium hotspot deployments requiring 5GHz capacity.

Understanding the RouterOS Hotspot Architecture

Before diving into configuration, it helps to understand how the RouterOS Hotspot server intercepts and manages traffic:

1. Client connects to the hotspot WiFi or LAN port (open network — no WPA password)
2. RouterOS DHCP server assigns an IP address from the hotspot pool
3. Client opens a browser — RouterOS intercepts the HTTP request via a transparent proxy and redirects to the captive portal login page
4. Client enters username and password (or voucher code)
5. RouterOS authenticates against the local user database or RADIUS server
6. On success, RouterOS adds the client’s IP to the hotspot IP binding and applies the User Profile (bandwidth limit, session timeout, data quota)
7. Client gets internet access within the limits of their profile — fully tracked per-session

This architecture gives you complete visibility and control over every subscriber session — a fundamental requirement for any commercial hotspot or ISP CPE operation.

Part 1 — Captive Portal Login Page Customisation

The default RouterOS Hotspot login page is functional but generic. Customising it reinforces your brand and builds trust with subscribers. RouterOS stores the hotspot HTML/CSS files in the router’s file system, accessible via Winbox Files or FTP.

Accessing the Hotspot Login Files

1. Open Winbox → connect to your MikroTik router
2. Go to Files → look for the hotspot folder
3. The key files are: login.html (main login page), alogin.html (after-login redirect), error.html (login error page), status.html (session status page), and logout.html
4. Drag these files to your desktop to edit, then drag them back to upload your changes

Key Customisations for Uganda ISPs

• Add your business logo: Upload your logo image to the hotspot folder and reference it in login.html via <img src="logo.png">
• Add your business name and contact: Display your ISP name, phone number, and payment instructions on the login page — essential for subscribers who need to pay for access
• Add package information: List your available bandwidth packages and prices directly on the login page so subscribers know what they’re getting before they log in
• Mobile-optimise the layout: Most subscribers in Uganda connect via smartphone — ensure the login page is responsive and loads cleanly on small screens. Use simple CSS with max-width: 400px; margin: auto; as a starting point.
• Add a payment link: Include a link to your payment page or our ISP Billing System so subscribers can pay and renew their subscription directly from the login page

RouterOS Hotspot Login Page Variables

RouterOS provides built-in template variables you can use in your login page HTML to display dynamic subscriber information:

• $(username) — the logged-in subscriber’s username
• $(ip) — the subscriber’s current IP address
• $(session-time-left) — remaining session time based on the User Profile timeout
• $(bytes-in) / $(bytes-out) — data usage for the current session
• $(uptime) — how long the current session has been active

Use these variables on the status.html page to give subscribers real-time visibility of their session — reducing support calls about “how long do I have left?”

Part 2 — Structured Voucher System

Vouchers are the commercial currency of hotspot businesses in Uganda — pre-generated username/password pairs sold to subscribers for timed or data-limited internet access. A well-structured voucher system is the difference between a scalable hotspot business and a chaotic manual operation.

Designing Your Voucher Tiers

Before generating vouchers, design your tier structure in RouterOS User Profiles (IP > Hotspot > User Profiles). Each tier should have a clear name, bandwidth limit, session time, and data quota. A practical tier structure for Uganda hotspot businesses:

Creating User Profiles in RouterOS

1. Go to IP > Hotspot > User Profiles → click Add (+)
2. Name: e.g. 1day-3Mbps
3. Rate Limit: 3M/3M (download/upload in Mbps)
4. Session Timeout: 1d (1 day = 24:00:00)
5. Shared Users: 1 (prevents credential sharing between devices)
6. Keepalive Timeout: 00:02:00 (disconnects idle sessions after 2 minutes to free up the hotspot user slot)
7. Click OK → repeat for each tier

Generating Vouchers in Bulk via User Generator

1. Go to Tools > User Manager in Winbox (or navigate to /tool user-manager)
2. Select Users → click Generate
3. Set Count: how many vouchers to generate (e.g. 50)
4. Set Profile: select your tier (e.g. 1day-3Mbps)
5. Set Username format: e.g. random (6–8 character alphanumeric codes)
6. Set Password: same as username, or a separate random value
7. Click Generate → export to CSV for printing and distribution

Print vouchers on small cards or slips with your business name, the username/password, and the package details. Sell directly or distribute through agents. For automated digital voucher delivery and subscriber self-service renewal, integrate with our ISP Billing System.

Part 3 — Per-User Bandwidth Limiting with Queue Trees

The Rate Limit field in User Profiles is the simplest way to apply per-user speed limits in RouterOS. However, for ISPs managing multiple subscriber tiers with shared uplink bandwidth, Queue Trees with PCQ (Per-Connection Queuing) provide far more sophisticated and fair bandwidth management.

Simple Rate Limiting vs PCQ — When to Use Each

• Simple Rate Limit (User Profile Rate Limit field): Best for straightforward hotspot voucher businesses where each user gets a fixed individual speed cap. Easy to configure, works out of the box with no additional setup. Use this for the majority of hotspot deployments in Uganda.
• PCQ (Per-Connection Queue): Best for ISPs managing a shared uplink where the total bandwidth must be divided fairly across all active subscribers. PCQ ensures that when 50 subscribers are active on a 50 Mbps uplink, each gets approximately 1 Mbps — rather than the first subscribers taking all the bandwidth until the link is saturated.

Implementing PCQ for Fair Bandwidth Sharing

1. Go to Queues > Queue Types → click Add (+)
2. Name: PCQ-Download → Kind: pcq → Classifier: dst-address → click OK
3. Add another: Name: PCQ-Upload → Kind: pcq → Classifier: src-address → click OK
4. Go to Queues > Simple Queues → click Add (+)
5. Name: Hotspot-Bandwidth → Target: 192.168.88.0/24 (your hotspot subnet)
6. Max Limit: set your total uplink bandwidth (e.g. 50M/50M)
7. Queue Type: Download → PCQ-Download, Upload → PCQ-Upload
8. Click OK

This configuration ensures fair bandwidth distribution across all active hotspot clients — preventing any single subscriber from monopolising the uplink during peak hours.

Part 4 — Session Management & Subscriber Control

IP Bindings — Bypassing and Blocking Subscribers

RouterOS Hotspot IP Bindings (IP > Hotspot > IP Bindings) allow you to:

• Bypass specific devices from authentication — useful for printers, smart TVs, and IOT devices that cannot display a login page
• Block specific MAC addresses — permanently prevent a device from connecting to your hotspot
• Assign fixed IPs to specific devices via MAC address binding — essential for servers and management devices that need stable IP addresses

Walled Garden — Free Access Before Login

The RouterOS Walled Garden (IP > Hotspot > Walled Garden) allows specific websites or IP ranges to be accessible before a subscriber logs in — without requiring a voucher. Use this to allow access to:

• Your business website or subscriber portal (so subscribers can purchase a voucher before logging in)
• Your ISP Billing System payment page — so subscribers can self-renew without needing to contact you
• A local payment gateway (MTN Mobile Money, Airtel Money API endpoints)

Active Sessions Monitoring

Go to IP > Hotspot > Active to see all currently authenticated subscribers in real time. Columns show username, IP address, MAC address, uptime, bytes in/out, and rate limit applied. You can disconnect any active session by right-clicking and selecting Remove — useful for immediately suspending a subscriber whose payment has lapsed.

Part 5 — RADIUS Integration for Centralised Billing

For ISPs managing multiple MikroTik routers across multiple hotspot sites, local user databases on each router do not scale. RADIUS (Remote Authentication Dial-In User Service) centralises authentication and accounting across all your routers into a single subscriber database.

How RADIUS Works with RouterOS Hotspot

1. A subscriber enters their credentials at any of your hotspot locations
2. The local MikroTik router sends an Access-Request to your central RADIUS server
3. The RADIUS server checks the credentials and subscriber status against the central database
4. If valid and active, the RADIUS server sends an Access-Accept with the subscriber’s bandwidth profile attributes
5. RouterOS applies the profile and the subscriber gets access — the session is logged in the RADIUS Accounting database
6. When the session ends (logout, timeout, or billing suspension), an Accounting-Stop record is sent to RADIUS for usage tracking

Configuring RADIUS on RouterOS

1. Go to RADIUS in Winbox → click Add (+)
2. Tick Hotspot service
3. Address: your RADIUS server IP
4. Secret: your shared RADIUS secret
5. Authentication Port: 1812 → Accounting Port: 1813 → click OK
6. Go to IP > Hotspot > Server Profiles → double-click your hotspot profile → tick Use RADIUS → click OK

Our ISP Billing System includes a built-in RADIUS server — simply point your MikroTik routers at the billing system’s RADIUS endpoint and your entire subscriber database, bandwidth profiles, and session accounting are managed centrally across all your hotspot sites in Uganda.

Frequently Asked Questions (FAQ)