HotSpot instance configuration defines how mbox hotspot access controller handles user traffic when it comes into HSG. We can configure different instances for different networks (or different SSID), to control different accesses, and enforce different user experiences etc. Each instance works like a virtual hotspot access controller.

There are a few key concepts we need to understand:

• Each hotspot instance maps to a combined set of LANIF and WANIF interfaces.

  • A LANIF interface is the incoming interface where user client's traffic is entering into mbox (and try to pass through mbox HSG).

  • A LANIF interface can be a physical interface or VLAN interface, and it represents a client network. If we need to support multiple networks, we configure VLANs on a physical LAN interface, in this case each LANIF is a VLAN interface. NOTE: when VLAN is configured, the switch-port connecting to this physical LAN interface must be configured as trunk port (with 802.1Q VLAN tagging).

  • A LANIF belongs a hotspot instance and is unique to each hotspot instance.

  • A WANIF interface is the outgoing interface when client's traffic leaves mbox.

  • A WANIF can be shared by many instances, so we can configure multiple instances/LANIF to share the same WANIF (eg. same ISP link).

• Each hotspot instance also runs as a DHCP server for its LANIF instance. The built-in hotspot DHCP process will issue clients IP addresses ec. If there's another "dhcp-server" setting under the LANIF interface, it it a MUST to remove it. Otherwise there'll be two DHCP processes issuing IPs to the clients and it will cause conflicts.

• A captive portal (or login page) is needed for each instance. The portal contents can be either locally hosted on HSG or externally hosted on a cloud HSG. HSG comes with a default set of portal templates for customers to choose to fit into their specific requirement, and the CMS allows web-based portal customization, eg. changing logo, images, background, sample text etc.

In below diagram:

• interface vlan10 is the LANIF for HOTEL instance (vlan10 is mapped to mbox@HOTEL SSID)

• interface vlan20 is the LANIF for ADS instance (vlan20 is mapped to mbox@ADS SSID)

• interface vlan30 is the LANIF for TVC instance (vlan30 is mapped to mbox@TVC SSID)

• eth0 is connecting to ISP, where the user traffic exits local network and out to public Internet. so eth0 is WANIF for all other instances.

CONFIGURE HOTSPOT INSTANCE

mbox HotSpot instance configurations are done using CLI, through local console, or SSH. User related information, eg. UAM/RADIUS and portals/CMS configurations are configured through mbox GUI, these settings are covered in separate sections.

To configure instance settings, please follow below guides.

• First we need to configure base network settings for each LANIF (instance base network setting)

• then configure instance settings using below commands:

Within each LANIF instance, below are compulsory commands:

• hotspot-portal <portalurl> key <portalkey> This command configures the user login portal URL, eg. https://splash.ransnet.com/demo/hotel/login.php.

If key <portalkey> is specified, it must match the same pre-shared key set on the CMS portal setting. Refer to hotspot portal config for details.

NOTE: if the portal contents are hosted locally within HSG, we need to configure DNS rewrite (see DNS rewrite), so that the <portalurl> is resolved back to HSG local loopback address. If the <portalurl> is externally hosted, it's important to make sure the URL is accessible and is added into bypass-dst/whitelist list.

• radius-server <server1> <radiuskey> <server2> This command specifies how HSG wants to authenticate user access. We can either use HSG local RADIUS, or point to external RADIUS servers. When using external RADIUS servers, we can optionally point to two servers (<server2> must use the same radiuskey as server1). If not configured, by default all instances will use local RADIUS server with pre-shared key as testing123 (HSG RADIUS by default is configured with localhost as radius client using pre-shared key testing123).

NOTE: when we use external RADIUS server, we must define HSG IP as RADIUS client (or NAS) on the remote server with the same radiuskey. This setting is instance specific, eg. we can configure different RADIUS server for different hotspot instances if needed.

• start/stop Each instance hotspot service needs to be explicitly started, or can be stop individually. When we change any instance settings, the instance hotspot service has to be restarted (stop then start again).

Below are important optional commands (if not configured, default settings apply).

• hotspot-portal external This command disables local portal access and must be used together with "hotspot-portal <external_portal_url>" to redirect clients to an external portal for login. By default, HSG assumes using local portal for user login, and automatically opens http/https access to LAN users (so that they can access to HSG local portal during login). But this may not always be desirable because it also opens access to clients to browse to HSG GUI locally, especially when we're using external portal, this command is recommended to harden unwanted accesses to local HSG services.

• hotspot-wan <WANIF> This command specifies the outbound interface where user traffic exits from mbox HSG. If it's not configured, it's default to eth0. But sometimes when we may use bonding or bridge or other Ethernet interface as WANIF, it's necessary to explicitly change to the actual interface name (if you are not sure about the exact interface name, use "show interface brief " to find out).

