Skip to content
MikroTik RouterOS Docs

HotSpot Captive Portal Setup

HotSpot Captive Portal Setup

Section titled “HotSpot Captive Portal Setup”

RouterOS Version: 7.x+ Difficulty: Intermediate Estimated Time: 30 minutes

TL;DR (Quick Start)

Section titled “TL;DR (Quick Start)”

For the impatient: here’s the 30-second version.

# Minimal HotSpot on ether2
/ip address add address=192.168.88.1/24 interface=ether2
/ip pool add name=hs-pool-1 ranges=192.168.88.10-192.168.88.100
/ip dhcp-server add name=hs-dhcp-1 interface=ether2 address-pool=hs-pool-1 disabled=no
/ip dhcp-server network add address=192.168.88.0/24 gateway=192.168.88.1 dns-server=192.168.88.1
/ip hotspot add name=hotspot1 interface=ether2 address-pool=hs-pool-1 profile=default disabled=no
/ip hotspot user add name=guest password=guest123 profile=default

Overview

Section titled “Overview”

HotSpot is MikroTik’s captive portal solution that forces users to authenticate before accessing the network. Unlike simple access control, HotSpot creates a transparent authentication layer that intercepts HTTP traffic and redirects unauthenticated users to a login page, making it ideal for guest networks, public WiFi, and controlled access scenarios.

This guide explains the underlying mechanisms, proper configuration, and common pitfalls that can make the difference between a seamless user experience and a troubleshooting nightmare.

Understanding Captive Portal Architecture

Section titled “Understanding Captive Portal Architecture”

The Authentication Flow

Section titled “The Authentication Flow”

When a device connects to a HotSpot-enabled network, this is what happens:

1. Device connects → Gets IP via DHCP
2. Device tries HTTP request → Intercepted by HotSpot
3. User redirected to login page → Enters credentials
4. Authentication succeeds → Traffic flows normally
5. Session timeout/logout → Returns to step 2

The Technical Implementation

Section titled “The Technical Implementation”

HotSpot works by creating a transparent proxy layer using these components:

HotSpot System Components

Critical insight: HotSpot only works with IPv4 and relies heavily on NAT rules. It cannot function with IPv6 or in pure bridging scenarios.

Network Topology Requirements

Section titled “Network Topology Requirements”

HotSpot requires a routed interface - it cannot work on bridge ports directly. The typical setup:

HotSpot Network Topology

Prerequisites

Section titled “Prerequisites”
  • RouterOS 7.x+ with device-mode supporting HotSpot (check /system device-mode)
  • At least two interfaces (WAN and LAN/HotSpot interface)
  • Basic understanding of DHCP and NAT
  • For HTTPS login: Valid SSL certificate and DNS name

The HotSpot Setup Wizard

Section titled “The HotSpot Setup Wizard”

MikroTik provides a setup wizard that configures all necessary components. Understanding what it creates helps you troubleshoot and customize later.

What the Wizard Creates

Section titled “What the Wizard Creates”

When you run /ip hotspot setup, it automatically configures:

  1. IP Pool - Range of addresses for HotSpot clients
  2. DHCP Server - Assigns IPs to connecting devices
  3. HotSpot Server - The captive portal instance
  4. HotSpot Profile - Authentication and session settings
  5. Firewall NAT Rules - Traffic redirection and masquerading
  6. DNS Configuration - Redirects DNS queries to HotSpot
  7. Default User - Initial login credentials

Manual vs. Wizard Configuration

Section titled “Manual vs. Wizard Configuration”

Use the wizard when:

  • Setting up a basic guest network
  • Learning HotSpot concepts
  • Creating a quick proof-of-concept

Configure manually when:

  • Integrating with existing network infrastructure
  • Requiring custom authentication (RADIUS)
  • Needing advanced walled garden rules
  • Setting up multiple HotSpot servers

Configuration Steps

Section titled “Configuration Steps”

This minimal example creates a working HotSpot on ether2 for testing the core concepts.

Note: While RouterOS provides /ip hotspot setup wizard for interactive configuration, the steps below use discrete commands that work with automation and validation tools.

Step 1: Configure HotSpot Gateway Interface

Section titled “Step 1: Configure HotSpot Gateway Interface”

Add an IP address to the interface that will serve HotSpot clients:

/ip address add address=192.168.88.1/24 interface=ether2 comment="HotSpot Gateway"

Step 2: Create Address Pool

Section titled “Step 2: Create Address Pool”

Create an IP pool for HotSpot clients:

/ip pool add name=hs-pool-1 ranges=192.168.88.10-192.168.88.100

Step 3: Configure DHCP Server

Section titled “Step 3: Configure DHCP Server”

Set up DHCP to assign addresses from the pool:

