routeros-hotspot

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 hotspots
• html-directory-override= — must match the exact folder name on the router's filesystem
• login-by=https — serves the login page over HTTPS; requires www-ssl service enabled with the same certificate
• use-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.

Most external captive portal setups override login.html, alogin.html, and status.html. Keep the full servlet page list, POST fields, RADIUS pass-through variables, multi-language target= mechanics, and HTTP response-control syntax in references/template-variables.md.

Use $(link-login-only) as the login POST endpoint, pass the original destination through dst, and always pick escaped variants such as $(link-orig-esc), $(mac-esc), and $(username-esc) when embedding values into URLs or query strings. The non-escaped variants can break parsing or open injection paths if a value contains &, =, ?, or #.

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">
  <!-- External auth provider loads redirect logic -->
  <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>
</body>
</html>

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.

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 basics
• routeros-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:

• HotSpot — official reference
• DHCP Server — option 114 configuration

RADIUS Integration

See references/radius-client.md for RADIUS client configuration patterns.