Captive Portal · Firoz Mahmud

Router setup guide

Configure MikroTik HotSpot so guests are redirected to the login page, submit the form, and get full internet access.

Guest login page (already live)

https://captive-portal.firozmahmud.dev/login

Open the login URL in a browser first to confirm the form loads, then configure the router.

How it works

The router must redirect guests — typing the URL manually will not pass the device MAC.

Guest joins your WiFi

Guest opens any website

Router redirects to /login with device MAC

Guest submits the portal form

Portal unlocks browsing on the router

You configure the router only — the portal handles the login page and guest records.

System overview

Portal is already live on the internet — you only configure the MikroTik router.

Rules

Splash URL must pass the guest MAC — without mac= the form cannot unlock internet.
Guests must be redirected by the router — typing the URL manually will not work.
Walled garden must allow the portal domain — otherwise the login page never loads.
Portal guest list alone is not enough — the router must receive the unlock signal.

What the router must send

MikroTik replaces $(mac) etc. automatically when the guest is redirected.

Parameter	MikroTik	Purpose
Device MAC	`$(mac)`	Guest identity (required)
Unlock endpoint	`$(link-login-only)`	Portal POST target (required)
Original site	`$(link-orig)`	Post-login redirect
Guest IP	`$(ip)`	Records (optional)

If MAC is missing

Guests see device id missing — open this page from the guest WiFi splash so the router can authorize browsing.

After the guest submits

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

Copy-paste values

Splash URL

Hotspot → Server Profiles → Login

URL

https://captive-portal.firozmahmud.dev/login?mac=$(mac)&ip=$(ip)&link-login-only=$(link-login-only)&link-orig=$(link-orig)

Walled garden

Allow portal before login

RouterOS

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

HotSpot user

Password must match the portal · HTTP PAP

RouterOS

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

Step-by-step

Enable Hotspot

IP → Hotspot → run setup wizard
Select guest WiFi interface or bridge
Leave RADIUS unchecked

External login page

HTML

<form 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="link-login-only" value="$(link-login-only)">
  <input type="hidden" name="link-orig" value="$(link-orig)">
</form>
<script>document.forms[0].submit();</script>

Walled garden

RouterOS

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

Shared HotSpot user

Portal username portal-guest and the same password on the router.

RouterOS

/ip hotspot user add name=portal-guest password=<portal-password> profile=default

Test end-to-end

Connect a phone to guest WiFi (mobile data off)
Open any website — URL must contain mac=
Submit the form
Verify: /ip hotspot active print

Troubleshooting

Problem	Likely cause	Fix
Login page never appears	Walled garden missing	Add walled garden for `captive-portal.firozmahmud.dev`
`device id missing`	No MAC in URL	Add `$(mac)` to splash URL; guest must come from HotSpot redirect
No internet after submit	Wrong HotSpot password	Match HotSpot user password with portal
No internet after submit	Missing `link-login-only`	Fix splash URL / HTML — include `link-login-only`
Works in browser, not on WiFi	Router not redirecting	Check HotSpot profile and splash URL

Final checklist

https://captive-portal.firozmahmud.dev/login loads in a browser
Splash URL includes $(mac) and $(link-login-only)
Walled garden allows captive-portal.firozmahmud.dev
HotSpot user password matches the portal
Guest arrives via HotSpot redirect (mac= in URL)
After submit: internet works