MikroTik

How to connect a MikroTik router running the RouterOS HotSpot to Kiwire. MikroTik is the most widely deployed controller on Kiwire, so this page goes step by step, and every router-side setting is also given as a script you can paste into the router's terminal.

Device type in Kiwire	Mikrotik
Redirect URL	https://<kiwire-host>/login/mikrotik
RADIUS	auth 1812 / acct 1813 (UDP)
Identity must equal	The router's System Identity. RouterOS sends it as NAS-Identifier, and the HotSpot login page sends it as nasid in the redirect
HotSpot login method	HTTP PAP must be enabled (login-by includes http-pap)
Disconnect / live changes (CoA)	Yes, UDP port 3799 (RouterOS calls it "RADIUS incoming"; its own default is 1700)
Data caps	Yes: Mikrotik-Total-Limit + Mikrotik-Total-Limit-Gigawords (caps over 4 GiB work). Speed: Mikrotik-Rate-Limit
Device bypass	Yes, two ways (both optional): approved devices through MAC login (step 8), or router rules written through the RouterOS API on TCP 8728 (step 7)

Read Controller identity and Virtual NAS once before your first installation. With MikroTik the rules are simple: one router, one Identity, one record.

How a login works

1. A guest joins the HotSpot network and opens a web page. RouterOS shows its login page (login.html).
2. You replace that page with a short one that forwards the guest to Kiwire, adding the guest's MAC and IP, the router's login address, the original page and the router's Identity.
3. The guest logs in on the Kiwire portal. Kiwire then sends the guest's browser back to the router's login address with username, password and dst (the page they first asked for).
4. The router checks those credentials with Kiwire over RADIUS. Kiwire answers with the time, speed and data limits from the guest's profile, and the router starts accounting.
5. While the guest is online, Kiwire can end the session or change its speed by sending a Disconnect or CoA request to the router (step 3 below).

Steps 2 and 4 are the controller's side of the portal, step 5 is its RADIUS side. When the page loads but the login never completes, the break is almost always at step 4 (the login address) or step 5 (the Identity or the shared secret).

Kiwire hands the password back to the router as it is, not as a CHAP hash. That is why the HotSpot must accept HTTP PAP logins (step 4 below).

Before you start

From Kiwire:

• The RADIUS server address. It is shown at the top of System › Device Controller (and in the Setup Guide checklist). Below it is written <radius-server-ip>.
• Your <kiwire-host>: the host name of your portal. Portals › Troubleshoot › Controller Test shows it in the Test URL field.
• A <shared-secret> of 64 characters or fewer. You can use Generate on the Device Controller form and copy the value to the router.
• An <identity> for the router: at least 4 characters and unique across the whole Kiwire platform, so make it specific, for example acme-kl-lobby-hs1.
• If you want disconnects and live changes: the address Kiwire's Disconnect and CoA requests come from, shown at the top of System › Device Controller as Disconnect / CoA requests come from. Below it is written <coa-source-ip> (see step 3).

On the router:

• RouterOS v7 (v6.43 or later also works; see RouterOS v6 below) with a working HotSpot on the guest interface or bridge. If there isn't one yet, run the setup wizard: /ip hotspot setup (or IP › Hotspot › Hotspot Setup in WinBox/WebFig).
• The name of the HotSpot server profile the HotSpot uses: /ip hotspot print shows it in the PROFILE column (the wizard calls it hsprof1). Below it is written <hotspot-profile>.
• Admin access by WinBox, WebFig or SSH, and a way to upload files (WinBox Files, or FTP/SFTP).
• Internet access from the router to <radius-server-ip> on UDP 1812 and 1813.
• For disconnects, live speed changes and device bypass: an address of the router that Kiwire can reach from the internet (a public IP, or a port forward to the router).

On the controller

The quickest way is the script below: replace every <…> placeholder, then paste it into New Terminal in WinBox or an SSH session. Steps 1 to 7 after it explain each part, and give the same settings for WinBox/WebFig. Menu names differ a little between firmware versions; the values are what matter.

