Kiwire docs

Appearance

Ruckus ​

How to connect Ruckus SmartZone (SZ / Virtual SmartZone) Hotspot (WISPr) WLANs to Kiwire, and the status of the other Ruckus entries.

Device type in KiwireRuckus AP
Redirect URLhttps://<kiwire-host>/login/ruckus_ap (the WISPr portal's external Logon URL)
RADIUSauth 1812 / acct 1813 (UDP)
Identity must equalthe AP MAC in the redirect (mac), and the NAS-Identifier SmartZone sends in RADIUS
Disconnect / live changes (CoA)standard RADIUS CoA / Disconnect to the record's IP Address, port 3799, once dynamic authorization is enabled on SmartZone
Data capstime limits only (Session-Timeout)

Which entry to pick ​

Device type in KiwireStatusUse it for
Ruckus APAvailableSmartZone / Virtual SmartZone Hotspot (WISPr) WLANs with an external logon page. Despite the name, this is the entry for SmartZone-managed APs.
Ruckus vSZAvailable through SynchrowebKiwire logs the guest in on SmartZone itself, through its Northbound Portal Interface. See Ruckus vSZ and SCG.
Ruckus SCGAvailable through SynchrowebThe same for SmartCell Gateway.

Ruckus Unleashed and ZoneDirector hotspots expect the login back at a different address (/login on port 9997) from the one Kiwire uses, so the Ruckus AP entry does not cover them. Contact Synchroweb before deploying either.

How a login works ​

How a guest logs in through Ruckus SmartZone and Kiwire The guest joins the Wi-Fi and opens a page. The Ruckus SmartZone device redirects the browser to Kiwire at /login/ruckus_ap. Kiwire shows the portal and the guest signs in. Kiwire hands the login back to the device: POST to sip:9997 hotspotlogin. The device then asks Kiwire over RADIUS, identifying itself with NAS-ID; AP mac for the portal. Kiwire accepts and returns the profile's limits, the device lets the guest out and starts sending accounting. Guest devicephone, laptopRuckus SmartZoneHotspot (WISPr) WLANKiwireportal + RADIUSInternetafter acceptance1 JOINS THE SSID, OPENS A PAGE2 REDIRECT TO/login/ruckus_ap3 PORTAL PAGE — THE GUEST SIGNS IN4 HAND-BACK:POST to sip:9997 hotspotlogin5 RADIUS REQUEST — IDENTITY =NAS-ID; AP mac for the portal6 ACCEPT + PROFILE LIMITS7 GUEST IS LET OUT; ACCOUNTING STARTS
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).
  1. The AP sends the guest to Kiwire with the SmartZone address (sip), the AP MAC (mac), the guest's MAC and IP (client_mac, uip), the original page (url), and proxy, ssid and vlan.
  2. After the portal, the guest's browser posts the username and password, with the guest's MAC, IP, original page and proxy, to http://<sip>:9997/SubscriberPortal/hotspotlogin — SmartZone's documented WISPr login address.
  3. SmartZone checks the credentials against Kiwire over RADIUS and lets the guest out.

Before you start ​

From Kiwire:

  • the RADIUS server address shown in the Setup Guide checklist ("Before you add your controller" › "RADIUS Authentication & Accounting");
  • a shared secret of at most 64 characters;
  • <kiwire-host>.

On SmartZone: admin access to the zone, the guest WLAN, and the MAC address of every AP that serves it.

On the controller ​

Menu names and commands vary between firmware versions; the values are what matter. Steps follow Ruckus' SmartZone administrator guide and Hotspot WISPr reference guide.

  1. RADIUS: add Kiwire as an authentication service (<radius-server-ip>, port 1812, <shared-secret>) and an accounting service (<radius-server-ip>, port 1813, same secret).
  2. Hotspot (WISPr) portal (Services & Profiles › Hotspots & Portals › Hotspot (WISPr) › Create):
    • Logon URL = External, https://<kiwire-host>/login/ruckus_ap;
    • Redirect unauthenticated user: to the original URL, or a start page of your choice;
    • Walled Garden: <kiwire-host>, fonts.googleapis.com, fonts.gstatic.com and anything your portal design loads. See Walled garden and redirect.
  3. WLAN: type Hotspot (WISPr), with the portal from step 2 and the authentication and accounting services from step 1.
  4. NAS ID on the WLAN's RADIUS options: choose AP MAC so the RADIUS side matches the redirect, or a user-defined name that you register as an extra record (see In Kiwire).
  5. Guest MAC and IP encryption. SmartZone encrypts the guest's MAC and IP in the redirect by default. Kiwire does not decrypt them, so the guest's device shows up in Kiwire under a long encoded value instead of its MAC. Ruckus documents no GUI switch for this; a SmartZone CLI setting (no encrypt-mac-ip) can turn it off, depending on the SmartZone version. Check this with Controller Test before rollout and contact Synchroweb if the MAC arrives encoded.