/ip dhcp-server add name=hs-dhcp-1 interface=ether2 address-pool=hs-pool-1 disabled=no
/ip dhcp-server network add address=192.168.88.0/24 gateway=192.168.88.1 dns-server=192.168.88.1

Step 4: Create HotSpot Server

Section titled “Step 4: Create HotSpot Server”

Create the HotSpot server on the interface:

/ip hotspot add name=hotspot1 interface=ether2 address-pool=hs-pool-1 profile=default disabled=no

Step 5: Create Test User

Section titled “Step 5: Create Test User”

Create a simple user account for testing:

/ip hotspot user add name=guest password=guest123 profile=default

Verification

Section titled “Verification”

Confirm the HotSpot server is running and properly configured:

Check 1: HotSpot Server Status

Section titled “Check 1: HotSpot Server Status”
/ip hotspot print

Expected Output:

#   NAME        INTERFACE  ADDRESS-POOL  PROFILE   IDLE-TIMEOUT
0   hotspot1    ether2     hs-pool-1     default   5m

Check 2: DHCP Server Configuration

Section titled “Check 2: DHCP Server Configuration”
/ip dhcp-server print

Expected Output:

Flags: X - disabled, I - invalid
#   NAME     INTERFACE  RELAY  ADDRESS-POOL  LEASE-TIME  ADD-ARP
0   dhcp1    ether2             hs-pool-2     1h

Check 3: User Database

Section titled “Check 3: User Database”
/ip hotspot user print

Expected Output:

#   NAME     SERVER  PROFILE  PASSWORD
0   guest    all     default  guest123

Advanced Configuration

Section titled “Advanced Configuration”

Custom Login Pages

Section titled “Custom Login Pages”

HotSpot uses HTML templates stored in the router’s file system. To customize:

  1. Access the files via FTP or Files menu in WinBox
  2. Copy the hotspot directory to create a custom version
  3. Modify HTML files (login.html, status.html, etc.)
  4. Point the profile to your custom directory
/ip hotspot profile set hsprof1 html-directory-override=custom-hotspot

Walled Garden Configuration

Section titled “Walled Garden Configuration”

Allow access to specific sites without authentication:

# Allow access to company website
/ip hotspot walled-garden add dst-host=*.company.com action=allow


# Allow access to specific IP range (e.g., local services)
/ip hotspot walled-garden ip add dst-address=10.0.0.0/24 action=allow

RADIUS Integration

Section titled “RADIUS Integration”

For enterprise authentication, integrate with a RADIUS server:

# Configure RADIUS client
/radius add service=hotspot address=10.0.0.100 secret=radiussecret


# Enable RADIUS in HotSpot profile
/ip hotspot profile set hsprof1 use-radius=yes

Session Management

Section titled “Session Management”

Control user session behavior:

/ip hotspot profile set hsprof1 \
    session-timeout=1h \
    idle-timeout=15m \
    keepalive-timeout=2m \
    on-login="log info \"User $user logged in from $address\"" \
    on-logout="log info \"User $user logged out\""

Security Considerations

Section titled “Security Considerations”

HTTPS Login

Section titled “HTTPS Login”

Enable secure authentication to protect credentials:

  1. Import SSL certificate:
/certificate import file-name=server.crt
/certificate import file-name=server.key
  1. Configure DNS name:
/ip dns set allow-remote-requests=yes
/ip dns static add name=hotspot.local address=192.168.88.1
  1. Enable HTTPS in profile:
/ip hotspot profile set hsprof1 login-by=https

Network Isolation

Section titled “Network Isolation”

Prevent HotSpot users from accessing internal networks:

# Block access to RFC1918 private networks
/ip firewall filter add chain=forward src-address=192.168.88.0/24 \
    dst-address=192.168.0.0/16 action=drop comment="Block HotSpot to internal"
/ip firewall filter add chain=forward src-address=192.168.88.0/24 \
    dst-address=10.0.0.0/8 action=drop
/ip firewall filter add chain=forward src-address=192.168.88.0/24 \
    dst-address=172.16.0.0/12 action=drop

Rate Limiting

Section titled “Rate Limiting”

Control bandwidth per user:

/ip hotspot user profile add name=limited rate-limit=2M/1M
/ip hotspot user set guest profile=limited

Troubleshooting

Section titled “Troubleshooting”

Problem: Login page doesn’t appear

Section titled “Problem: Login page doesn’t appear”

Symptoms: Users get internet access immediately or see “page not found”

Causes & Solutions:

  1. HotSpot not enabled on interface

    /ip hotspot print
    # Ensure interface is listed and not disabled

  2. DNS not redirected properly

    /ip firewall nat print
    # Look for DNS redirect rules (port 53)

  3. Device using HTTPS-only sites

    • Modern devices often use HTTPS by default
    • Configure HTTPS login or add HTTP sites to walled garden

