| name | routeros-hotspot |
| description | RouterOS hotspot captive portal for wired/wireless access control. Use when: configuring hotspot on RouterOS, setting up captive portal, writing hotspot profiles or instances, configuring walled garden, setting DHCP option 114 (RFC 8910 captive portal URI), integrating RADIUS with hotspot, or when the user mentions /ip/hotspot, walled-garden, hotspot profile, or captive portal on MikroTik. |
RouterOS Hotspot
How Hotspot Chains Work
Hotspot traffic intercept runs before the regular firewall input/forward chains. This is the single most important fact to internalize:
/ip/hotspot binds to a bridge or interface — all traffic on that interface enters the hotspot chain first- Firewall rules blocking TCP 80/443 from the hotspot interface do NOT block the captive portal login page — hotspot handles it before the firewall sees it
- RouterOS automatically injects dynamic firewall rules (
hs-unauth, hs-auth chains) — do not manually create, remove, or interfere with these hotspot-managed rules
Common mistake: Adding a DROP rule for port 443 from bridge-hotspot to "fix a security gap" — this breaks the HTTPS login page silently.
Hotspot Profile
/ip/hotspot/profile/add \
name=my-profile \
hotspot-address=10.20.0.1 \
login-by=https,mac,http-pap \
mac-auth-mode=mac-as-username-and-password \
dns-name=login.example.com \
ssl-certificate=login.example.com.crt_0 \
nas-port-type=ethernet \
use-radius=yes \
radius-accounting=yes \
html-directory-override=hotspot-files
Key properties:
ssl-certificate= — reference the name after import (RouterOS appends _0 to imported certificate names)nas-port-type= — use ethernet for wired hotspots and wireless-ieee-802-11-g for wireless hotspotshtml-directory-override= — must match the exact folder name on the router's filesystemlogin-by=https — serves the login page over HTTPS; requires www-ssl service enabled with the same certificateuse-radius=yes — when set, local /ip/hotspot/user entries are bypassed; adding them has no effect
Hotspot Instance
/ip/hotspot/add \
name=hotspot1 \
interface=bridge-hotspot \
profile=my-profile \
address-pool=pool-hotspot \
addresses-per-mac=2 \
idle-timeout=5m \
keepalive-timeout=none \
disabled=no
Note: keepalive-timeout=none disables the keepalive. keepalive-timeout=0 is NOT valid — it is ignored.
Note: RouterOS hotspot relies on NAT and is IPv4-only. IPv6 clients are not supported by the hotspot subsystem.
DHCP Option 114 — Captive Portal API (RFC 8910)
Option 114 (standardized 2020, RFC 8910) signals the captive portal URI to clients. It is underrepresented in LLM training data.
# force=yes is REQUIRED — without it, clients whose DHCP Parameter Request
# List does not include code 114 (e.g. iOS, Android) silently skip the option
/ip/dhcp-server/option/add \
name=captive-portal \
code=114 \
force=yes \
value="'https://login.example.com/api'"
/ip/dhcp-server/option/sets/add \
name=captive-portal-set \
options=captive-portal
/ip/dhcp-server/set my-dhcp-server dhcp-option-set=captive-portal-set
Option value syntax: outer double quotes, inner single quotes — "'https://...'". Missing inner quotes cause the option to be sent as a binary blob, not a string URI.
api.json timing: RouterOS creates hotspot/api.json only after the first client CAPPORT probe — not at hotspot enable time. Move it to the html-directory-override folder after first client connects:
# Handles both flash/ and non-flash storage layouts
:local srcPath "hotspot/api.json"
:local dstPath "hotspot-files/api.json"
:if ([:len [/file find name="flash"]] > 0) do={
:set srcPath "flash/hotspot/api.json"
:set dstPath "flash/hotspot-files/api.json"
}
:if ([:len [/file find name=$srcPath]] > 0) do={
/file set [find name=$srcPath] name=$dstPath
} else={
:log warning "api.json not yet created — run after first client CAPPORT probe"
}
Walled Garden
Use a consistent comment= tag for idempotent add/remove. Without it, repeated script runs accumulate duplicate entries.
# Remove only our entries, not manually-added ones
/ip/hotspot/walled-garden/ip/remove [find comment="my-wg"]
/ip/hotspot/walled-garden/ip/add dst-host=example.com action=accept comment="my-wg"
/ip/hotspot/walled-garden/ip/add dst-host=*.example.com action=accept comment="my-wg"
IP vs HTTP walled garden:
/ip/hotspot/walled-garden/ip — layer 3 match by destination host, applied BEFORE authentication. Use for HTTPS destinations./ip/hotspot/walled-garden — layer 7 URL pattern match, requires HTTP. Does NOT work for HTTPS.
SSL Certificate Note
The hotspot profile references ssl-certificate=name.crt_0 (RouterOS appends _0 on import). Enable www-ssl with the same certificate:
/ip/service/set www-ssl disabled=no certificate=login.example.com.crt_0 tls-version=only-1.2
Quick import pattern:
/certificate import file-name=login.example.com.crt passphrase=""
/certificate import file-name=login.example.com.key passphrase=""
# After import, the certificate appears as login.example.com.crt_0
External Captive Portal — HTML Template Variables
RouterOS substitutes $(variable) server-side in any file under html-directory-override before serving it. These are not JavaScript variables — they are filled before the browser receives the page.
Servlet pages RouterOS serves (drop your own to override):
login.html, flogin.html (failed-login), alogin.html (post-success), status.html, logout.html, error.html, redirect.html, rlogin.html, rstatus.html, fstatus.html, flogout.html, radvert.html, md5.js, errors.txt. Most external-CP setups only need login.html + alogin.html + status.html.
Most-used variables for external CP:
| Variable | Description |
|---|
$(link-login-only) | Login POST endpoint without ?dst= — preferred for external auth (avoids double-encoding) |
$(link-login) | Login URL with ?dst= redirect appended |
$(link-orig) / $(link-orig-esc) | Original URL the client requested. Use -esc when interpolating into another URL |
$(server-name) | Hotspot instance name |
$(mac) / $(mac-esc) | Client MAC (raw / URL-escaped) |
$(ip) | Client IP |
$(host-ip) | IP from hotspot host table (differs from $(ip) under one-to-one NAT) |
$(interface-name), $(vlan-id) | Useful for tenant-aware external auth |
$(error) / $(error-orig) | Localized vs raw error from previous auth attempt |
$(logged-in) | yes if client is already authenticated |
$(trial) | yes if trial access still available for this MAC |
$(username) / $(username-esc) | Authenticated username (status page) |
$(bytes-in[-nice]), $(bytes-out[-nice]), $(uptime[-secs]), $(session-time-left[-secs]) | Status-page counters |
$(radius<id>[u]), $(radius<id>-<vnd-id>[u]) | Pass-through of RADIUS Access-Accept attributes — text or unsigned int. Empty / "0" when local-DB auth (use-radius=no) |
$(http-header-<Name>) | Read an incoming request header — e.g. , |
Always pick the -esc variant ($(link-orig-esc), $(mac-esc), $(username-esc)) when embedding a value into a URL or query string. The non-escaped variants will break parsing or open injection paths if the value contains &, =, ?, #.
POST form fields RouterOS accepts at $(link-login-only):
username, password, domain, dst, popup, session-id, var, erase-cookie, target (multi-language subdir).
Conditional syntax (server-side, not JavaScript):
$(if logged-in == "yes")
<a href="$(link-logout)">Logout</a>
$(else)
<form action="$(link-login-only)" method="post">...</form>
$(endif)
Operators: presence ($(if VAR)), ==, !=. Also $(elif ...). No nested arithmetic / string ops.
Generic login.html pattern for external captive portal:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="pragma" content="no-cache">
<meta name="viewport" content="width=device-width, initial-scale=1">
<script src='https://auth.example.com/snippets/router-os/redirect'></script>
</head>
<body>
<div id="entryPoint">Redirecting...</div>
<script>
window.addEventListener('load', function () {
ExternalAuth_redirect(
'$(server-name)', '$(mac-esc)', '$(link-login-only)',
'$(link-orig-esc)', '$(error-orig)', '$(logged-in)', '$(ip)'
);
});
</script>
</>
The external provider authenticates the user and redirects the browser back to $(link-login-only) with username + password + dst POST fields. RouterOS validates (local DB or RADIUS), issues the auth cookie, and redirects to dst.
Walled-garden must include the external auth host (and any CDN/asset hosts) — otherwise the unauthenticated browser cannot reach the redirect script in step 2.
Full variable reference, all servlet pages, RADIUS pass-through patterns, multi-language target= mechanics, and HTTP response control: see references/template-variables.md.
Common LLM Mistakes
| Mistake | Correct behavior |
|---|
| DROP TCP 443 from hotspot interface | Hotspot chain runs before firewall — breaks the HTTPS login page |
keepalive-timeout=0 to disable keepalive | Use keepalive-timeout=none |
Option 114 value= without inner single quotes | Must be "'https://...'" — outer double, inner single |
Option 114 without force=yes | iOS/Android silently skip option if not in their DHCP PRL |
Adding /ip/hotspot/user when use-radius=yes | Local users are bypassed when RADIUS is active |
Wildcard HTTPS domains in /ip/hotspot/walled-garden | Use /ip/hotspot/walled-garden/ip for HTTPS (layer 3 match) |
| Hotspot on dual-stack network with IPv6 | Hotspot is IPv4-only — IPv6 not supported |
$(link-login) treated as JavaScript variable | It is RouterOS server-side substitution, not JS |
Embedding $(link-orig) / $(mac) / $(username) into another URL | Use the -esc variant — non-esc breaks parsing on &, =, ? and may enable injection |
| Hotspot with PCC / multiple routing tables | Hotspot uses only the default routing table — split-WAN setups need explicit /ip route rule for hotspot traffic |
Additional Resources
Related skills:
routeros-fundamentals — RouterOS CLI syntax, REST API, scripting basicsrouteros-certificates (in backlog) — for the full certificate chain handling pattern
MCP tools:
rosetta MCP server — /tool/ping, /ip/hotspot command tree inspection (routeros_search, routeros_get_page)
MikroTik docs:
RADIUS Integration
See references/radius-client.md for RADIUS client configuration patterns.