NOTE: if HSG is also used as a perimeter gateway that needs to perform NAT/PAT, you will configure SNAT (firewall-snat xx overload outbound <WANIF>)

• hotspot-server <serverip> ports <port1> <port2> This command configures the hotspot instance server IP, which is clients default gateway. Each instance must run as a unit process therefore requires unique set of port numbers. By default, HSG will use the LANIF primary IP address and randomly generate unique port numbers for each instance. But sometimes, we may need to explicitly configure a unique IP for hotspot-server (different from LANIF IP). For example, in a HA configuration (two HSG, active/standby), we configure two different LANIF IP on each unit, then use hotspot-server command to configure another VIP as the instance hotspot-server IP, so that the hotspot-server IP is the same for both units.

NOTE: When hotspot service is started for a instance, HSG will remove the LANIF IP address and create a virtual tunnel interface which binds to the LANIF IP address (or hotspot-server IP); when hotspot service is stopped, the tunnel interface will be removed and HSG will add the original IP address back LANIF.

• hotspot-splash <splashurl> By default, <splashurl> is the same as <portalurl>.But if <portalurl> is hosted on 3rd-party web server, It is necessary to explicitly configure splash portal URL, for example https://splash.ransnet.com/splash/ransnet.php

• hotspot-access <acl> <permit/deny> <poto,src,dst> By default, once a user is authenticated, he/she will have full access across this instance (permit all outbound from WANIF). But sometimes, we may want to block/deny certain access based on specific security policies. So we use this command to apply firewall ACL rules within the instance.

NOTE: unlike normal firewall-access rules (which has an implicit deny-all), there's an implicit permit-all within each hotspot instance.

Below is an example of blocking email and ftp access and permit everything else.

• client-local-access <yes/no> By default, mbox blocks users access to other networks (no inter-instance access is allowed). But sometimes, we may need to permit access to printers in other networks etc, so we will use this command to enable inter-instance access.

• client-network <subnet> <netmask> This command refers to the permitted client networks within this instance. By default mbox will generate client network from the LANIF setting (assume a flat client network, same as the LANIF network); however, if there's a layer-3 switch behind mbox, there could be more subnets in addition to the LANIF network, so we need to explicitly use this command to configure a client network that covers all permissible networks.

NOTE: this command is compulsory if you have clients pre-configured with static IP (eg. other 3rd-party wireless controller IP), so that the range here will exclude the static clients. In addition, you will use client-static command to identify the static clients.

• client-static <start-of-static-range> <netmask> When mbox functions as a DHCP servers, it expects all the clients to have IP addresses coming from its local DHCP range. But sometime, we may have some hosts with static IP addresses, or addresses signed by other DHCP servers, eg. 3rd-party WLC IP addresses. We use client-static command identify these hosts and allow them hotspot access. This feature is disabled by default.

• client-dhcp <start-of-dhcp-range> <netmask> lease <lease-time> By default DHCP is enabled for each instance, and mbox will assign from the 1st available IP, eg. if the interface address is 192.168.1.1/24, the first client will be getting 192.168.1.2/24 and so on. We can use this command start a different DHCP range to issue to user clients.

• client-dhcp-dns <dns1> <dns2> When mbox runs as a DHCP server, this commdn includes name-server in dhcp offering to client. If not explicitly configured, default google DNS (8.8.8.8, 8.8.4.4) will be issued.

• client-dhcp-helper <dhcpserver1,dhcpserver2> This command enables mbox as a DHCP relay agent for this instance. It relays user DHCP request to upstream DHCP server (therefore DHCP server for local instance will be disabled). If multiple DHCP servers are specified (seperated by comma), mbox will forward user DHCP requests to all servers, then user device will ack and select one of the DHCP server offers. By default, DHCP helper is disabled. 

NOTE: this command must be used together with client-static command, since we're now using external DHCP server to assign clients IP.

Below are optional commands. These settings can be configured via RADIUS (under the "Access info" tab, under username or profile). 

NOTE: CLI settings are "global" within each instance, If both CLI and RADIUS are configured, RADIUS setting will over-write CLI settings.

• client-bandwidth <download> <upload> This commands sets maximum download/upload bandwidth per host/device (in bps). If no RADIUS setting per user, and this command is not set, there's no speed limit per user/host.

• client-timeout <idletimeout> <sessiontimeout> Idle time is the inactivity time, after which user session will be cleared. Session timeout is the absolute session time, after which user session will be cleared even if the user is actively using (user will be forced to login out). When either timeout happens (idletime or sessiontime), user will need to login again. This setting can also be set in RADIUS.

• redirect-url <http://www.ransnet.com> Redirect client browse to a specific URL upon login. This can be a landing page hosted on HSG or an external website URL (eg. customer promotional web page). This setting can also be set in RADIUS.