Problem: Users can’t authenticate

Section titled “Problem: Users can’t authenticate”

Symptoms: Login page appears but credentials are rejected

Causes & Solutions:

  1. User database issues

    /ip hotspot user print
    # Verify user exists and password is correct

  2. RADIUS server unreachable (if using RADIUS)

    /radius monitor 0
    # Check RADIUS server status

  3. Profile misconfiguration

    /ip hotspot profile print detail
    # Verify authentication methods are enabled

Problem: Authenticated users lose connection

Section titled “Problem: Authenticated users lose connection”

Symptoms: Users must re-authenticate frequently

Causes & Solutions:

  1. Aggressive timeout settings

    /ip hotspot profile print
    # Check idle-timeout and session-timeout values

  2. IP address conflicts

    /ip hotspot host print
    # Look for duplicate MAC addresses

  3. NAT table overflow

    /ip firewall connection print count-only
    # Monitor connection table usage

Problem: Some websites don’t work

Section titled “Problem: Some websites don’t work”

Symptoms: Authenticated users can’t access specific sites

Causes & Solutions:

  1. Walled garden blocking legitimate traffic

    /ip hotspot walled-garden print
    # Review allow/deny rules

  2. DNS resolution issues

    /ip dns cache print
    # Check if DNS queries are being resolved

  3. MTU/MSS issues with transparent proxy

    /ip firewall mangle add chain=forward protocol=tcp tcp-flags=syn \
        action=change-mss new-mss=clamp-to-pmtu

Useful Debug Commands

Section titled “Useful Debug Commands”
# Monitor active HotSpot sessions
/ip hotspot active print


# Check HotSpot host table
/ip hotspot host print


# View HotSpot cookies (for cookie-based auth)
/ip hotspot cookie print


# Monitor firewall rules created by HotSpot
/ip firewall nat print dynamic


# Check connection tracking
/ip firewall connection print where connection-state=established

Common Use Cases

Section titled “Common Use Cases”

Guest Network with Time Limits

Section titled “Guest Network with Time Limits”
# Create time-limited profile
/ip hotspot user profile add name=guest-1hour session-timeout=1h


# Create daily guest accounts
/ip hotspot user add name=guest-$(date) password=daily123 profile=guest-1hour

Voucher-Based Access

Section titled “Voucher-Based Access”
# Create voucher profile with data limits
/ip hotspot user profile add name=voucher limit-bytes-total=500M


# Generate voucher codes
:for i from=1 to=10 do={
    /ip hotspot user add name=("voucher" . $i) password=("pass" . $i) profile=voucher
}

Corporate Guest Portal

Section titled “Corporate Guest Portal”
# Configure RADIUS authentication
/radius add service=hotspot address=10.0.0.100 secret=corporate-secret


# Set up corporate profile
/ip hotspot profile add name=corporate \
    use-radius=yes \
    login-by=http-chap \
    html-directory-override=corporate-portal

Integration with VLANs

Section titled “Integration with VLANs”

HotSpot can work with VLANs for network segmentation:

# Create VLAN interface for guest network
/interface vlan add name=vlan-guest vlan-id=100 interface=ether2


# Configure HotSpot on VLAN interface
/ip hotspot add name=guest-hotspot interface=vlan-guest \
    address-pool=guest-pool profile=guest-profile


# Isolate guest VLAN from internal networks
/ip firewall filter add chain=forward in-interface=vlan-guest \
    dst-address=192.168.1.0/24 action=drop

Performance Considerations

Section titled “Performance Considerations”

Hardware Requirements

Section titled “Hardware Requirements”

HotSpot performance depends on:

  • CPU power - All traffic passes through the CPU
  • RAM - Session state and connection tracking
  • Flash storage - Log files and user database

Optimization Tips

Section titled “Optimization Tips”

  1. Use hardware with sufficient CPU

    • Avoid ARM-based devices for high-traffic scenarios
    • Consider x86 devices for 100+ concurrent users

  2. Optimize session timeouts

    # Reduce idle timeout to free resources faster
    /ip hotspot profile set default idle-timeout=5m

  3. Limit concurrent sessions

    # Prevent resource exhaustion
    /ip hotspot profile set default address-pool=limited-pool

  4. Monitor resource usage

    /system resource print
    /system resource cpu print
Section titled “Related Topics”

Prerequisites

Section titled “Prerequisites”

Authentication

Section titled “Authentication”

Bandwidth Control

Section titled “Bandwidth Control”

Network Segmentation

Section titled “Network Segmentation”

References

Section titled “References”