Let Kiwire generate it (site provisioning)

Instead of editing the script below by hand, open Device › Controllers, select the MikroTik in the list and click Site Provisioning in the toolbar. Tick Captive portal and/or WPA-Enterprise, fill in the hotspot interface (for example ether2 or bridge-guest) if you want Kiwire to create the HotSpot server, and click Generate command. Kiwire builds the whole setup for that controller — Identity, RADIUS with disconnect support, HotSpot profile, walled garden and the login page — and gives you one line to paste into the router's terminal. The router downloads its script from Kiwire once and runs it, printing a KIWIRE-RESULT, KIWIRE-SKIP or KIWIRE-WARN line for every step.

• RouterOS 7 or later. On older versions the script stops before changing anything.
• Nothing that can cut off guests already online runs unless you ask: the HotSpot server, LAN address, DNS and NAT options, and binding a WiFi radio are all opt-in.
• Running it again is safe: it updates what it created instead of adding copies.
• The RADIUS secret is only written into the script if you tick Embed RADIUS shared secret; otherwise set it on the router afterwards (/radius set [find comment=kiwire-managed] secret=<the controller's shared secret>).
• The one-line command works for 30 minutes and at most 5 downloads. Recent RouterOS checks Kiwire's certificate when downloading; on an older RouterOS 7 without built-in certificates, remove check-certificate=yes-without-crl from the line.
• The controller must still be registered in Kiwire's NAS registry (ask Synchroweb), and needs a zone and portal journey for guests to see a page.

The complete script

# --- Kiwire: MikroTik HotSpot setup (RouterOS v7) ---
# Replace every <...> before pasting. Lines starting with # are comments.

# 1. Identity: must match the Identity on the Kiwire Device Controller record
/system identity set name=<identity>

# 2. Kiwire as the HotSpot RADIUS server
/radius add service=hotspot address=<radius-server-ip> secret=<shared-secret> \
    authentication-port=1812 accounting-port=1813 timeout=3s comment="Kiwire RADIUS"

# 3. Accept Disconnect and CoA requests from Kiwire
/radius incoming set accept=yes port=3799
# Only if <coa-source-ip> differs from <radius-server-ip> (see System > Device Controller):
/radius add service=hotspot address=<coa-source-ip> secret=<shared-secret> \
    authentication-port=1812 accounting-port=1813 timeout=3s comment="Kiwire CoA source"

# 4. HotSpot server profile: RADIUS on, HTTP PAP allowed, accounting on
/ip hotspot profile set [find name=<hotspot-profile>] use-radius=yes \
    login-by=http-pap,http-chap,cookie radius-accounting=yes radius-interim-update=received

# 5. login.html: upload the file from step 5 of the guide (not done by this script)

# 6. Walled garden: let guests reach the Kiwire portal before they log in
/ip hotspot walled-garden ip add action=accept dst-host=<kiwire-host> comment="Kiwire portal"
/ip hotspot walled-garden add action=allow dst-host=<kiwire-host> comment="Kiwire portal"
/ip hotspot walled-garden ip add action=accept dst-host=fonts.googleapis.com comment="Kiwire portal fonts"
/ip hotspot walled-garden ip add action=accept dst-host=fonts.gstatic.com comment="Kiwire portal fonts"

# 7. Optional, only for Bypass Devices › Router rules: RouterOS API for Kiwire
/ip service set api disabled=no port=8728 address=<allowed-address>
/user group add name=kiwire-api policy=read,write,api
/user add name=kiwire group=kiwire-api password=<api-password>

# 8. Optional, only for Bypass Devices › Approved devices: MAC login before the login page
/ip hotspot profile set [find name=<hotspot-profile>] \
    login-by=mac,http-pap,http-chap,cookie mac-auth-mode=mac-as-username-and-password

• Leave out the second /radius add in part 3 if the Device Controller page shows the same address for the RADIUS server and for Disconnect / CoA requests.
• Leave out part 8 if you don't use approved devices. It replaces the login-by list from part 4 with the same list plus mac.
• Leave out part 7 if you don't use router rules. <allowed-address> is the address Kiwire connects to the API from (ask Synchroweb support); <api-password> is a password you choose.
• Running the script twice adds the RADIUS and walled-garden entries twice. If you need to run it again, remove the old entries first (/radius print, /ip hotspot walled-garden print, /ip hotspot walled-garden ip print).

1. Set the router's Identity

/system identity set name=<identity>

WinBox/WebFig: System › Identity. RouterOS sends this name as NAS-Identifier in every RADIUS request, and the login page in step 5 sends it in the redirect. It must be exactly the Identity you enter in Kiwire.

2. Add Kiwire as the RADIUS server

/radius add service=hotspot address=<radius-server-ip> secret=<shared-secret> \
    authentication-port=1812 accounting-port=1813 timeout=3s

WinBox/WebFig: RADIUS › +, tick hotspot.

• service=hotspot is enough for guest Wi-Fi. Add other services only if you also use Kiwire for them.
• timeout=3s is a suggestion. The RouterOS default (1100 ms) is short for a RADIUS server across the internet.
• If the router has several WAN links and the requests must leave from a particular one, set src-address= as well.

3. Accept disconnects and live changes from Kiwire

/radius incoming set accept=yes port=3799

WinBox/WebFig: RADIUS › Incoming.

RouterOS's own default port for this is 1700. Kiwire's COA Port defaults to 3799. Use 3799 on both, or enter 1700 in Kiwire's COA Port field instead. The two must match.

The router has to know the secret for every address it accepts these requests from, so it answers only addresses it has a /radius entry for. If Synchroweb support tells you Kiwire's Disconnect and CoA requests come from an address other than <radius-server-ip>, add a second entry for it with the same secret:

/radius add service=hotspot address=<coa-source-ip> secret=<shared-secret> \
    authentication-port=1812 accounting-port=1813 timeout=3s

Keep it below the first entry (/radius print lists them in order). The router tries entries in order, so it only sends a login request to the second one if the first does not answer.

If your firewall drops unsolicited traffic to the router, allow UDP 3799 from <coa-source-ip> in the input chain.

Kiwire sends a Disconnect request when you disconnect a session, when a guest's account expires, when the time or data runs out between accounting updates, and when a guest's device limit is exceeded with auto-disconnect on. If the router ignores these requests, those guests stay online until the router's own limits end the session.

4. Use RADIUS in the HotSpot server profile

/ip hotspot profile set [find name=<hotspot-profile>] use-radius=yes \
    login-by=http-pap,http-chap,cookie radius-accounting=yes radius-interim-update=received

WinBox/WebFig: IP › Hotspot › Server Profiles, open the profile: Login tab for login-by, RADIUS tab for the rest.

• http-pap in login-by is required. Kiwire hands the password back to the router in plain form. The RouterOS default is http-chap,cookie, and a profile without http-pap rejects every login from Kiwire.
• http-chap can stay. It does no harm next to http-pap, but on its own it is not enough.
• cookie is optional. With it, a returning device skips the login page for the cookie lifetime.
• radius-interim-update=received (the RouterOS default) makes the router use the accounting interval Kiwire sends (Acct-Interim-Interval, at least 5 minutes).
• If you have given the HotSpot an SSL certificate (ssl-certificate= on the same profile), you can add https to login-by. The router's login address in the redirect then starts with https://, and the hand-back goes over HTTPS.

5. Replace the login page so it forwards guests to Kiwire

The HotSpot's pages live in the directory named by the profile's html-directory setting (default hotspot; on some routers flash/hotspot). Check it with:

/ip hotspot profile print where name=<hotspot-profile>

In WinBox Files, download login.html from that directory as a backup, then upload a new login.html with exactly this content (replace <kiwire-host> only), overwriting the old one:

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="pragma" content="no-cache">
<meta http-equiv="expires" content="-1">
<meta http-equiv="refresh" content="0; url=https://<kiwire-host>/login/mikrotik?mac=$(mac-esc)&ip=$(ip)&link-login=$(link-login-only-esc)&link-orig=$(link-orig-esc)&nasid=$(identity-esc)&vlan=$(vlan-id)&error=$(error-esc)">
<title>Loading</title>
</head>
<body>
<p>Loading the login page&hellip; If nothing happens,
<a href="https://<kiwire-host>/login/mikrotik?mac=$(mac-esc)&ip=$(ip)&link-login=$(link-login-only-esc)&link-orig=$(link-orig-esc)&nasid=$(identity-esc)&vlan=$(vlan-id)&error=$(error-esc)">tap here</a>.</p>
</body>
</html>

RouterOS fills in each $(…) when it serves the page. The -esc form of a variable is the same value made safe for a URL.

The parameter names on the left of each = are the ones Kiwire's MikroTik login config expects. Don't rename them:

Parameter	RouterOS variable	What Kiwire uses it for
mac	$(mac-esc)	The guest's device. Required
ip	$(ip)	The guest's IP address. Used by zone rules on IP
link-login	$(link-login-only-esc)	Where Kiwire sends the login back to. Required
link-orig	$(link-orig-esc)	The page the guest first asked for. Kiwire sends it back as dst
nasid	$(identity-esc)	The router's Identity. Required, and it must be registered in Kiwire
vlan	$(vlan-id)	Optional. For zone rules on VLAN
error	$(error-esc)	Optional. When the router rejects a login it shows this page again with an error, and Kiwire shows the error instead of logging in again automatically

Two more parameters are read if present. RouterOS has no variable for them, so type the value into both URLs yourself:

• &ssid=<your-SSID>: for zone rules on SSID.
• &zone=<name>: for zone rules on Controller Zone, for example one value per HotSpot server on the same router (give each server its own profile and html-directory).

Leave the router's other pages (alogin.html, status.html, logout.html and so on) as they are.

Upgrading or resetting the HotSpot

A RouterOS reset, or running /ip hotspot setup again, can put the default login.html back. Check the page after any change to the HotSpot.

6. Walled garden: let guests reach Kiwire before login

/ip hotspot walled-garden ip add action=accept dst-host=<kiwire-host>
/ip hotspot walled-garden add action=allow dst-host=<kiwire-host>
/ip hotspot walled-garden ip add action=accept dst-host=fonts.googleapis.com
/ip hotspot walled-garden ip add action=accept dst-host=fonts.gstatic.com

WinBox/WebFig: IP › Hotspot › Walled Garden and Walled Garden IP List.

The portal is served over HTTPS, which the HotSpot's HTTP walled garden cannot see into, so Kiwire must be in the IP walled garden (the first line). The second line covers plain HTTP. Add anything else your portal pages load: social sign-in, payment pages, reCAPTCHA or external images. See Walled garden and redirect for the list. RADIUS itself goes from the router to Kiwire, so it does not need a walled-garden entry.

7. Optional: allow router rules from Kiwire

The Router rules (MikroTik) tab of Kiwire's Portals › Captive Portal › Bypass Devices can let a device (a smart TV, a printer, a point-of-sale terminal) straight through the HotSpot without a login, and optionally cap its speed. Kiwire does this by logging in to the router's API and adding an IP binding of type bypassed (plus a simple queue named BYPASS_… when you set a speed).

Kiwire uses the plain API service on TCP 8728. The encrypted API service (8729) is not supported.

/ip service set api disabled=no port=8728 address=<allowed-address>
/user group add name=kiwire-api policy=read,write,api
/user add name=kiwire group=kiwire-api password=<api-password>

• Set address= to limit who can reach the API (ask Synchroweb support for the address Kiwire connects from). Don't leave port 8728 open to the whole internet: it is not encrypted.
• Use a separate user for Kiwire, not admin.
• Enter the user name and password in the router's record in Kiwire (see below).
• A speed limit needs an IP address on the bypass entry. RouterOS queues work on IP addresses, so for an entry with only a MAC address Kiwire adds the bypass but no speed limit.

Skip this step if you don't use router rules. For most TVs and streaming sticks, approved devices (step 8) are the simpler choice: nothing is written to the router, and a device can follow a guest's account.

8. Optional: MAC login for approved devices

With MAC login on, the HotSpot asks Kiwire about each device's MAC address before showing the login page. A device on Kiwire's Approved devices list (Portals › Captive Portal › Bypass Devices) is let straight through; every other device gets the login page exactly as before. See Letting TVs and other devices skip the portal for the Kiwire side.

/ip hotspot profile set [find name=<hotspot-profile>] \
    login-by=mac,http-pap,http-chap,cookie mac-auth-mode=mac-as-username-and-password

WinBox/WebFig: IP › Hotspot › Server Profiles, open the profile, Login tab: tick MAC next to the methods already ticked, and set MAC Auth. Mode to MAC as username and password.

• Keep http-pap (and the other methods) in login-by. MAC login is tried first; the login page still serves every device that isn't approved.
• mac-as-username-and-password sends the device's MAC address as both the username and the password, which is what Kiwire expects. Leave MAC Auth. Password empty.
• No API access, IP binding or queue is needed: the device's speed and limits come from the profile in Kiwire, the same way as for a guest.
• Approved devices must also be switched on in Kiwire (the switch at the top of the Approved devices tab).

RouterOS v6

The commands above are written for RouterOS v7. The same menus and property names exist on v6, so the script also runs there. One difference matters: device bypass needs v6.43 or later, because Kiwire logs in to the API the way RouterOS has done since 6.43 and older versions refuse that login. If you are unsure about a command on an older router, check it in WinBox under the menu of the same name.

In Kiwire

1. Admin › System › Device Controller → add a record:
   • Vendor: Mikrotik
   • Identity: exactly the router's System Identity (<identity>)
   • Shared Secret Key: <shared-secret>, the same as on the router (64 characters or fewer)
   • Under Advanced Configuration:
     • IP Address: the address Kiwire can reach the router on. Needed for disconnects, live changes and bypass. Leave it empty if the router isn't reachable from the internet.
     • COA Port: 3799, or whatever you set with /radius incoming.
     • Username / Password: the API user from step 7. Only needed for router rules.
2. Check the redirect parameters. The MikroTik login config is maintained by Synchroweb and already matches the page in step 5. See The redirect and the login config for what each parameter does.
3. Zones and journeys. Under Portals › Captive Portal › Zones Mapping, add a zone rule on NAS ID = the router's Identity (or on VLAN, SSID, IP or Controller Zone), and give the zone a journey. See Controllers and zones and Designers and journeys.
4. Profiles. Speed and data limits come from the guest's profile (Account › Profiles). See "Speed and data limits" below.

Speed and data limits

Kiwire sends these to the router when a guest logs in:

• Time: Session-Timeout (the time left on the account) and Idle-Timeout.
• Speed: Mikrotik-Rate-Limit as <upload>/<download> in bits per second, when the profile has both set. RouterOS creates a queue for the guest from it. (The standard WISPr-Bandwidth-Max-Up and -Down are sent too.)
• Data cap: Mikrotik-Total-Limit and Mikrotik-Total-Limit-Gigawords: the quota left on the account, upload and download together. The first carries the part under 4 GiB, the second the number of whole 4 GiB blocks, so caps of 4 GiB and more are sent correctly. RouterOS logs the guest out when it is used up. Kiwire does not send separate upload or download caps (Mikrotik-Recv-Limit / Mikrotik-Xmit-Limit).
• Anything you add under the profile's Custom attributes. The MikroTik template there offers other MikroTik attributes, for example an address list or a HotSpot user group.

When you change a logged-in guest's profile (by hand, or when the account moves to its next profile automatically), Kiwire sends a CoA request to IP Address : COA Port with the new profile's speed (Mikrotik-Rate-Limit), Session-Timeout, Idle-Timeout and data cap. The new speed applies at once. RouterOS ignores the standard WISPr speed attributes on a live change, which is why Kiwire sends the MikroTik one.

Test it

1. Portals › Troubleshoot › Controller Test → Start Capture, then connect a phone to the guest network and open any http:// page. Check that the hit shows:
   • mac, ip, link-login and nasid filled in;
   • the controller ID registered to your organisation. If nothing appears, the router isn't forwarding to Kiwire: check login.html and the walled garden. Before the router's record exists, add the Test URL's kw_ct=… value to both URLs in login.html (as &kw_ct=… at the end) so the capture can see it, and remove it afterwards.
2. Log in on the portal as a guest. On the router, /ip hotspot active print should list the guest, and /log print where topics~"radius" or topics~"hotspot" shows rejections.
3. Reporting › Login › Active Session: the session should appear, and its usage should update at each accounting interval.
4. If you use disconnects: disconnect the session from Kiwire and check it disappears from /ip hotspot active print. If it stays, check the COA Port, the firewall and the /radius entry for <coa-source-ip> (step 3).
5. If you use approved devices: approve a TV in Kiwire and switch approved devices on, then switch the TV off and on. It should get online without the login page, appear in /ip hotspot active print with its MAC address as the user, and show a Last connected time on the Approved devices tab. A TV not yet approved shows up under Recently seen, not approved on the same tab.

Upgrading from an older setup

Routers already working with Kiwire need no change to their login page, RADIUS entry or profile. Since late September 2026 Kiwire really sends Disconnect requests when an account expires, runs out of time or data, or exceeds its device limit with auto-disconnect on (before, those guests stayed online until the router's own limits ended the session). For these to work, check on each router that /radius incoming is enabled on the COA Port, that the router has a /radius entry for <coa-source-ip> (step 3), and that the record's IP Address is filled in.

Limits to know

• Allow up to an hour after adding the router's record, or changing its secret, before RADIUS logins are accepted. See Allow up to an hour for a new controller.
• Routers behind one public IP share a secret. If several routers reach Kiwire from the same internet address (a shared uplink, a carrier NAT), give all their records the same Shared Secret Key.
• Identity is matched exactly (upper/lower case aside). A router renamed with /system identity stops working until the record in Kiwire is renamed too.
• HTTP PAP must stay enabled on the HotSpot profile. A profile set back to CHAP only (http-chap,cookie, the RouterOS default) rejects every login.
• Data caps on a live change. RouterOS's documentation lists speed, time and the separate upload/download limits as changeable during a session, but not the combined total limit that Kiwire uses. A new data cap from a profile change may only apply from the guest's next login.
• A live change sends the new profile's full limits, not what is left of them.
• Device limit. A device that logs in again (a re-login or a roam between access points) does not count against the account's device limit.
• Approved devices need mac in login-by with mac-auth-mode=mac-as-username-and-password (step 8). With MAC login on, the router asks Kiwire about every device as it joins; devices that aren't approved go on to the login page.
• Router rules need the plain API on port 8728, the router's IP Address and the API user on the record. The error "Could not connect to the controller API (check IP, credentials and that API port 8728 is enabled)" means one of those three is wrong or blocked. A speed limit on a MAC-only bypass entry is not applied (step 7).
• Browser warnings on the hand-back. The portal is HTTPS and the router's login address is normally plain HTTP. If guests see a "form is not secure" warning after logging in, give the HotSpot an SSL certificate and add https to login-by (step 4).

Vendor reference

• RouterOS: HotSpot (captive portal): server profiles, login-by, use-radius, walled garden, IP bindings.
• RouterOS: HotSpot customisation: login page variables and the -esc escaping.
• RouterOS: RADIUS: /radius, /radius incoming, MikroTik attributes and what CoA can change.
• RouterOS: API: the API service used for device bypass.