Hotspot Instance¶
A hotspot instance is a virtual hotspot access controller that handles traffic from a specific client network (LANIF). Each instance maps to a LAN interfaces (LANIF), with independent configuration for authentication, portal, DHCP, and access policies. Multiple instances allow HSG to serve different client networks (or SSIDs) with different user experiences and security policies.
Core Concepts¶
LANIF (LAN Interface)¶
A LANIF is the incoming interface where client traffic enters HSG:
- Can be a physical interface or VLAN interface
- Represents a client network (e.g., vlan10 for hotel guests, vlan20 for visitors)
- Each LANIF belongs to exactly one hotspot instance
- When VLANs are configured, the switch port connecting to the physical LAN interface must be configured as a trunk port with 802.1Q VLAN tagging
Architecture Example¶
| Instance | LANIF | SSID | |---|---|---|---| | HOTEL | vlan10 (172.16.10.0/24) | mbox@HOTEL | | ADS | vlan20 (172.16.20.0/24) | mbox@ADS | | TVC | vlan30 (172.16.30.0/24) | mbox@TVC |
DHCP and Portal¶
Each hotspot instance provides:
- DHCP Server — Issues IP addresses to client devices (unless DHCP relay is configured)
- Captive Portal — Login page, either locally hosted on HSG or externally hosted
Note
If the LANIF interface already has a dhcp-server configured, do NOT enable DHCP within the hotspot instance. Running two DHCP processes on the same network causes conflicts.
Configuration¶
Hotspot instance configuration is done via GUI or CLI. User authentication (RADIUS/UAM) and portal/CMS settings are covered in separate sections.
Step 1: Create Hotspot Instance¶
GUI Configuration:
Navigate to Device Settings → Security → Hotspot, then click Add Hotspot:
CLI Configuration:
mbox# configure
mbox(config)# security hotspot <LANIF>
Info: Client gateway is 172.16.10.1
Info: Client network is 172.16.10.0
Info: Client netmask is 255.255.255.0
Compulsory Commands¶
These settings must be configured for each instance to function:
hotspot-portal¶
Configure the user login portal URL:
Parameters:
<url>— Portal URL (e.g.,https://splash.ransnet.com/demo/hotel/login.php)<preshared-key>— Must match the key set in the portal CMS
Important:
- Local portal: Configure DNS rewrite so the portal URL resolves to HSG's loopback address
- External portal: Ensure the URL is accessible and added to the firewall bypass/whitelist
radius-server¶
Configure the RADIUS server for user authentication:
Parameters:
<server1>— Primary RADIUS server IP<key>— RADIUS pre-shared key (must match HSG's RADIUS client configuration on the remote server)<server2>— Optional secondary server (uses same key as server1)
Default: If not configured, uses HSG's built-in RADIUS server.
Important: When using external RADIUS servers, register HSG's IP as a RADIUS client (NAS) on the remote server with the matching preshared key.
start / stop¶
Manage the hotspot service for this instance:
Important: After any configuration change, restart the hotspot service (stop then start).
Important Optional Commands¶
Use these to customize instance behavior. Default settings apply if not configured.
hotspot-portal external¶
Disable local portal and require external portal login:
By default, HSG opens HTTP/HTTPS access to clients for local portal access. This command hardens security by disabling access to HSG services (especially the GUI).
hotspot-server¶
Configure the hotspot server IP and ports:
By default, HSG uses the LANIF primary IP and auto-generates unique port numbers. Use this when:
- HA/failover setup: Configure a shared VIP so both active/standby units use the same hotspot server IP
Note
When hotspot service starts, HSG removes the LANIF IP and creates a virtual tunnel interface bound to the hotspot server IP. The original LANIF IP is restored when the service stops.
hotspot-splash¶
Configure the splash/landing page URL:
By default, same as the portal URL. Use when the portal is on a third-party server and you want a different splash page.
hotspot-access¶
Apply firewall ACL rules within the instance:
By default, authenticated users have full outbound access. Use this to restrict certain traffic (e.g., block email, FTP).
Example: Block email and FTP:
hotspot-access 10 deny tcp dport 20
hotspot-access 11 deny tcp dport 21
hotspot-access 12 deny tcp dport 110
hotspot-access 13 deny tcp dport 25
Note
Unlike normal firewall rules (implicit deny-all), hotspot instances have implicit permit-all for authenticated users. Explicit deny rules block specific traffic.
Client Network Configuration¶
client-network¶
Define the permitted client networks within this instance:
By default, HSG generates the client network from the LANIF setting. Use this to include additional subnets (e.g., behind a Layer 3 switch).
Compulsory if: Clients have static IPs (e.g., from a third-party controller). Configure the range to exclude static clients, then use client-static to identify them.
client-static¶
Allow static-IP devices to access hotspot:
When HSG runs DHCP, it expects all client IPs from its DHCP pool. Use this to whitelist devices with static IPs or addresses from other DHCP servers (e.g., third-party WLC).
Default: Disabled
client-local-access¶
Allow clients to access other hotspot instances:
By default, clients cannot access other networks (no inter-instance access). Use yes to allow cross-instance access (e.g., printer in another VLAN).
DHCP Configuration¶
client-dhcp¶
Configure the DHCP address pool:
By default, HSG assigns from the first available IP (e.g., 192.168.1.1/24 → first client gets 192.168.1.2). Use this to specify a different range.
client-dhcp-dns¶
Configure DNS servers issued via DHCP:
By default: 8.8.8.8 (Google DNS)
client-dhcp-helper¶
Enable DHCP relay (forward to upstream DHCP server):
Disables local DHCP and relays requests to upstream servers. If multiple servers specified, clients select from all offers.
Compulsory with: client-static (since external DHCP now assigns IPs)
Per-User / Per-Device Optional Commands¶
These settings can be configured globally (CLI) or per-user/connection. If both are configured, RADIUS settings override CLI settings.
client-bandwidth¶
Limit download/upload bandwidth per device:
If not configured, no speed limit applies.
client-timeout¶
Set idle and session timeouts:
idle-seconds— User session expires after inactivitysession-seconds— User session expires after absolute time (even if active)
When either timeout expires, user must log in again.
redirect-url¶
Redirect user to a landing page after login:
Can be a local HSG-hosted page or external URL (e.g., promotional website).
Bypass/Whitelist Configuration¶
Allow user access without authentication based on specified criteria.
Destination Domain¶
Permit access to specific domains (and all subdomains):
Important: Prefix each domain with a dot (.) so subdomains are automatically included. For example, .ransnet.com permits portal.ransnet.com, www.ransnet.com, and all other subdomains.
Destination Domain List¶
Similar to Destination Domain, but allows bulk domain imports from a list file.
Destination IP / URL¶
Permit access to specific URLs, IP addresses, or subnets:
Supports FQDNs, URLs, individual IPs, and subnet ranges (CIDR notation).
Source MAC (Entry)¶
Permit access based on device MAC address:
Devices with these MAC addresses bypass authentication.
Source IP / Subnet (Entry)¶
Permit access based on client source IP or subnet:
Clients with these IPs or from these subnets bypass authentication.
Source MAC (RADIUS Setting)¶
Permit access based on RADIUS MAC address authentication. Register device MAC addresses in RADIUS user database via User Management → Import.
Session Persistence¶
Seamless Re-login¶
Enable seamless session re-login after captive portal login. Clients don’t need to re-authenticate when returning to the hotspot.
Session Duration¶
Control how long user sessions remain valid:
- Since first login — Keep session active for N days from initial login (then re-authenticate)
- Since last login — Keep session active for N days from last use (sliding window)
CLI Example: Complete Instance Configuration¶
security hotspot vlan10
hotspot-portal https://splash.ransnet.com/hotel/login.php key hotel123
radius-server 192.168.1.100 radius-key-123
client-dhcp 172.16.10.10 255.255.255.0 lease 3600
client-dhcp-dns 8.8.8.8 8.8.4.4
client-timeout 600 3600
client-bandwidth 10000000 5000000
start
Verification and Troubleshooting¶
Use these commands to verify hotspot instance configuration and diagnose issues:
show security hotspot¶
Display all configured hotspot instances:
Output shows instance name, LANIF, WANIF, DHCP settings, portal URL, and service status (running/stopped).
show security hotspot clients¶
List all connected clients for a specific instance:
Output shows client MAC address, assigned IP, authentication status, bandwidth usage, and session duration.