In Kiwire ​

  1. System › Device Controller › add one record per AP:
    • Vendor: Ruckus AP.
    • Identity: the AP MAC exactly as it arrives in mac (Controller Test shows the format).
    • Shared Secret Key: <shared-secret> — the same on every record.
    • Advanced Configuration › Network Configuration: IP Address = the SmartZone address Kiwire should send disconnects to, COA Port = 3799.
  2. If the NAS-Identifier SmartZone sends in RADIUS is not exactly the same string as mac (for example dashes instead of colons, or a user-defined name), add one more record with that value as Identity and the same secret; see Identity and virtual NAS. Each record counts toward your licence's device limit.
  3. Check the redirect parameters with Redirect and login config: Kiwire reads client_mac, uip, url, sip, mac, vlan, ssid and proxy.
  4. Add a zone rule and journey: Controllers and zones, Portal designer.

Test it ​

  1. Portals › Troubleshoot › Controller Test › Start Capture, connect a phone, and check that sip, mac and client_mac arrive, that client_mac looks like a MAC address, and that the AP shows as registered.
  2. Log in as a real guest; the phone should go online after the page hands back to SmartZone.
  3. Reporting › Login › Active Session lists the guest.

Limits to know ​

  • No Ruckus data-cap attribute: profile quotas are enforced by time only.
  • Disconnects and profile changes are sent as standard RADIUS Disconnect/CoA to the record's IP Address; enable dynamic authorization on SmartZone to use them.
  • The Identity must match the separators exactly: aa:bb:cc:dd:ee:ff and AA-BB-CC-DD-EE-FF differ in separators and are different values (upper or lower case alone does not matter).

Ruckus vSZ and SCG ​

With these entries Kiwire's server logs the guest in on SmartZone directly, through SmartZone's Northbound Portal Interface (NBI), instead of sending the browser back to the AP. Synchroweb sets up the first site with you, because Kiwire's server has to reach your SmartZone.

How a guest logs in through Ruckus SmartZone and Kiwire The guest joins the Wi-Fi and opens a page. The Ruckus SmartZone device redirects the browser to Kiwire at /login/ruckus_vsz. Kiwire shows the portal and the guest signs in. Kiwire hands the login back to the device: server-side NBI Login on :9080. The device then asks Kiwire over RADIUS, identifying itself with AP MAC (mac) / NAS-ID. Kiwire accepts and returns the profile's limits, the device lets the guest out and starts sending accounting. Guest devicephone, laptopRuckus SmartZonevSZ / SCG, NBI loginKiwireportal + RADIUSInternetafter acceptance1 JOINS THE SSID, OPENS A PAGE2 REDIRECT TO/login/ruckus_vsz3 PORTAL PAGE — THE GUEST SIGNS IN4 HAND-BACK:server-side NBI Login on :90805 RADIUS REQUEST — IDENTITY =AP MAC (mac) / NAS-ID6 ACCEPT + PROFILE LIMITS7 GUEST IS LET OUT; ACCOUNTING STARTS
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).

On SmartZone (menu names vary by SmartZone version):

  1. Enable the Northbound Portal Interface and set its password.
  2. On the guest WLAN, set the external portal (logon) URL to https://<kiwire-host>/login/ruckus_vsz (/login/ruckus_scg for a SmartCell Gateway), and point RADIUS authentication and accounting at Kiwire as in On the controller.
  3. Turn off encryption of the client MAC and IP in the redirect (no encrypt-mac-ip, where your version offers it), so Kiwire records the guests' real MAC addresses. Logins also complete with it on.
  4. Allow Kiwire's server to reach SmartZone's NBI on port 9080. The address Kiwire connects from is shown at the top of System › Device Controller (Disconnect / CoA requests come from).

In Kiwire, on each AP's Device Controller record, or once on a record with the Identity Ruckus_Controller:

  • Vendor: Ruckus vSZ (or Ruckus SCG).
  • Identity: the AP MAC exactly as SmartZone sends it in the redirect (mac); Controller Test shows it.
  • IP Address: SmartZone's NBI address (add :port if it isn't 9080).
  • Password (under Advanced Configuration): the Northbound Portal Interface password.

Test it: run Controller Test, sign in as a guest, and check the session under Reporting › Login › Active Session. If the portal shows an error after sign-in, check the NBI password and that port 9080 is reachable.

Vendor reference ​

Last updated:

Kiwire platform documentation

Synchroweb