Router setup guide

01 Before you start

This guide configures a MikroTik RouterOS HotSpot on your physical or virtual router. Guests on guest WiFi are redirected to the live captive portal, fill name/age/gender (Male / Female / Other), and submit (that submit is consent — there is no separate checkbox). Then they receive internet. You only touch the router — the portal handles the login page and guest records.

Prerequisites — check each item as you confirm it

• Guest WiFi interface/bridge has working DHCP, NAT, and internet access
• WinBox, WebFig, or SSH admin access to the router
• Phone or laptop ready to join guest WiFi with mobile data off
• RouterOS backup exported (/export file=pre-hotspot-backup)

02 How it works

Follow the guest journey from WiFi join to internet access:

1. 1 Join WiFi Guest connects and receives an IP from the router.
2. 2 Get redirected Any website visit sends the guest to /login with mac= and link-login-only.
3. 3 Submit form Guest enters name, age, gender (Male / Female / Other) and submits — submit = consent (no checkbox).
4. 4 Portal unlocks Portal saves the record and POSTs HotSpot credentials to $(link-login-only).
5. 5 Online Router opens internet for that MAC. Walk-away / idle ≈5m ends the HotSpot session (profile default); MAC cookie up to ~3 days.

03 Rules for every router

04 MikroTik Hotspot configuration

Real RouterOS settings — work through each step in WinBox or terminal. Expand a step, apply it on your router, then tick it off.

/ip hotspot print

<html><head><title>Redirect</title></head><body>
<form name="redirect" action="https://captive-portal.firozmahmud.dev/login" method="get">
  <input type="hidden" name="mac" value="$(mac)">
  <input type="hidden" name="ip" value="$(ip)">
  <input type="hidden" name="host-ip" value="$(host-ip)">
  <input type="hidden" name="hostname" value="$(hostname)">
  <input type="hidden" name="link-login-only" value="$(link-login-only)">
  <input type="hidden" name="link-orig" value="$(link-orig)">
  <input type="hidden" name="server-name" value="$(server-name)">
  <input type="hidden" name="identity" value="$(identity)">
  <input type="hidden" name="server-address" value="$(server-address)">
  <input type="hidden" name="interface-name" value="$(interface-name)">
  <!-- Per-router bridge MAC (no $(router-mac)). POC: e4:8d:8c:36:45:db -->
  <input type="hidden" name="router_mac" value="e4:8d:8c:36:45:db">
  <input type="hidden" name="ssid" value="captive-portal-open-wifi">
</form>
<script>document.redirect.submit();</script>
</body></html>

/ip hotspot print detail
/ip hotspot profile set hsprof4 login-by=http-pap,http-chap,cookie
/ip hotspot user profile set [find name=default] idle-timeout=5m keepalive-timeout=2m mac-cookie-timeout=3d

https://captive-portal.firozmahmud.dev/login?mac=$(mac)&ip=$(ip)&host-ip=$(host-ip)&hostname=$(hostname)&link-login-only=$(link-login-only)&link-orig=$(link-orig)&server-name=$(server-name)&identity=$(identity)&server-address=$(server-address)&interface-name=$(interface-name)

/ip hotspot walled-garden add dst-host=captive-portal.firozmahmud.dev

/ip hotspot user add name=portal-guest password=<portal-password> profile=default
/ip hotspot user profile set [find default] shared-users=100

05 After the guest submits

Submitting the login form is consent (hidden consent=1; no separate tick). The portal saves the guest record, then auto-POSTs the HotSpot username and password to link-login-only (the router's login endpoint) so the browser — not a server-to-server call — performs the unlock.

Portal POSTs to $(link-login-only) using HotSpot user portal-guest — password must match portal config (MIKROTIK_HOTSPOT_PASSWORD).

06 Presence heartbeat (verified on POC)

Near-realtime Online / Offline on /list. Does not change guest login or unlock — splash → form → browser POST to router /login stays the same.

1. 1 Portal secret Set the same value in portal .env / GitHub secret MIKROTIK_PRESENCE_SECRET and inside the MikroTik script. Compose must pass it into the portal container; redeploy. Empty secret → API returns 503.
2. 2 System → Scripts → New Name exactly portal-presence (not script1). Check Don’t Require Permissions. Paste source from repo setup/mikrotik/presence-report.rsc (or gitignored presence-report.local.rsc with secret already filled).
3. 3 Edit CONFIG POC defaults already match: SSID captive-portal-open-wifi, bridge bridge-hotspot, server hotspot1, URL https://captive-portal.firozmahmud.dev/mikrotik/presence. You only must set secret if using the placeholder file.
4. 4 User Profile hooks On the HotSpot user profile used by guests (check /ip hotspot user print detail): set On Login and On Logout to /system script run portal-presence.
5. 5 Test Click Run Script once. Check Log for portal-presence: OK, Files → portal-presence-last.json, and /list Connection status.

/ip hotspot user profile set [find name=default] \
  on-login="/system script run portal-presence" \
  on-logout="/system script run portal-presence"

If guests use another profile (not default), set On Login / On Logout on that profile instead. Full click-by-click guide with screenshot: repo docs/mikrotik/presence-script-setup.md.

07 Troubleshooting

Expand the symptom that matches what you see:

/ip hotspot profile set hsprof4 login-by=http-pap,http-chap,cookie
/ip hotspot user profile set [find name=default] idle-timeout=5m keepalive-timeout=2m mac-cookie-timeout=3d

08 Security recommendations

To undo this integration: remove the walled-garden rule and HotSpot user, and restore the default login.html. Keep a RouterOS export from before you started in case you need a full restore.