Scroll to navigation

OPENNDS(1) openNDS OPENNDS(1)

NAME

opennds - opennds Documentation

openNDS is a high performance, small footprint Captive Portal, offering by default a simple splash page restricted Internet connection, yet incorporates an API that allows the creation of sophisticated authentication applications.

It is a fork of the NoDogSplash project that in turn was derived originally from the codebase of the Wifi Guard Dog project.

openNDS is released under the GNU General Public License.


The following describes what openNDS does, how to get it and run it, and how to customize its behavior for your application.

Contents:

OVERVIEW

openNDS (NDS) is a high performance, small footprint Captive Portal, offering by default a simple splash page restricted Internet connection, yet incorporates an API that allows the creation of sophisticated authentication applications.

Captive Portal Detection (CPD)

All modern mobile devices, most desktop operating systems and most browsers now have a CPD process that automatically issues a port 80 request on connection to a network. NDS detects this and serves a special "splash" web page to the connecting client device.


Provide simple and immediate public Internet access

NDS provides two selectable ready to run methods.
  • Click to Continue. A simple "Click to Continue" dynamic splash page sequence requiring a client user to accept Terms of Service before continuing to access the Internet (default). Basic client device information is recorded in a log file.
  • username/email-address login. A simple dynamic splash page sequence that requires the client user to enter their username and email-address before accepting the Terms of Service. A welcome page and landing page that can carry an information or advertising payload are served to the client in sequence. Client user and client device information is recorded in the log file. (This mode is selected in the configuration file)

Both these modes are generated using default ThemeSpec script files. These ThemeSpec script files contain easy to edit html blocks, allowing basic content changes to be made very simply.

Modifying the content seen by users is a simple matter of editing the html blocks within the script file.

Additional more advanced ThemeSpec files are included and can also be enabled from the config file. These additional files make use of the custom_parameters, custom_images and custom_files config options. Form input fields and text comments can be added, and images and content blocks can be downloaded on demand from remote servers.





Write Your Own Captive Portal.

NDS can be used as the "Engine" behind the most sophisticated Captive Portal systems using the tools provided.
  • Forward Authentication Service (FAS). FAS provides pre-authentication user validation in the form of a set of dynamic web pages, typically served by a web service independent of NDS, located remotely on the Internet, on the local area network or on the NDS router.
  • PreAuth. A special case of FAS that runs locally on the NDS router with dynamic html served by NDS itself. This requires none of the overheads of a full FAS implementation and is ideal for NDS routers with limited RAM and Flash memory.
  • BinAuth. A method of running a post authentication script or extension program.



WHAT'S NEW? - CHANGELOG

opennds (9.7.0)

  • This version adds new functionality, and fixes some issues
  • Fix - syntax error (missing comma) in awk command in bash on generic Linux [bluewavenet]
  • Add - option to append serial number suffix to gatewayname [bluewavenet]
  • Add - block use of ip aliases on gateway interface [doctor-ox] [bluewavenet]
  • Fix - ndsctl json syntax error [bluewavenet]
  • Add - check for null variables in key value pairs in MHD callbacks [bluewavenet]
  • Fix - changed some notice messages into debug messages [bluewavenet]
  • Fix - possible return of incorrect pid [doctor-ox] [bluewavenet]
  • Fix - possible abiguities resulting in failure to parse parameters correctly [bluewavenet]
  • Fix - Remove deprecated get_client_token.sh [bluewavenet]
  • Fix - Prevent possible malformed mac address returned from dhcpcheck() [doctor-ox] [bluewavenet]



— Rob White <dot@blue-wave.net> Wed, 16 Mar 2022 15:54:29 +0000


opennds (9.6.0)

  • This version adds new functionality, and fixes some issues
  • Fix - correctly display return buffer in syslog [bluewavenet]
  • Add - use heap allocation for library call return buffer [bluewavenet]
  • Fix - OpenWrt, fhook request for fw3 [bluewavenet]
  • Add - spider remote urls before downloading [bluewavenet]
  • Add - OpenWrt, revert uncommitted uci updates at startup and shutdown [bluewavenet]
  • Fix - remove unnecessary flash writes and fix hosts updates [doctor-ox] [bluewavenet]
  • Add - Updated splash images [bluewavenet]
  • Add - OpenWrt makefile for nft or ipt dependencies [bluewavenet]
  • Fix - grep by word to prevent any ambiguity [doctor-ox] [bluewavenet]
  • Fix - ensure rate limiting is disabled if rate thresholds are set to zero [bluewavenet]
  • Add - querystring support for client status page [bluewavenet]
  • Add - Advanced/standard status page checkbox [bluewavenet]
  • Add - set default session timeout to 24 hours [bluewavenet]
  • Fix - potential buffer overflow [bluewavenet]
  • Fix - Restrict max packet limit to iptables maximum [bluewavenet]
  • Fix - descriptive labels on ndsctl status output [bluewavenet]
  • Add - update of README.md [bluewavenet]
  • Fix - Added required variable to FAS return string example documentation [dorkone]
  • Add - Default checkinterval set to 15 seconds [bluewavenet]
  • Fix - incoming and outgoing counters when unlimited bursting is enabled [bluewavenet]
  • Add - maximum bucket size configuration [bluewavenet]
  • Add - calculate moving average packet size for rate limiting [bluewavenet]
  • Add - some operational default values [bluewavenet]
  • Add - initial rate limits when unrestricted bursting is disabled [bluewavenet]
  • Add - Require clients to be in the dhcp database [bluewavenet]
  • Add - dhcpcheck library call [bluewavenet]
  • Fix - Remove trailing whitespace when getting clientaddress if client not active [bluewavenet]
  • Fix - Segfault when FAS fails to Return customstring [dorkone] [bluewavenet]
  • Add - Enable/Disable unrestricted bursting [bluewavenet]
  • Add - gatewayurl to querystring and use in place of originurl in FAS [bluewavenet]
  • Fix - more accurate debug message [bluewavenet]
  • Fix - Show packet rate correctly as packets per minute [bluewavenet]
  • Add - Report Packet Rate and Bucket Size in ndsctl status and json and status client page [bluewavenet]
  • Add - rate limit refresh to client limit rules [bluewavenet]
  • Fix - code readability [bluewavenet]
  • Fix - Documentation for data sent to Authmon Daemon [bluewavenet]
  • Add - Show unrestricted burst intervals in ndsctl status [bluewavenet]
  • Add - Set default bucket ratios to 10 [bluewavenet]



— Rob White <dot@blue-wave.net> Sun, 06 Feb 2022 07:44:50 +0000


opennds (9.5.1)

  • This minor version update fixes two important issues
  • Fix - ThemeSpec file downloads when mwan3 is running [bluewavenet]
  • Fix - Preemptive auth failure after previous deauth [minhng99] [bluewavenet]



— Rob White <dot@blue-wave.net> Thu, 16 Dec 2021 16:22:16 +0000


opennds (9.5.0)

  • This version adds new functionality, and fixes some issues
  • Add - use average packet size instead of MTU when implementing rate limiting [bluewavenet]
  • Fix - typo in iptables command and remove a redundant command [bluewavenet]
  • Add - startdaemon() and stopdaemon() utility functions [bluewavenet]
  • Add - combined interface/ipaddress external gateway status monitoring [bluewavenet]
  • Fix - potential online/offline detection problem when mwan3 is running [bluewavenet]
  • Add - get_debug_level and syslog library calls [bluewavenet]
  • Fix - correctly reset upload and download rate rules [bluewavenet]
  • Add - extend upstream gateway checking for use with mwan3 loadbalance/failover [bluewavenet]
  • Fix - Potential NULL pointer segfault in http_microhttpd on calling authenticated() [bluewavenet]
  • Fix - Potential NULL pointer segfault in http_microhttpd on calling preauthenticated() [dddaniel]
  • Add - Calculate Bucket size based on achieved burst rate [bluewavenet]
  • Fix - prevent parameter parsing if clientip not known [bluewavenet]
  • Add - disable rate quotas by setting bucket ratio to zero [bluewavenet]
  • Fix - suppress some debug messages [bluewavenet]
  • Add - more libraries documentation [bluewavenet]
  • Add - library calls startdaemon and stopdaemon [bluewavenet]
  • Fix - Increase buffer length for longer interface names [koivunen]
  • Add - enforce minimum data rates in ndsctl auth [bluewavenet]
  • Add - Update README.md [bluewavenet]
  • Add - bucket ratio option to config file [bluewavenet]
  • Add - upload and download bucket ratio config values [bluewavenet]
  • Fix - flag initial debuglevel to externals [bluewavenet]
  • Add - limit-burst tuning to rate quotas [bluewavenet]
  • Fix - add trailing space to defaultip [bluewavenet]
  • Add - record pre-emptive authentication in local log [bluewavenet]
  • Add - Write to local log function to libopennds [bluewavenet]
  • Add - set client_type and custom string for Pre-emptive authentication [bluewavenet]
  • Fix - Remove trailing newline from library call response [bluewavenet]
  • Fix - attempt to remove cid file only if client->cid is set [bluewavenet]
  • Add - a skip option for custom downloads to speed up serving page from themespec [bluewavenet]
  • Add - put client_type into query string when type is cpd canary [bluewavenet]
  • Add - set refresh=0 before loading images [bluewavenet]
  • Fix - Truncated return status [bluewavenet]
  • Add - Acknowlegement from call to dnsconfig [bluewavenet]
  • Fix - potential buffer overflow in debug output [bluewavenet]
  • Add - processing of custom data and client type [bluewavenet]
  • Add - Client Type for RFC8908 and RFC8910 clients [bluewavenet]
  • Add - rfc8908 replies for external FAS and refactor memory management for MHD calls [bluewavenet]
  • Add - send error 403 if client is not on openNDS subnet [bluewavenet]
  • Fix - remove uneccessary safe_asprint in auth.c [bluewavenet]
  • Fix - Initialise buffer to prevent receiving spurious characters [bluewavenet]
  • Add - encoded custom data support to ndsctl json, themespec and binauth [bluewavenet]
  • Add - advert_1.htm to thankyou page of theme_click-to-continue-custom-placeholders.sh [bluewavenet]
  • Add - library call get_interface_by_ip [bluewavenet]
  • Add - function encode_custom() for encoding custom data to be sent to openNDS [bluewavenet]
  • Fix - error 511, make all html references absolute to enforce link to MHD [bluewavenet]
  • Add - check status_path exists and is executable [bluewavenet]
  • Fix - regression causing error 511 to be served from default script [bluewavenet]
  • Add - venue-info-url and can-extend-session json keys [bluewavenet]
  • Add - RFC 8908 initial experimental support [bluewavenet]
  • Add - debug message when resetting client [bluewavenet]
  • Fix - Ensure the ndscids directory exists before trying to write to it. [bluewavenet]
  • Fix - use eval in do_ndsctl to allow quoting of arguments [bluewavenet]
  • Fix - ensure client hid and client cid file is reset correctly [bluewavenet]
  • Fix - Titles of example ThemeSpec Files [bluewavenet]
  • Fix - Ensure ThemeSpec Files are executable [bluewavenet]
  • Remove - deprecated Allowed and Blocked entries in ndsctl status output [bluewavenet]
  • Add - Deprecate option macmechanism, allowedmaclist and blockedmaclist [bluewavenet]



— Rob White <dot@blue-wave.net> Wed, 8 Dec 2021 06:45:56 +0000


opennds (9.4.0)

  • This version adds new functionality, and fixes some issues
  • Add - Error message in fas-aes-https if shared key is mismatched [bluewavenet]
  • Fix - and refactor error 511 page generation[bluewavenet]
  • Fix - and refactor dnsmasq configuration [bluewavenet]
  • Fix - Typographic error preventing RFC8910 disable [bluewavenet]
  • Add - gateway address and gatewayfqdn to ndsctl json output [bluewavenet]
  • Add - RFC8910 housekeeping on startup and shutdown [bluewavenet]
  • Add - correctly apply dhcp option 114 for generic Linux [bluewavenet]
  • Add - reading of configured ndsctlsocket in ndsctl utility[bluewavenet]
  • Add - use send_error 200 for MHD watchdog [bluewavenet]
  • Add - generation of page_511 html by library script [bluewavenet]
  • Add - extend debuglevel support to library scripts [bluewavenet]
  • Refactor - fas-aes-https to simplify and make customisation of http easier [bluewavenet]
  • Add - library script for error 511 page, allowing customisation [bluewavenet]
  • Add - make authmon report connection error details [bluewavenet]
  • Fix- remove unwanted debug message in ndsctl [bluewavenet]
  • Add - RFC8910 support by default [bluewavenet]
  • Add - display status page when accessing /login when authenticated [bluewavenet]
  • Add - MHD response to RFC8910 requests [bluewavenet]
  • Add - Dnsmasq RFC8910 configuration [bluewavenet]
  • Add - send error 511 in response to unsupported http method [bluewavenet]
  • Add - Check for ca-bundle on OpenWrt, if not installed, add syslog messages and terminate [bluewavenet]
  • Add - Make ndsctl use the configured value for socket path if set and deprecate -s option [bluewavenet]
  • Add - Warning message when Walled Garden port 80 is allowed [bluewavenet]
  • Fix - remove un-needed pthread_kill in termination_handler() [bluewavenet] [T-X]
  • Fix - debug messages from authmon.sh [bluewavenet]
  • Fix - Allow disabling gateway fqdn, facilitating access to router port 80 [bluewavenet]
  • Fix - Segfault in ndsctl when -s option is used incorrectly [bluewavenet] [T-X]
  • Fix - Typo making calculation of ul/dl rates incorrect [bluewavenet]
  • Fix - Allow port 80 to be configured in the Walled Garden [bluewavenet]



— Rob White <dot@blue-wave.net> Wed, 22 Sep 2021 19:39:08 +0000


opennds (9.3.1)

  • This version fixes some issues
  • Fix - Segfault in ndsctl when -s option is used incorrectly [bluewavenet] [T-X]
  • Fix - Typo making calculation of ul/dl rates incorrect [bluewavenet]
  • Fix - Allow port 80 to be configured in the Walled Garden [bluewavenet]
  • Add - Warning message when Walled Garden port 80 is allowed [bluewavenet]



— Rob White <dot@blue-wave.net> Thu, 26 Aug 2021 12:09:36 +0000


opennds (9.3.0)

  • This version adds new functionality, and fixes some issues
  • Add - Add - firewall passthrough mode for authenticated users [bluewavenet]
  • Add - Add - use configured debuglevel in authmon [bluewavenet]
  • Add - automated log rotation and client_zone to binauth_log [bluewavenet]
  • Add - increased timeout interval for file downloads [bluewavenet]
  • Add - local interface to MeshZone and remove unneeded call to ip utility [bluewavenet]
  • Add - log_mountpoint and max_log_entries options [bluewavenet]
  • Add - config variables ext_interface and ext_gateway [bluewavenet]
  • Add - Start initial download of remotes only if online [bluewavenet]
  • Add - Router online/offline watchdog [bluewavenet]
  • Fix - Segfault when gatewayfqdn is disabled [bluewavenet]
  • Fix - missing clientmac when not using themespec [bluewavenet]
  • Fix - some compiler warnings [bluewavenet]
  • Fix - use configured value for webroot for remote image symlink to images folder [bluewavenet]
  • Fix - remove references to login.sh in documentation and comments [bluewavenet]
  • Fix - Prevent potential read overrun within the MHD page buffer [bluewavenet]
  • Remove - legacy get_ext_iface() function [bluewavenet]



— Rob White <dot@blue-wave.net> Sun, 8 Aug 2021 09:58:02 +0000


opennds (9.2.0)

  • This version adds new functionality, improves performance, adds documentation and fixes an issue
  • Add - new config options to ndsctl status [bluewavenet]
  • Add - Readthedocs / man documentation for configuration options [bluewavenet]
  • Add - Faster convergence of average rates to configured rate quotas [bluewavenet]
  • Add - BinAuth parse authenticated client database for client data [bluewavenet]
  • Add - Use heap allocation for http page buffer allowing large page sizes [bluewavenet]
  • Fix - fail to serve downloaded images on custom themespec [bluewavenet]



— Rob White <dot@blue-wave.net> Sun, 11 July 2021 15:05:39 +0000


opennds (9.1.1)

  • This version fixes a compiler error, some compiler warnings and mutes a debug message
  • Fix - Compiler error, missing mode in call to open() [bluewavenet]
  • Fix - Compiler warning, ignored return value from call to lockf() [bluewavenet]
  • Fix - Compiler warning, ignored return value from call to system() [bluewavenet]
  • Fix - Compiler warning, ignored return value from call to fgets() [bluewavenet]
  • Fix - Remove debug message from call to get_client_interface library [bluewavenet]



— Rob White <dot@blue-wave.net> Thu, 4 July 2021 21:07:21 +0000


opennds (9.1.0)

  • This version introduces new functionality, some changes and fixes
  • Add - option statuspath to enable alternate status page scripts [bluewavenet]
  • Add - ndsctl lockf() file locking [bluewavenet] [T-X]
  • Add - b64encode to ndsctl [bluewavenet]
  • Add - option max_page_size for MHD [bluewavenet]
  • Add - option remotes_refresh_interval [bluewavenet]
  • Add - Pre-download remote files in background after startup [bluewavenet]
  • Add - client id data files created by openNDS on client connect [bluewavenet]
  • Add - check routing is configured and up [bluewavenet]
  • Add - support for Preemptive Authentication for connected client devices. [bluewavenet]
  • Add - Gateway interface watchdog [bluewavenet]
  • Remove - deprecated IFB config [bluewavenet]
  • Fix - ndsctl, send return codes [bluewavenet]
  • Fix - MHD Watchdog Use uclient-fetch in OpenWrt [bluewavenet]
  • Fix - Improve MHD watchdog [bluewavenet]
  • Fix - update legacy code in ndsctl_thread [bluewavenet]
  • Fix - edge case where MHD returns (null) as host value [bluewavenet]



— Rob White <dot@blue-wave.net> Thu, 24 June 2021 15:06:30 +0000


openNDS (9.0.0)

  • This version introduces major new functionality, some changes and fixes
  • Add - post-request - add upstream payload [bluewavenet]
  • Add - post-request - base64 encode payload [bluewavenet]
  • Add - authmon add more status checking and default to view mode for upstream processing [bluewavenet]
  • Add - authmon add housekeeping call, limit concurrent authentications, send auth-ack [bluewavenet]
  • Add - fas-aes-https add housekeeping call, add auth-ack support, add "try again" button [bluewavenet]
  • Add - "$" character added to htmlentityencode [bluewavenet]
  • Add - Theme support - theme_click-to-continue [bluewavenet]
  • Add - Themespec, custom variables and custom images options to OpenWrt config [bluewavenet]
  • Add - Support for ThemeSpecPath, FasCustomParametersList, FasCustomVariablesList, FasCustomImagesList [bluewavenet]
  • Add - Example theme - click-to-continue-custom-placeholders [bluewavenet]
  • Add - Increase Buffer sizes to support custom parameters [bluewavenet]
  • Add - themespec_path argument [bluewavenet]
  • Add - Increase buffers for custom vars and images [bluewavenet]
  • Add - Increase command buffer for custom vars and images [bluewavenet]
  • Add - Increase HTMLMAXSIZE [bluewavenet]
  • Add - Use MAX_BUF for fasparam, fasvar and fasimage [bluewavenet]
  • Add - support for ThemeSpec files and placeholders [bluewavenet]
  • Add - Theme Click to Continue with Custom Placeholders [bluewavenet]
  • Add - make custom field a required entry [bluewavenet]
  • Add - bash/ash check and simplify image download config [bluewavenet]
  • Add - example custom images and text placeholders to click-to-continue-custom [bluewavenet]
  • Add - theme_user-email-login-custom-placeholders [bluewavenet]
  • Add - Status page for login failure [bluewavenet]
  • Add - fas_custom_files_list and update Makefiles [bluewavenet]
  • Add - Autoconfiguration of ndsctl socket file to use tmpfs mountpoint [bluewavenet]
  • Add - example custom images and custom html [bluewavenet]
  • Add - Set default gateway interface br-lan [bluewavenet]
  • Add - libopennds, set wget timeout [bluewavenet]
  • Add - allow disabling of gatewayfqdn [bluewavenet]
  • Add - packet rate limiting for upload/download rate quotas [bluewavenet]
  • Add - get custom resources from Github branch [bluewavenet]
  • Add - functions start_mhd() and stop_mhd() [bluewavenet]
  • Add - MHD Watchdog - restart MHD if required [bluewavenet]
  • Add - Pause and retry popen on failure [bluewavenet]
  • Add - function get_key_from_config() [bluewavenet]
  • Remove - deprecated traffic control code [bluewavenet]
  • Remove - deprecated binauth scripts [bluewavenet]
  • Remove - deprecated legacy splash page support [bluewavenet]
  • Remove - deprecated ndsctl clients [bluewavenet]
  • Remove - outdated PreAuth scripts [bluewavenet]
  • Refactor - Move hid to head of query string [bluewavenet]
  • Refactor - Move libopennds to libs
  • Fix - ndsctl auth crashed opennds if session duration argument was null [bluewavenet]
  • Fix - fas-aes-https - correctly set path for authlist for most server types [bluewavenet]
  • Fix - suppress BinAuth syslog notice message [bluewavenet]
  • Fix - setting gw_fqdn in hosts file if gw_ip is changed [bluewavenet]
  • Fix - add missing comma before trusted list in ndsctl json [bluewavenet] [gueux]
  • Fix - Improve Shell detection [bluewavenet]
  • Fix - Improve b64decode performance [bluewavenet]
  • Fix - ndsctl -s option [bluewavenet] [gueux]
  • Fix - Adjust config defaults to good real world values [bluewavenet]
  • Fix - don't override ndsparamlist in ThemeSpec files [bluewavenet]
  • Fix - Check ndsctl lock to prevent calling from Binauth [bluewavenet]
  • Fix - Clean up syslog messages at info level (2) [bluewavenet]
  • Fix - Debian changelog format to allow package building [bluewavenet]
  • Fix - numerous compiler errors and BASH compatibility issues [bluewavenet]
  • Fix - ndsctl auth, ensure if session timeout = 0 then use global value [bluewavenet]
  • Fix - setting of gatewayport, caused by typo in conf.c [bluewavenet] [Ethan-Yami]
  • Fix - remove unused credential info from log [bluewavenet]
  • Deprecate - the legacy opennds.conf file [bluewavenet]



— Rob White <dot@blue-wave.net> Thu, 2 May 2021 17:32:43 +0000


openNDS (8.1.1)

Fix - remove legacy code where option preauthenticated_users containing the keyword "block" would cause openNDS to fail to start [bluewavenet]



— Rob White <dot@blue-wave.net> Thu, 21 Feb 2021 16:33:34 +0000


openNDS (8.1.0)

  • This version introduces some new functionality and some fixes/enhancements
  • Fix - Add default values for gatewayfqdn. If not set in config could result in crash on connection of first client [bluewavenet]
  • Add - Authenticated users are now granted access to the router by entry in "list authenticated_users" [bluewavenet]
  • Fix - option preauth was being ignored [bluewavenet]
  • Add - query string validity check and entity encode "$" character. Generate error 511 if query string is corrupted [bluewavenet]
  • Add - a "Try Again" button to the login.sh script, to be displayed if the client token has expired before login. [bluewavenet]



— Rob White <dot@blue-wave.net> Thu, 18 Feb 2021 17:03:23 +0000


openNDS (8.0.0)

  • This version introduces major new functionality and some major changes
  • Rationalisation of support for multiple Linux distributions [bluewavenet]
  • Refactor login.sh script introducing base64 encoding and hashed token (hid) support [bluewavenet]
  • Refactor fas-hid script introducing base64 encoding and simplifying customisation of the script [bluewavenet]
  • Refactor binauth_log.sh and log BinAuth custom data as url encoded [bluewavenet]
  • Refactor fas-aes, simplifying customisation of the script [bluewavenet]
  • Refactor fas-aes-https, simplifying customisation of the script [bluewavenet]
  • Change - Use hid instead of tok when fas_secure_enabled >= 1 [bluewavenet]
  • Add - base64 encoding to fas_secure_enabled level 1 [bluewavenet]
  • Add - gatewyname, clientif, session_start, session_end and last_active to ndsctl json [bluewavenet]
  • Add - support for RFC6585 Status Code 511 - Network Authentication Required [bluewavenet]
  • Add - Client Status Page UI with Logout [bluewavenet]
  • Add - GatewayFQDN option [bluewavenet]
  • Add - client interface to status page query string [bluewavenet]
  • Add - support using base 64 encoded custom string for BinAuth and replace tok with hid [bluewavenet]
  • Add - base 64 decode option to ndsctl [bluewavenet]
  • Add - b64 encoding of querystring for level 1 [bluewavenet]
  • Add - Improved performance/user-experience on congested/slow systems using php FAS scripts [bluewavenet]
  • Add - support for ndsctl auth by hid in client_list [bluewavenet]
  • Add - Ensure faskey is set to default value (always enabled) [bluewavenet]
  • Add - Display error page on login failure in login.sh [bluewavenet]
  • Add - splash.html, add deprecation notice [bluewavenet]
  • Add - authmon, improved lock checking and introduce smaller loopinterval [bluewavenet]
  • Add - client_params, wait for ndsctl if it is busy [bluewavenet]
  • Add - fas-aes-https, allow progressive output to improve user experience on slow links [bluewavenet]
  • Fix - Block access to /opennds_preauth/ if PreAuth not enabled [bluewavenet]
  • Fix - On startup, call iptables_fw_destroy before doing any other setup [bluewavenet]
  • Fix - missing final redirect to originurl in fas-hid [bluewavenet]
  • Fix - ensure gatewayname is always urlencoded [bluewavenet]
  • Fix - client session end not set by binauth [bluewavenet]
  • Fix - Session timeout, if client setting is 0, default to global value [bluewavenet]
  • Fix - missing trailing separator on query and fix some compiler errors [bluewavenet]
  • Fix - ensure authmon daemon is killed if left running from previous crash [bluewavenet]
  • Fix - add missing query separator for custom FAS parameters [bluewavenet]
  • Fix - ndsctl auth, do not set quotas if client is already authenticated [bluewavenet]
  • Fix - client_params, show "Unlimited" when "null" is received from ndsctl json [bluewavenet]
  • Update configuration files [bluewavenet]
  • update documentation [bluewavenet]



— Rob White <dot@blue-wave.net> Sat, 2 Jan 2021 16:38:14 +0000


openNDS (7.0.1)

  • This version contains fixes and some minor updates
  • Fix - Failure of Default Dynamic Splash page on some operating systems [bluewavenet]
  • Fix - A compiler warning - some compiler configurations were aborting compilation [bluewavenet]
  • Update - Added helpful comments in configuration files [bluewavenet]
  • Remove - references to deprecated RedirectURL in opennde.conf [bluewavenet]
  • Update - Documentation updates and corrections [bluewavenet]



— Rob White <dot@blue-wave.net> Wed, 7 Nov 2020 12:40:33 +0000


openNDS (7.0.0)

  • This version introduces major new enhancements and the disabling or removal of deprecated functionality
  • Fix - get_iface_ip in case of interface is vif or multihomed [bluewavenet]
  • Fix - Add missing client identifier argument in ndsctl help text [bluewavenet]
  • Deprecate - ndsctl clients option [bluewavenet]
  • Add - global quotas to output of ndsctl status [bluewavenet]
  • Fix - fix missing delimiter in fas-hid [bluewavenet]
  • Add - Report Rate Check Window in ndsctl status and show client quotas [bluewavenet]
  • Add - Quota and rate reporting to ndsctl json. Format output and fix json syntax errors [bluewavenet]
  • Fix - get_client_interface for case of iw utility not available [bluewavenet]
  • Fix - php notice for pedantic php servers in post-request [bluewavenet]
  • Add - built in autonomous Walled Garden operation [bluewavenet]
  • Remove - support for deprecated RedirectURL [bluewavenet]
  • Add - gatewaymac to the encrypted query string [bluewavenet]
  • Deprecate - legacy splash.html and disable it [bluewavenet]
  • Add - support for login mode in PreAuth [bluewavenet]
  • Add - Support for Custom Parameters [bluewavenet]



— Rob White <dot@blue-wave.net> Wed, 5 Nov 2020 18:22:32 +0000


openNDS (6.0.0)

  • This version - for Openwrt after 19.07 - for compatibility with new MHD API
  • Set - minimum version of MHD to 0.9.71 for new MHD API [bluewavenet]
  • Set - use_outdated_mhd to 0 (disabled) as default [bluewavenet]
  • Add - Multifield PreAuth login script with css update [bluewavenet]
  • Add - Documentation and config option descriptions for configuring Walled Garden IP Sets



— Rob White <dot@blue-wave.net> Wed, 21 Aug 2020 15:43:47 +0000


openNDS (5.2.0)

  • This version - for backport to Openwrt 19.07 - for compatibility with old MHD API
  • Fix - Failure of MHD with some operating systems eg Debian [bluewavenet]
  • Fix - potential buffer truncation in ndsctl
  • Set - use_outdated_mhd to 1 (enabled) as default [bluewavenet]
  • Set - maximum permissible version of MHD to 0.9.70 to ensure old MHD API is used [bluewavenet]



— Rob White <dot@blue-wave.net> Wed, 12 Aug 2020 17:43:57 +0000


openNDS (5.1.0)

  • Add - Generic Linux - install opennds.service [bluewavenet]
  • Add - Documentation updates [bluewavenet]
  • Add - config file updates [bluewavenet]
  • Add - Install sitewide username/password splash support files [bluewavenet]
  • Add - quotas to binauth_sitewide [bluewavenet]
  • Add - Splash page updates [bluewavenet]
  • Add - Implement Rate Quotas [bluewavenet]
  • Fix - check if idle preauthenticated [bluewavenet]
  • Add - support for rate quotas [bluewavenet]
  • Fix - Correctly compare client counters and clean up debuglevel messages [bluewavenet]
  • Add - Implement upload/download quotas Update fas-aes-https to support quotas [bluewavenet]
  • Add - Rename demo-preauth scripts and install all scripts [bluewavenet]
  • Add - fas-aes-https layout update [bluewavenet]
  • Add - Set some defaults in fas-aes-https [bluewavenet]
  • Add - custom data string to ndsctl auth [bluewavenet]
  • Add - custom data string to fas-hid.php [bluewavenet]
  • Add - Send custom data field to BinAuth via auth_client method [bluewavenet]
  • Fix - missing token value in auth_client [bluewavenet]
  • Add - upload/download quota and rate configuration values [bluewavenet]
  • Add - Send client token to binauth [bluewavenet]
  • Add - Rename upload_limit and download_limit to upload_rate and download_rate [bluewavenet]
  • Fix - Pass correct session end time to binauth [bluewavenet]
  • Add - some debuglevel 3 messages [bluewavenet]
  • Add - description of the favicon and page footer images [bluewavenet]
  • Add - Authmon collect authentication parameters from fas-aes-https [bluewavenet]
  • Add - sessionlength to ndsctl auth [bluewavenet]
  • Fix - Page fault when ndsctl auth is called and client not found [bluewavenet]
  • Add - Enable BinAuth / fas_secure_enabled level 3 compatibility [bluewavenet]
  • Fix - Correctly set BinAuth session_end [bluewavenet]
  • Add - Updates to Templated Splash pages [bluewavenet]
  • Add - Community Testing files [bluewavenet]
  • Fix - BinAuth error passing client session times [bluewavenet]
  • Fix - PHP notice - undefined constant [bluewavenet]
  • Fix - OpenWrt CONFLICTS variable in Makefile [bluewavenet]



— Rob White <dot@blue-wave.net> Wed, 24 Jun 2020 20:55:18 +0000


openNDS (5.0.1)

Fix - Path Traversal Attack vulnerability allowed by libmicrohttpd's built in unescape functionality [bluewavenet] [lynxis]



— Rob White <dot@blue-wave.net> Wed, 06 May 2020 19:56:27 +0000


openNDS (5.0.0)

  • Import - from NoDogSplash 4.5.0 allowing development without compromising NoDogSplash optimisation for minimum resource utilisation [bluewavenet]
  • Rename - from NoDogSplash to openNDS [bluewavenet]
  • Create - openNDS avatar and splash image [bluewavenet]
  • Move - wait_for_interface to opennds C code ensuring consistent start at boot time for all hardware, OpenWrt and Debian [bluewavenet]
  • Add - Enable https protocol for remote FAS [bluewavenet]
  • Add - trusted devices list to ndsctl json output [bluewavenet]
  • Add - option unescape_callback_enabled [bluewavenet]
  • Add - get_client_token library utility [bluewavenet]
  • Add - utf-8 to PreAuth header [bluewavenet]
  • Add - PreAuth Support for hashed id (hid) if sent by NDS [bluewavenet]
  • Add - library script shebang warning for systems not running Busybox [bluewavenet]
  • Add - htmlentityencode function, encode gatewayname in templated splash page [bluewavenet]
  • Add - htmlentity encode gatewayname on login page (PreAuth) [bluewavenet]
  • Add - Simple customisation of log file location for PreAuth and BinAuth [bluewavenet]
  • Add - option use_outdated_mhd [bluewavenet]
  • Add - url-encode and htmlentity-encode gatewayname on startup [bluewavenet]
  • Add - Allow special characters in username (PreAuth) [bluewavenet]
  • Add - Documentation updates [bluewavenet]
  • Add - Various style and cosmetic updates [bluewavenet]
  • Fix - Change library script shebang to bash in Debian [bluewavenet]
  • Fix - Remove unnecessary characters causing script execution failure in Debian [bluewavenet]
  • Fix - Add missing NULL parameter in MHD_OPTION_UNESCAPE_CALLBACK [skra72] [bluewavenet]
  • Fix - Script failures running on Openwrt 19.07.0 [bluewavenet]
  • Fix - Preauth, status=authenticated [bluewavenet]
  • Fix - Prevent ndsctl from running if called from a Binauth script. [bluewavenet]
  • Fix - Minor changes in Library scripts for better portability [bluewavenet]
  • Fix - Prevent php notices on pedantic php servers [bluewavenet]
  • Fix - broken remote image retrieval (PreAuth) [bluewavenet]
  • Fix - Allow use of "#" in gatewayname [bluewavenet]



— Rob White <dot@blue-wave.net> Sat, 03 Apr 2020 13:23:36 +0000


HOW OPENNDS (NDS) WORKS

openNDS is a Captive Portal Engine. Any Captive Portal, including NDS, will have two main components:

  • Something that does the capturing, and
  • Something to provide a Portal for client users to log in.



openNDS MUST run on a device configured as an IPv4 router.

A wireless router will typically be running OpenWrt or some other Linux distribution.

A router, by definition, will have two or more interfaces, at least one to connect to the wide area network (WAN) or Internet feed, and at least one connecting to the local area network (LAN).

Each LAN interface must also act as the Default IP Gateway for its LAN, ideally with the interface serving IP addresses to client devices using DHCP.

Multiple LAN interfaces can be combined into a single bridge interface. For example, ethernet, 2.4Ghz and 5Ghz networks are typically combined into a single bridge interface. Logical interface names will be assigned such as eth0, wlan0, wlan1 etc. with the combined bridge interface named as br-lan.

NDS will manage one or more of them of them. This will typically be br-lan, the bridge to both the wireless and wired LAN, but could be, for example, wlan0 if you wanted NDS to work just on the wireless interface.

Summary of Operation

By default, NDS blocks everything, but intercepts port 80 requests.

An initial port 80 request will be generated on a client device, usually automatically by the client device's built in Captive Portal Detection (CPD), or possibly by the user manually browsing to an http web page.

This request will of course be routed by the client device to the Default Gateway of the local network. The Default Gateway will, as we have seen, be the router interface that NDS is managing.

The Thing That Does the Capturing (NDS)

As soon as this initial port 80 request is received on the default gateway interface, NDS will "Capture" it, make a note of the client device identity, allocate a unique token for the client device, then redirect the client browser to the Portal component of NDS.


The Thing That Provides the Portal (FAS, PreAuth, Themespec)

The client browser is redirected to the Portal component. This is a web service that is configured to know how to communicate with the core engine of openNDS.

This is commonly known as the Splash Page, or more correctly, the entry point to the portal splash page sequence.

openNDS has its own web server built in and this can be used to serve the Portal "Splash" pages to the client browser, or a separate web server can be used.

openNDS comes with numerous standard Splash Page Sequence options pre-installed.

One provides a trivial Click to Continue splash page and another provides a Client User form requiring Name and Email address to be entered.

All of these can be customised or a complete specialised Portal can be written by the installer (See FAS, PreAuth, Themespec).

FAS, or Forward Authentication Service may use the web server embedded in openNDS, a separate web server installed on the NDS router, a web server residing on the local network or an Internet hosted web server.

The user of the client device will always be expected to complete some actions on the splash page.

Once the user on the client device has successfully completed the splash page actions, that page then links directly back to NDS.

For security, NDS expects to receive valid verification of the client. If the verification is valid, openNDS then "authenticates" the client device, allowing access to the Internet. openNDS uses various methods of encryption to ensure verification cannot be bypassed.

Post authentication processing extensions may be added to openNDS (See BinAuth). Once openNDS has authenticated a client, it calls a BinAuth script if enabled.

Typically, BinAuth is used to provide a local log of authenticated clients. In addition the BinAuth script can override client authentication if required.



NOTE:

FAS and Binauth can be enabled together. This can give great flexibility, with FAS providing remote verification and Binauth providing local post authentication processing closely linked to openNDS.


Captive Portal Detection (CPD)

All modern mobile devices, most desktop operating systems and most browsers now have a CPD process that automatically issues a port 80 request on connection to a network. NDS detects this and serves a special “splash” web page to the connecting client device.

The port 80 html request made by the client CPD can be one of many vendor specific URLs.


It is important to remember that CPD is designed primarily for mobile devices to automatically detect the presence of a portal and to trigger the login page, without having to resort to breaking SSL/TLS security by requiring the portal to redirect port 443 for example.

Just about all current CPD implementations work very well but some compromises are necessary depending on the application.

The vast majority of devices attaching to a typical Captive Portal are mobile devices. CPD works well giving the initial login page.

For a typical guest wifi, eg a coffee shop, bar, club, hotel etc., a device connects, the Internet is accessed for a while, then the user takes the device out of range.

When taken out of range, a typical mobile device begins periodically polling the wireless spectrum for SSIDs that it knows about to try to obtain a connection again, subject to timeouts to preserve battery life.

Most Captive Portals have a session duration limit (NDS included).

If a previously logged in device returns to within the coverage of the portal, the previously used SSID is recognised and CPD is triggered and tests for an Internet connection in the normal way. Within the session duration limit of the portal, the Internet connection will be established, if the session has expired, the splash page will be displayed again.

Early mobile device implementations of CPD used to poll their detection URL at regular intervals, typically around 30 to 300 seconds. This would trigger the Portal splash page quite quickly if the device stayed in range and the session limit had been reached.

However it was very quickly realised that this polling kept the WiFi on the device enabled continuously having a very negative effect on battery life, so this polling whilst connected was either increased to a very long interval or removed all together (depending on vendor) to preserve battery charge. As most mobile devices come and go into and out of range, this is not an issue.

A common issue raised is:

My devices show the splash page when they first connect, but when the authorization expires, they just announce there is no internet connection. I have to make them "forget" the wireless network to see the splash page again. Is this how is it supposed to work?

The workaround is as described in the issue, or even just manually disconnecting or turning WiFi off and on will simulate a "going out of range", initialising an immediate trigger of the CPD. One or any combination of these workarounds should work, again depending on the particular vendor's implementation of CPD.

In contrast, most laptop/desktop operating systems, and browser versions for these still implement CPD polling whilst online as battery considerations are not so important.

For example, Gnome desktop has its own built in CPD browser with a default interval of 300 seconds. Firefox also defaults to something like 300 seconds. Windows 10 is similar.

This IS how it is supposed to work, but does involve some compromises.

The best solution is to set the session timeout to a value greater than the expected length of time a client device is likely to be present. Experience shows a limit of 24 hours covers most situations eg bars, clubs, coffee shops, motels etc. If for example an hotel has guests regularly staying for a few days, then increase the session timeout as required.

Staff at the venue could have their devices added to the Trusted List if appropriate, but experience shows, it is better not to do this as they very soon learn what to do and can help guests who encounter the issue. (Anything that reduces support calls is good!)

Captive Portal Identification (CPI) (RFC 8910)

Captive Portal Identification is an alternative method of triggering the Portal "Splash" page without having to capture the attempted port 80 access that CPD does.

Instead of waiting for the client to test for Internet access using its vendor specified detection URL, openNDS sends the end point URL of its own Portal using DHCP option 114 (default-url).

Any clients supporting this method will open their CPD browser pointing at the specified URL instead of waiting for a redirection.

This is a new and somewhat experimental standard with very few clients supporting it, but this is likely to change rapidly as the standard matures.

This method is enabled in openNDS by default, but can be disabled (see "Dhcp option 114 Enable - RFC8910" in the Configuration Options section).

Captive Portal Identification With Portal API (RFC 8910 / RFC 8908)

The RFC8908 Captive Portal API extends Captive Portal Identification by adding an API by which a client device can access the Portal. This is supported in openNDS from version 9.5.0 onwards.

At the time of writing (November 2021), very few client devices support this API.

Network Zone Detection (Where is the Client Connected?)

Client devices can be connected to one of a number of local WiFi SSIDs, connected directly or indirectly by ethernet, or connected via a wireless mesh network. Each connection type available is considered as a Network Zone.

NDS detects which zone each client is connected to. This information can be used to dynamically customise the login for each zone.

For example a coffee shop might have two SSIDs configured:

  • Staff (Secure SSID ie with access code)
  • Customers (open SSID with login form)



In this example SSID "Staff" is configured on interface wlan0, and considered as Zone "Private".

However, SSID "Customers" is configured on virtual interface wlan0-1, and considered as Zone "Public".

NDS detects which zone is being used by a client and a relevant login page can be served.

Packet filtering

openNDS considers four kinds of packets coming into the router over the managed interface. Each packet is one of these kinds:

1.
Blocked, if the MAC mechanism is block, and the source MAC address of the packet matches one listed in the BlockedMACList; or if the MAC mechanism is allow, and source MAC address of the packet does not match one listed in the AllowedMACList or the TrustedMACList. These packets are dropped.
2.
Trusted, if the source MAC address of the packet matches one listed in the TrustedMACList. By default, these packets are accepted and routed to all destination addresses and ports. If desired, this behavior can be customized by FirewallRuleSet trusted-users and FirewallRuleSet trusted-users-to-router lists in the opennds.conf configuration file, or by the EmptyRuleSetPolicy trusted-users EmptyRuleSetPolicy trusted-users-to-router directives.
3.
Authenticated, if the packet's IP and MAC source addresses have gone through the openNDS authentication process and has not yet expired. These packets are accepted and routed to a limited set of addresses and ports (see FirewallRuleSet authenticated-users and FirewallRuleSet users-to-router in the opennds.conf configuration file).
4.
Preauthenticated. Any other packet. These packets are accepted and routed to a limited set of addresses and ports (see FirewallRuleSet preauthenticated-users and FirewallRuleSet users-to-router in the opennds.conf configuration file). Any other packet is dropped, except that a packet for destination port 80 at any address is redirected to port 2050 on the router, where openNDS's built in libhttpd-based web server is listening. This begins the 'authentication' process. The server will serve a splash page back to the source IP address of the packet. The user clicking the appropriate link on the splash page will complete the process, causing future packets from this IP/MAC address to be marked as Authenticated until the inactive or forced timeout is reached, and its packets revert to being Preauthenticated.



openNDS implements these actions by inserting rules in the router's iptables mangle PREROUTING chain to mark packets, and by inserting rules in the nat PREROUTING, filter INPUT and filter FORWARD chains which match on those marks.

Because it inserts its rules at the beginning of existing chains, openNDS should be insensitive to most typical existing firewall configurations.

Data volume and Rate Quotas

openNDS (NDS) has built in Data Volume and Data Rate quota support.

Data volume and data rate quotas can be set globally in the config file.

The global values can be overridden on a client by client basis as required.

Traffic Shaping

openNDS (NDS) supports Traffic Shaping (Bandwidth Limiting) using the SQM - Smart Queue Management (sqm-scripts) package, available for OpenWrt and generic Linux.

INSTALLING OPENNDS

Prerequisites

openNDS is designed to run on a device configured as an IPv4 router and will have at least two network interfaces:

A WAN interface (Wide Area Network). This interface must be connected to an Internet feed:
  • Either an ISP CPE (Internet Service Provider Customer Premises Equipment)
  • Or another router, such as the venue ADSL router.
  • It must be configured as a DHCP client, obtaining its IPv4 address and DNS server from the connected network.

A LAN interface (Local Area Network). This interface MUST be configured to:

  • Provide the Default IPv4 gateway in a private IPv4 subnet that is different to any private subnets between it and the ISP CPE
  • Provide DHCP services to connected clients
  • Provide DNS services to connected clients
  • Provide Network Address Translation (NAT) for all outgoing traffic directed to the WAN interface.



If an improper routing configuration is detected, openNDS will shut down.

Installing on OpenWrt

  • Have a router working with OpenWrt. At the time of writing, openNDS has been tested with OpenWrt 18.06.x, 19.7.x 21.2.x and Snapshot.
  • OpenWrt version 19.07.x or less requires theoogle.com updated libmicrohttpd-no-ssl_0.9.71-1 package (or higher version) from Openwrt 21.2.x or higher.
  • openNDS may or may not work on older versions of OpenWrt.
  • Make sure your router is working correctly before you try to install openNDS. In particular, make sure your DHCP daemon is serving addresses on the interface that openNDS will manage.

    The default interface is br-lan but can be changed to any LAN interface by editing the /etc/config/opennds file.

  • To install openNDS on 21.3.x or higher, you may use the OpenWrt Luci web interface or alternatively, ssh to your router and run the command:
opkg update


followed by

opkg install opennds




  • openNDS is enabled by default and will start automatically on reboot or can be started and stopped manually.
  • If the interface that you want openNDS to manage is not br-lan, edit /etc/config/opennds and set GatewayInterface.
  • To start openNDS, run the following, or just reboot the router:
service opennds start


To test the installation, connect a client device to the interface on your router that is managed by openNDS (for example, connect to the router's wireless lan).

Most client device operating systems and browsers support Captive Portal Detection (CPD) and the operating system or browser on that device will attempt to contact a pre defined port 80 web page.

CPD will trigger openNDS to serve the default splash page where you can click or tap Continue to access the Internet.

See the Authentication section for details of setting up a proper authentication process.

If your client device does not display the splash page it most likely does not support CPD.

You should then manually trigger openNDS by trying to access a port 80 web site (for example, http://gnome.org is a good choice).



To stop openNDS:
service opennds stop


To uninstall openNDS:
opkg remove opennds



Generic Linux

openNDS and libmicrohttps-ssl can be compiled in place for most distributions of Linux.

To compile libmicrohttpd and openNDS, see the chapter "How to Compile and install openNDS".

THE SPLASH PAGE SEQUENCE

As you will see mentioned in the "How openNDS (NDS) Works" section, an initial port 80 request is generated on a client device, either by the user manually browsing to an http web page, or, more usually, automatically by the client device's built in Captive Portal Detection (CPD).

This request is intercepted by NDS and an html Splash Page Sequence is served to the user of the client device to enable them to authenticate and be granted Internet access.

Types of Splash Page

This Splash page can be one of the following:

A Dynamic Web Page served by the built in openNDS web server (PreAuth)

A script or executable file is called by openNDS. This script or executable will generate html code for the openNDS web server.

In openNDS this is called "PreAuth", as openNDS itself serves the splash page as a PRElude to AUTHentication.

Simple coding in the script enables a dialogue with the client user, for dissemination of information, user response and authentication.

This is an implementation of Forward Authentication Services (FAS), without the resource utilisation of a separate web server, particularly useful for legacy devices with limited flash and RAM capacity.



A Dynamic Web Page served by an independent web server

This independent web server can be on the same device as openNDS, on the same Local Area Network as NDS, or on External Web Hosting Services.

A script or executable file is called by openNDS on the independent web server.

This has the advantage having the full flexibility of using readily available mainstream web servers, located anywhere, enabling full flexibility in design and implementation of the captive portal functionality, ranging from a self contained system through to a fully integrated multi site system with a common database.



The Pre-Installed Basic Splash Pages

By default, the Splash pages consist of a simple click to continue dialogue followed by a Welcome or advertising page. A simple config option allows you to select instead a Name/EmailAddress login dialogue.

In many instances, one or other of these simple methods will be all that is required, but the power of FAS, PreAuth and BinAuth can be used to create very sophisticated Captive Portal Systems.



The Legacy splash.html Static Web Page

The legacy static splash.html page has been deprecated for some time and in openNDS v 9.0.0 support has been removed.

Displaying Remote Content

openNDS supports the download on demand of remote content

openNDS can display content from third party web hosting, on the client user login screen.

This is ideal for serving information, banner advertising etc. and is configured simply by adding a custom_image or custom_file configuration option.



Walled Garden support

Sophisticated remote content can be served, with access controlled by the openNDS Walled Garden. Simple configuration options can enable such things as a Paypal payment system or access to Facebook resources.

For details see the Walled Garden Section.



CUSTOMISING OPENNDS

After initial installation, openNDS (NDS) should be working in its most basic mode and client Captive Portal Detection (CPD) should pop up the default Click to Continue page.

Before attempting to customise NDS you should ensure it is working in this basic mode.

NDS reads its configuration file when it starts up but the location of this file varies depending on the operating system.

As NDS is a package that requires hardware configured as an IP router, perhaps the most common installation is using OpenWrt. However NDS can be compiled to run on most Linux distributions, the most common being Debian or one of its popular variants (eg Raspbian).

If NDS is working in the default, post installation mode, then you will have met the NDS dependencies and can now move on to your own customisation.

Rules for Customised Splash Pages

It should be noted when designing a custom splash page that for security reasons many client device CPD implementations:

  • Immediately close the browser when the client has authenticated.
  • Prohibit the use of href links.
  • Prohibit downloading of external files (including .css and .js, even if they are allowed in NDS firewall settings).
  • Prohibit the execution of javascript.



The Configuration File

In OpenWrt, or operating systems supporting UCI (such as LEDE) the configuration is kept in the file:

/etc/config/opennds


In other operating systems the configuration is kept in the file:

/etc/opennds/opennds.conf


Both of these files contain a full list of options and can be edited directly. A restart of NDS is required for any changes to take effect.

In the case of OpenWrt though, once you are confident in your configuration requirements you can use UCI to read and set any of the configuration options using simple commands, making this very convenient if making changes from scripts, such as those you may write to use with Binauth and FAS.

For example, to list the full configuration, at the command line type:

uci show opennds


To display the Gateway Name, type:

uci get opennds.@opennds[0].gatewayname


To set the Gateway Name to a new value, type:

uci set opennds.@opennds[0].gatewayname='my new gateway'


To add a new firewall rule allowing access to another service running on port 8888 on the router, type:

uci add_list opennds.@opennds[0].users_to_router='allow
tcp port 8888'


Finally you must tell UCI to commit your changes to the configuration file:

uci commit opennds


The Legacy Click and Go Splash Page

The legacy Click to Continue html splash page was deprecated and disabled at v8.0.0.

From v 9.0.0 it has been removed entirely.

Dynamic Splash Pages

Default Dynamic Click to Continue

The pre-installed dynamic click to continue page sequence is enabled by default using the ThemeSpec "theme_click-to-continue". The configuration default is equivalent to setting:

option login_option_enabled '1'

It generates a Click to Continue page followed by Thankyou and Landing pages.

User clicks on "Continue" are recorded in the log file /[tmpfs_dir]/ndslog/ndslog.log

Where [tmpfs_dir] is the operating system "temporary" tmpfs mount point. This will be /tmp /run or /var and is automatically detected.

Details of how the script works are contained in comments in the script theme_click-to-continue.sh

Pre-Installed dynamic User/email Login page sequence

The pre-installed dynamic login page is enabled by setting option:

option login_option_enabled '2'

It generates a login page asking for username and email address. User logins are recorded in the log file /[tmpfs_dir]/ndslog/ndslog.log

Where [tmpfs_dir] is the operating system "temporary" tmpfs mount point. This will be /tmp /run or /var and is automatically detected.

Details of how the script works are contained in comments in the script theme_user-email-login.sh

Custom Dynamic ThemeSpec Pages

Custom ThemeSpec page sequences can be added by setting option:

option login_option_enabled '3'

and option

option themespecpath '/path/to/themespec_script'

Two additional ThemeSpec files are included as examples:

/usr/lib/opennds/theme_click-to-continue-custom-placeholders.sh

and

/usr/lib/opennds/theme_user-email-login-custom-placeholders.sh

Both these also require custom parameter, variable, image and file lists:

list fas_custom_parameters_list 'logo_message=openNDS:%20Perfect%20on%20OpenWrt!'

list fas_custom_parameters_list 'banner1_message=BlueWave%20-%20Wireless%20Network%20Specialists'

list fas_custom_parameters_list 'banner2_message=HMS%20Pickle'

list fas_custom_parameters_list 'banner3_message=SeaWolf%20Cruiser%20Racer'

list fas_custom_variables_list 'input=phone:Phone%20Number:text;postcode:Home%20Post%20Code:text'

list fas_custom_images_list 'logo_png=https://openwrt.org/_media/logo.png'

list fas_custom_images_list 'banner1_jpg=https://raw.githubusercontent.com/openNDS/openNDS/9.0.0/resources/bannerbw.jpg'

list fas_custom_images_list 'banner2_jpg=https://raw.githubusercontent.com/openNDS/openNDS/9.0.0/resources/bannerpickle.jpg'

list fas_custom_images_list 'banner3_jpg=https://raw.githubusercontent.com/openNDS/openNDS/9.0.0/resources/bannerseawolf.jpg'

list fas_custom_files_list 'advert1_htm=https://raw.githubusercontent.com/openNDS/openNDS/9.0.0/resources/bannerpickle.htm'

Once configured these two example ThemeSpec scripts will download custom image files, a custom html file and inject custom user input forms for phone number and home postcode.

Other Custom Designs

Custom designed dynamically generated ThemeSpec pages are supported using FAS and PreAuth. For details see the FAS and PreAuth chapters.

CONFIGURATION OPTIONS

Enable openNDS

Set to 0 to disable opennds

option enabled 1

Use deprecated generic configuration file

Use of this setting is not recommended.

option config '/etc/opennds/opennds.conf'

Enable debug output (0-3)

Default: 1

Level0

Silent (only initial startup, LOG_ERR and LOG_EMERG messages will be seen, otherwise there will be no logging.)

Level 1

LOG_ERR, LOG_EMERG, LOG_WARNING and LOG_NOTICE (this is the default level).

Level 2

debuglevel 1 + LOG_INFO

Level 3

debuglevel 2 + LOG_DEBUG

option debuglevel '1'

Firewall Restart hook

Set to 0 to disable hook that makes opennds restart when the firewall restarts.

This hook is needed as a restart of Firewall overwrites opennds iptables entries.

option fwhook_enabled '1'

Ndsctl Socket Access

Set the socket name to use for ndsctl socket access, relative to the tmpfs mountpoint.

Any directory/folder specified must exist. Default: ndsctl.sock (Do not add a leading "/")

Full default socket path would be /tmp/ndsctl.sock in OpenWrt In the following example, the socket path would be /tmp/sockets/ndsctl.sock

Example:

option ndsctlsocket 'sockets/ndsctl.sock'

Local Log Mountpoint

Default: router's volatile tmpfs storage eg on OpenWrt '/tmp'

Local logging can be directed to any storage accessible to the router eg USB drive, SSD etc

WARNING - you cannot use the router's built in flash storage as this would cause excessive wear and eventual flash failure

Example:

option log_mountpoint '/logs'

Maximum number of Local Log Entries

Set the maximum number of local log entries to be kept. Default 100

Minimum value 0 (no limit)

Maximum value - limited only by free storage space on the logging mountpoint

If set to '0' there is no limit

This is the maximum number of local log entries allowed before log rotation begins

Both ThemeSpec and BinAuth log locally if they are enabled

WARNING - local logging is by default written to the tmpfs volatile storage

If this option were to be set too high the router could run out of tmpfs storage and/or free RAM

Non-volatile storage, such as a USB storage device may be defined using the log_mountpoint option

Example:

option max_log_entries '1000'

Login Option

Default: 1

Integer value sent to PreAuth script as login mode

openNDS comes preconfigured for three basic modes of operation

Mode 0

If FAS is not enabled, then this functions as mode 1

Mode 1

Default Dynamic Click to Continue

The pre-installed dynamic login page is enabled by setting option login_option_enabled = '1'

It generates a Click to Continue page followed by an info/advertising page.

User clicks on “Continue” are recorded in the log file /[tmpfs_dir]/ndslog/ndslog.log

Mode 2

Username/Emailaddress Dynamic Login

The pre-installed dynamic login page is enabled by setting option login_option_enabled = '2'

It generates a login page asking for username and email address followed by an info/advertising page.

User logins are recorded in the log file /[tmpfs_dir]/ndslog/ndslog.log

Mode 3

Use Theme defined in ThemeSpec path (option themespec_path)

option login_option_enabled '1'

Allow Preemptive Authentication

Default: 0 - Disabled

Enable by setting to 1

This allows the ndsctl utility to preemptively authorise connected clients that have not entered the preauthenticated state.

This is useful for example with IoT devices that do not have CPD (captive portal detection)

or for a FAS to manage inter-captive-portal roaming by making use of a centralised database of client validations.

Example:

option allow_preemptive_authentication '1'

ThemeSpec Path

Default: None

Required when when login_option_enabled is set to '3'

Note: /usr/lib/opennds/theme_click-to-continue.sh is used for login_option_enabled '1'

and: /usr/lib/opennds/theme_user_email_login.sh is used for login_option_enabled '2'

Sets the ThemeSpec file path to be used when login_option_enabled '3'

The ThemeSpec script makes use of lists of custom parameters, custom variables, custom image urls and custom files and is used to generate the dynamic splash page sequence.

The ThemeSpec file will normally reside in /usr/lib/opennds/ but can be anywhere accessible to openNDS.

The file must be flagged as executable and have the correct shebang for the default shell.

option themespec_path '/usr/lib/opennds/<filename>'

Define Custom Parameters

Custom parameters are sent as fixed values to FAS

Default None

Custom Parameters listed in the form of param_name=param_value

param_name and param_value must be urlencoded if containing white space or single quotes

eg replace spaces with %20 - replace single quotes with %27

Parameters should be configured one per line to prevent possible parsing errors.

eg:

list fas_custom_parameters_list '<param_name1=param_value1>'

list fas_custom_parameters_list '<param_name2=param_value2>'

etc.

Configuration for custom parameters in the installed ThemeSpec Files

The installed ThemeSpec files are:

theme_click-to-continue-custom-placeholders

and

theme_user-email-login-custom-placeholders

list fas_custom_parameters_list 'logo_message=openNDS:%20Perfect%20on%20OpenWrt!'

list fas_custom_parameters_list 'banner1_message=BlueWave%20-%20Wireless%20Network%20Specialists'

list fas_custom_parameters_list 'banner2_message=HMS%20Pickle'

list fas_custom_parameters_list 'banner3_message=SeaWolf%20Cruiser%20Racer'

Define Custom Variables

Custom Variables are used by FAS to dynamically collect information from clients

Default None

Custom Variables are listed in the form of var_name=var_type

"var_name" and "var_type" must be urlencoded if containing white space or single quotes

eg replace spaces with %20 - replace single quotes with %27

Variables should be configured one per line to prevent possible parsing errors.

eg:

list fas_custom_variables_list '<var_name1=var_type1>'

list fas_custom_variables_list '<var_name2=var_type2>'

etc.

FAS Generic Variables

A custom FAS or ThemeSpec must be written to make use of FAS Generic Variables

eg:

list fas_custom_variables_list 'membership_number=number'

list fas_custom_variables_list 'access_code=password'

ThemeSpec Dynamically generated Form Fields

ThemeSpec scripts can dynamically generate Form Field html and inject into the dynamic splash page sequence.

This is achieved using a SINGLE line containing the keyword "input", in the form: fieldname:field-description:fieldtype

Numerous fields can be defined in this single "input=" line, separated by a semicolon (;).

Configuration for custom variables in the installed ThemeSpec Files

theme_click-to-continue-custom-placeholders

and

theme_user-email-login-custom-placeholders

This example inserts Phone Number and Home Post Code fields:

list fas_custom_variables_list 'input=phone:Phone%20Number:text;postcode:Home%20Post%20Code:text'

Define Custom Images

Custom Images are served by a local FAS where required in dynamic portal pages

Default None

Custom images will be copied from the URL to the openNDS router

Custom Images are listed in the form of image_name_type=image_url

image_name and image_url must be urlencoded if containing white space or single quotes

The image url must begin with http:// https:// or file://

Images should be configured one per line to prevent possible parsing errors.

list fas_custom_images_list '<image_name1_[type]=image_url1>'

list fas_custom_images_list '<image_name2_[type]=image_url2>'

etc.

"type" can be any recognised image file extension eg jpg, png, ico, etc.

Configuration for custom images in the installed ThemeSpec Files

theme_click-to-continue-custom-placeholders

and

theme_user-email-login-custom-placeholders

list fas_custom_images_list 'logo_png=https://openwrt.org/_media/logo.png'

list fas_custom_images_list 'banner1_jpg=https://raw.githubusercontent.com/openNDS/openNDS/v9.0.0/resources/bannerbw.jpg'

list fas_custom_images_list 'banner2_jpg=https://raw.githubusercontent.com/openNDS/openNDS/v9.0.0/resources/bannerpickle.jpg'

list fas_custom_images_list 'banner3_jpg=https://raw.githubusercontent.com/openNDS/openNDS/v9.0.0/resources/bannerseawolf.jpg'

Define Custom Files

Custom Files are served by a local FAS where required in dynamic portal pages

Default None

Custom files will be copied from the URL to the openNDS router

Images should be configured one per line to prevent possible parsing errors.

Custom files are listed in the form of file_name_type=file_url

file_name and file_url must be urlencoded if containing white space or single quotes

The file url must begin with http:// https:// or file://

list fas_custom_files_list '<file_name1_[type]=file_url1>'

list fas_custom_files_list '<file_name2_[type]=file_url2>'

"type" can be any recognised file extension that can be used to display web content eg txt, htm etc.

URLs using the file:// protocol must point to a valid mountpoint accessible to openNDS, for example a usb storage device.

Configuration for custom files in the installed ThemeSpec Files

theme_click-to-continue-custom-placeholders

and

theme_user-email-login-custom-placeholders

list fas_custom_files_list 'advert1_htm=https://raw.githubusercontent.com/openNDS/openNDS/v9.0.0/resources/bannerpickle.htm'

Set refresh interval for downloads

Set refresh interval for downloaded remote files (in minutes)

Default 0

A setting of 0 (zero) means refresh is disabled.

This is useful for providing automated refreshing of informational or advertising content. Should the remote resources become unavailable, current versions will continue to be used.

Example, set to twelve hours (720 minutes):

option remotes_refresh_interval '720'

Use outdated libmicrohttpd (MHD)

Default 0 (Disabled)

Warning, enabling this may cause instability or in the worst case total failure - it would be better to upgrade MHD.

Use at your own risk.

Older versions of MHD use an older version of the MHD API and may not run correctly or fail.

Older versions of MHD convert & and + characters to spaces when present in form data. This can make a PreAuth or BinAuth impossible to use for a client if form data contains either of these characters eg. in username or password.

There may well be other issues with older versions.

MHD versions earlier than 0.9.71 are detected.

If this option is set to 0 (default), NDS will terminate if MHD is earlier than 0.9.71

If this option is set to 1, NDS will attempt to start and log an error.

option use_outdated_mhd '1'

Maximum Page Size to be served by MHD

Default 10240 bytes

Minimum value 1024 bytes

Maximum - limited only by free RAM in the router

This sets the maximum number of bytes that will be served per page by the MHD web server.

Setting this option is useful:

1.
To reduce memory requirements on a resource constrained router
2.
To allow large pages to be served where memory usage is not a concern



Example:

option max_page_size '4096'

MHD Unescape callback

Default 0 (Disabled)

MHD has a built in unescape function that urldecodes incoming queries from browsers.

This advanced option allows an external unescape script to replace the built in decoder.

The script must be named unescape.sh, be present in /usr/lib/opennds/ and be executable.

A very simple standard unescape.sh script is installed by default.

Set to 1 to enable this option, 0 to disable.

Example:

option unescape_callback_enabled '1'

Set the MHD WebRoot

Default: /etc/opennds/htdocs

The local path where the system css file, and other static page content resides.

ie. Serve the file splash.css from this directory

Example:

option webroot '/etc/opennds/htdocs'

Set the GatewayInterface

Default br-lan

Use this option to set the device opennds will bind to.

The value may be an interface section in /etc/config/network or a device name such as br-lan.

The selected interface must be allocated an IPv4 address.

In OpenWrt this is normally br-lan, in generic Linux it might be wlan0

option gatewayinterface 'br-lan'

Set the GatewayPort

Default: 2050

openNDS's own http server (MHD) uses the gateway address as its IP address.

This option sets the port it listens to.

Example:

option gatewayport '2080'

Set the GatewayName

Default: openNDS

gatewayname is used as an identifier for the instance of openNDS

It is displayed on the default splash page sequence for ThemeSpec and the example php scripts.

It is particularly useful in the case of a single remote FAS server that serves multiple openNDS sites, allowing the FAS to customise its response for each site.

Note: The single quote (or apostrophe) character ('), cannot be used in the gatewayname.

If it is required, use the htmlentity &#39; instead.

For example:

option gatewayname 'Bill's WiFi' is invalid.

Instead use:

option gatewayname 'Bill&#39;s WiFi'

Example:

option gatewayname 'OpenWrt openNDS'

Serial Number Suffix Enable

Appends a serial number suffix to the gatewayname string.

openNDS constructs a serial number based on the router mac address and adds it to the gatewayname

Default 1 (enabled)

To disable, set to 0

Example:

option enable_serial_number_suffix '0'

Set GatewayFQDN

Default: status.client

This is the simulated FQDN used by a client to access the Client Status Page

If not set, the Status page can be accessed at: http://gatewayaddress:gatewayport/

Warning - if set, services on port 80 of the gateway will no longer be accessible (eg Luci AdminUI)

By default, the Error511/Status page will be found at http://status.client/ by a redirection of port 80 to http://gatewayaddress:gatewayport/

Disable GatewayFQDN by setting the option to 'disable'

ie:

option gatewayfqdn 'disable'

Alternate Useful Example:

option gatewayfqdn 'login.page'

Set StatusPath

Default: /usr/lib/opennds/client_params.sh

This is the script used to generate the GatewayFQDN client status page.

Example:

option statuspath '/mycustomscripts/custom_client_params.sh'

Set MaxClients

Default 250

The maximum number of clients allowed to connect.

This should be less than or equal to the number of allowed DHCP leases. set for the router's dhcp server.

Example:

option maxclients '500'

Client timeouts in minutes

Preauthidletimeout

Default 30

This is the time in minutes after which a client is disconnected if not authenticated.

ie the client has not attempted to authenticate for this period.

Example:

option preauthidletimeout '60'

Authidletimeout

Default 120

This is the time in minutes after which an idle client is disconnected ie the client has not used the network access for this period

Example:

option authidletimeout '60'

Session Timeout

Default 1440 minutes (24 hours).

This is the interval after which clients are forced out (a value of 0 means never).

Clients will be deauthenticated at the end of this period.

Example: Set to 20 hours (1200 minutes).

option sessiontimeout '1200'

Set the Checkinterval

The interval in seconds at which openNDS checks client timeouts, quota usage and runs watchdog checks.

Default 15 seconds (one quarter of a minute).

Example: Set to 30 seconds.

option checkinterval '30'

Set Rate Quotas

Defaults 0

Integer values only.

NOTE:

Upload means to the Internet, download means from the Internet.


If the client average data rate exceeds the value set here, the client will be rate limited.

Values are in kb/s.

If set to 0, there is no limit.

Quotas and rates can also be set by FAS via Authmon Daemon, ThemeSpec scripts, BinAuth, and ndsctl auth. Values set by these methods, will override values set in the config file.

Rates:

option uploadrate '200'

option downloadrate '800'

Set Bucket Ratio

Default 10

Upload and Download bucket ratios can be defined.

Allows control of upload rate limit threshold overrun per client.

Used in conjunction with MaxDownloadBucketSize and MaxUploadBucketSize.

Facilitates calculation of a dynamic "bucket size" or "queue length" (in packets) to be used for buffering upload and download traffic to achieve rate restrictions defined in this config file or by FAS for individual clients.

If a bucket becomes full, packets will overflow and be dropped to maintain the rate limit.

To minimise the number of dropped packets the bucket ratio can be increased whilst still maintaining the configured rate restriction.

*CAUTION* Large values may consume large amounts of memory per client.

If the client's average rate does not exceed its configured value within the ratecheck window interval (See RateCheckWindow option), no memory is consumed.

If the rate is set to 0, the Bucket Ratio setting has no meaning and no memory is consumed.

Examples:

option upload_bucket_ratio '1'

option download_bucket_ratio '5'



MaxDownloadBucketSize

Default: 250

Allows control over download rate limiting packet loss at the expense of increased latency.

*CAUTION* Large values may consume large amounts of memory per client.

Allowed Range 5 to 10000

Example:

option max_download_bucket_size '100'

MaxUploadBucketSize

Default 250

Allows control over upload rate limiting packet loss at the expense of increased latency.

*CAUTION* Large values may consume large amounts of memory per client.

Allowed Range 5 to 10000

Example:

option max_upload_bucket_size '100'

DownLoadUnrestrictedBursting

Default 0

Enables / disables unrestricted bursting

Setting to 0 disables

Setting to 1 enables

If enabled, a client is allowed unrestricted bursting until its average download rate exceeds the set download rate threshold.

Unrestricted bursting minimises memory consumption at the expense of potential short term bandwidth hogging.

If disabled, a client is not allowed unrestricted bursting.

Example:

option download_unrestricted_bursting '1'

UpLoadUnrestrictedBursting

Default 0

Enables / disables unrestricted bursting

Setting to 0 disables

Setting to 1 enables

If enabled, a client is allowed unrestricted bursting until its average upload rate exceeds the set upload rate threshold.

Unrestricted bursting minimises memory consumption at the expense of potential short term bandwidth hogging.

If disabled, a client is not allowed unrestricted bursting.

Example:

option upload_unrestricted_bursting '1'

Set RateCheckWindow

Default 2

The client data rate is calculated using a moving average.

This allows clients to burst at maximum possible rate, only rate limiting if the moving average exceeds the specified upload or download rate.

The moving average window size is equal to ratecheckwindow times checkinterval (seconds).

Example: Set to 3 checkinterval periods:

option ratecheckwindow '3'

Disable Rate Quotas

All rate limits can be globally disabled by setting this option to 0 (zero).

Example: Disable all rate quotas for all clients, overriding settings made in FAS via Authmon Daemon, ThemeSpec scripts, BinAuth, and ndsctl auth:

option ratecheckwindow '0'

Set Volume Quotas

Defaults 0

Integer values only.

Values are in kB.

If set to 0, there is no limit.

If the client data quota exceeds the value set here, the client will be deauthenticated.

The client by default may re-authenticate. It is the responsibility of the FAS (whether Themespec, other local or remote) to restrict further authentication of the client if so desired.

Example:

option uploadquota '1000'

option downloadquota '10000'

Enable BinAuth Support.

Default disabled

BinAuth enables POST AUTHENTICATION PROCESSING and and is useful in particular when a FAS is configured remotely.

If set, a BinAuth program or script is triggered by several possible methods and is called with several arguments on both authentication and deauthentication.

Possible methods

Authentication:

"auth_client": Request for authentication received from the captive portal splash page.

"client_auth": Acknowledgement that Client was authenticated via this script.

"ndsctl_auth": Client was authenticated by ndsctl auth command.



Deauthentication:

"client_deauth": Client deauthenticated by the client via captive portal splash page.

"idle_deauth": Client was deauthenticated because of inactivity.

"timeout_deauth": Client was deauthenticated because the session timed out.

"ndsctl_deauth": Client was deauthenticated by ndsctl deauth command.

"uprate_deauth": Client was deauthenticated because its average upload rate exceeded the allowed value.

"downrate_deauth": Client was deauthenticated because its average download rate exceeded the allowed value.

"upquota_deauth": Client was deauthenticated because its upload quota exceeded the allowed value.

"downquota_deauth": Client was deauthenticated because its download quota exceeded the allowed value.

"shutdown_deauth": Client was deauthenticated by openNDS terminating.



A fully functional BinAuth script is pre-installed and provides local logging of client activity.

This is enabled by the following option:

option binauth '/usr/lib/opennds/binauth_log.sh'

Set Fasport

Default: Not set.

This is the Forwarding Authentication Service (FAS) port number.

Redirection is changed to the IP port of a FAS (provided by the system administrator).

NOTE:

If FAS is running locally (ie fasremoteip is NOT set), port 80 cannot be used.


Typical Remote Shared Hosting Example:

option fasport '80'

Typical Locally Hosted example (ie fasremoteip not set):

option fasport '2090'

Set Fasremotefqdn

Default: Not set.

If set, this is the remote fully qualified domain name (FQDN) of the FAS.

The protocol must NOT be prepended to the FQDN (ie http:// or https://).

To prevent CPD or browser security errors NDS prepends the required http:// or https:// before redirection, depending upon the fas_secure_enabled option.

If set, DNS MUST resolve fasremotefqdn to be the same ip address as fasremoteip.

Remote Shared Hosting

Typical Remote Shared Hosting Example (replace this with your own FAS FQDN):

option fasremotefqdn 'onboard-wifi.net'

CDN (Content Delivery Network) hosted server

For a CDN (Content Delivery Network) hosted server, the configuration is the same as for Remote Shared Hosting but fasremotefqdn must also be added to the Walled Garden list of FQDNs

Set the Fasremoteip

Default: GatewayAddress (the IP of NDS)

If set, this is the remote ip address of the FAS.

Typical Remote Shared Hosting Example (replace this with your own remote FAS IP):

option fasremoteip '46.32.240.41'

Set the Faspath

Default: /

This is the path from the FAS Web Root to the FAS login page (not the file system root).

In the following examples, replace with your own values for faspath:

Typical Remote Shared Hosting Example (if fasremotefqdn is not specified):
option faspath '/remote_host_fqdn/fas/fas-hid.php'


Typical Remote Shared Hosting Example (ie BOTH fasremoteip AND fasremotefqdn set):

option faspath '/fas/fas-hid.php'


Typical Locally Hosted Example (ie fasremoteip not set):

option faspath '/fas/fas-hid.php'




Set the Faskey

Default: 1234567890

A key phrase for NDS to encrypt the query string sent to FAS.

Can be any text string with no white space.

Option faskey must be pre-shared with FAS. (It is automatically pre-shared with Themespec files)

option faskey 'mysecretopenNDSfaskey'

Set Security Level: fas_secure_enabled

Default: 1

Level set to 0

  • The FAS is enforced by NDS to use http protocol.
  • The client token is sent to the FAS in clear text in the query string of the redirect along with authaction and redir.

Note: This level is insecure and can be easily bypassed



Level set to 1

  • The FAS is enforced by NDS to use http protocol.
  • The client token will be hashed and sent to the FAS along with other relevant information in a base 64 encoded string

FAS must return the sha256sum of the concatenation of hid (the hashed original token), and faskey to be used by openNDS for client authentication.



Level set to 2

  • The FAS is enforced by NDS to use http protocol.
  • The parameters clientip, clientmac, gatewayname, hid(the hashed original token), gatewayaddress, authdir, originurl and clientif
  • are encrypted using faskey and passed to FAS in the query string.
  • The query string will also contain a randomly generated initialization vector to be used by the FAS for decryption.
  • The cipher used is "AES-256-CBC".
  • The "php-cli" package and the "php-openssl" module must both be installed for fas_secure level 2 and 3. openNDS does not depend on this package and module, but will exit gracefully not installed when this level is set.
  • The FAS must use the query string passed initialisation vector and the pre shared fas_key to decrypt the query string.



An example FAS level 2 php script (fas-aes.php) is included in the /etc/opennds directory and also supplied in the source code.

Level set to 3

  • The FAS is enforced by NDS to use https protocol.
  • Level 3 is the same as level 2 except the use of https protocol is enforced for FAS.
  • In addition, the "authmon" daemon is loaded.
  • Level 3 allows the external FAS, after client verification, to effectively traverse inbound firewalls and address translation to achieve NDS authentication without generating browser security warnings or errors.



An example FAS level 3 php script (fas-aes-https.php) is included in the /etc/opennds directory and also supplied in the source code.

Note: Option faskey must be pre shared with the FAS script in use (including any ThemeSpec local file) if fas secure is set to levels 1, 2 and 3.

Example:

option fas_secure_enabled '3'

Set PreAuth

Default Not set, or automatically set by "option login_option_enabled".

PreAuth support allows FAS to call a local program or script with html served by the built in NDS web server.

If the option is set, it points to a program/script that is called by the NDS FAS handler.

All other FAS settings will be overridden.

Example:

option preauth '/path/to/myscript/myscript.sh'

Access Control For Authenticated Users

Block Access For Authenticated Users (block)

Default: None

If Block Access is specified, an allow or passthrough must be specified afterwards as any entries set here will override the access default.

Examples:

You might want to block entire IP subnets. e.g.:

list authenticated_users 'block to 123.2.3.0/24'

list authenticated_users 'block to 123.2.0.0/16'

list authenticated_users 'block to 123.0.0.0/8'



or block access to a single IP address. e.g.:

list authenticated_users 'block to 123.2.3.4'


Do not forget to add an allow or passthrough if the default only is assumed (see Grant Access)

Grant Access For Authenticated Users (allow and passthrough)

Access can be allowed by openNDS directly, overriding the operating system firewall rules

or

Access can be allowed by openNDS but the final decision can be passed on to the operating system firewall.

Default:

No Entry, equivalent to

list authenticated_users 'passthrough all'


Any entries set here, or above in Block Access, will override the default

Example:

list authenticated_users 'allow all'

Example:

Grant access to https web sites, subject to the operating system's firewall rules

list authenticated_users 'passthrough tcp port 443'


Grant access to http web sites, overriding the operating system firewall rules.

list authenticated_users 'allow tcp port 80'


Grant access to udp services at address 123.1.1.1, on port 5000, overriding the operating system firewall rules.

list authenticated_users 'allow udp port 5000 to 123.1.1.1'


Access Control For Preauthenticated Users:

***IMPORTANT***


To support RFC8910 Captive Portal Identification

AND to help prevent DNS tunnelling, DNS Hijacking and generally improve security,

***DO NOT ALLOW ACCESS TO EXTERNAL DNS SERVICES***




Walled Garden Access For Preauthenticated Users

You can allow preauthenticated users to access external services This is commonly referred to as a Walled Garden.

  • Manually for known ip addresses
  • Autonomously from a list of FQDNs and ports


Manual Walled Garden configuration

Manual Walled Garden configuration requires research to determine the ip addresses of the Walled Garden site(s).

This can be problematic as sites can use many dynamic ip addresses.

However, manual configuration does not require any additional dependencies (ie additional installed packages).

Manual configuration example:

list preauthenticated_users 'allow tcp port 80 to 112.122.123.124'

list preauthenticated_users 'allow udp port 8020 to 112.122.123.124'

Autonomous Walled Garden configuration

Autonomous Walled Garden configuration is activated using a list of FQDNs and Ports.

This has the advantage of discovering all ip addresses used by the Walled Garden sites.

But it does require the ipset and dnsmasq-full packages to be installed by running the following commands (on OpenWrt):

opkg update

opkg install ipset

opkg remove dnsmasq

opkg install dnsmasq-full

Configuration is then a simple matter of adding two lists as follows:

list walledgarden_fqdn_list 'fqdn1 fqdn2 fqdn3 .... fqdnN'

list walledgarden_port_list 'port1 port2 port3 .... portN'

Note: If walledgarden_port_list is NOT specified, then Walled Garden access is granted for all protocols (tcp, udp, icmp) on ALL ports for each fqdn specified in walledgarden_fqdn_list.

Note: If walledgarden_port_list IS specified, then:

  • Specified port numbers apply to ALL FQDN's specified in walledgarden_fqdn_list.
  • Only tcp protocol Walled Garden access is granted.



Add Facebook to the Walled Garden

To add Facebook to the Walled Garden, the list entries would be:

list walledgarden_fqdn_list 'facebook.com fbcdn.net' list walledgarden_port_list '443'

Add Paypal to the Walled Garden

To add Paypal to the Walled Garden, the list entries would be:

list walledgarden_fqdn_list 'paypal.com paypalobjects.com'

list walledgarden_port_list '443'

User Access to Services On the Router

Access is automatically granted to resources required for normal operation of the captive portal.

Additional access falls into two categories:

Essential Access

It is essential that you allow ports for DNS and DHCP (unless you have a very specific reason for doing so, disabling these will soft brick your router!):

list users_to_router 'allow tcp port 53'

list users_to_router 'allow udp port 53'

list users_to_router 'allow udp port 67'

Optional Access

You may wish to allow access to specific services on the router.

For example - Allow ports for SSH/Telnet/HTTP/HTTPS:

list users_to_router 'allow tcp port 22'

list users_to_router 'allow tcp port 23'

list users_to_router 'allow tcp port 80'

list users_to_router 'allow tcp port 443'

MAC Address Access Control List

A list of MAC addresses can be defined that are either allowed to use the system, or are blocked.

Note: This can easily be bypassed as a client MAC address can usually be easily changed.

The mechanism used is either 'allow' or 'block' (It cannot be both).

Examples:

option macmechanism 'allow'

list allowedmac '00:00:C0:01:D0:0D'

list allowedmac '00:00:C0:01:D0:1D'

or

option macmechanism 'block'

list blockedmac '00:00:C0:01:D0:2D'

Trusted Clients

A list of the MAC addresses of client devices that do not require authentication can be defined.

NOTE:

This can easily be be used to allow unauthorised access as a client MAC address can be changed. For a potentially more secure alternative, see "option allow_preemptive_authentication"


Example:

list trustedmac '00:00:C0:01:D0:0D'

list trustedmac '00:00:C0:01:D0:1D'

Dhcp option 114 Enable - RFC8910

Sends "default_url" (dhcp option 114) with all replies to dhcp requests

Required for RFC8910 Captive Portal Identification

Default 1 (enabled)

To disable, set to 0

Example:

option dhcp_default_url_enable '0'

Packet Marking Compatibility

openNDS uses specific HEXADECIMAL values to mark packets used by iptables as a bitwise mask.

This mask can conflict with the requirements of other packages.

However the defaults are fully compatible with the defaults used in mwan3 and sqm

Any values set here are interpreted as in hex format.

Option: fw_mark_authenticated

Default: 30000 (0011|0000|0000|0000|0000 binary)

Option: fw_mark_trusted

Default: 20000 (0010|0000|0000|0000|0000 binary)

Option: fw_mark_blocked

Default: 10000 (0001|0000|0000|0000|0000 binary)

Examples:

option fw_mark_authenticated '30000'

option fw_mark_trusted '20000'

option fw_mark_blocked '10000'

CUSTOM PARAMETERS, VARIABLES, IMAGES AND FILES

Custom Parameters were first introduced in openNDS version 7. With version 9.0.0, custom variables, images and files have been added.

Custom Parameters

Custom parameters are defined in the config file and are sent as fixed values to FAS in the encoded/encrypted query string where they can be parsed and used by the FAS.

This is particularly useful in a remote or centralised FAS that is serving numerous instances of openNDS at different locations/venues.

  • Any number of Custom Parameters can be listed in the configuration file, but each one must be in a separate entry in the form of "param_name=param_value"
  • param_name and param_value must be urlencoded if containing white space or single quotes.

For example in the OpenWrt UCI config file:

list fas_custom_parameters_list '<param_name1=param_value1>'

list fas_custom_parameters_list '<param_name2=param_value2>'

etc.

A real example might be:

list fas_custom_parameters_list 'location=main_building'

list fas_custom_parameters_list 'admin_email=norman@bates-motel.com>'

For a small text strings with spaces, replace each space with %20

The following Working Example applies to the installed ThemeSpec scripts:
theme_click-to-continue-custom-placeholders

and

theme_user-email-login-custom-placeholders





list fas_custom_parameters_list 'logo_message=openNDS:%20Perfect%20on%20OpenWrt!'

list fas_custom_parameters_list 'banner1_message=BlueWave%20-%20Wireless%20Network%20Specialists'

list fas_custom_parameters_list 'banner2_message=HMS%20Pickle'

list fas_custom_parameters_list 'banner3_message=SeaWolf%20Cruiser%20Racer'

Custom Variables

Custom variables are defined in the config file and are sent as fixed placeholders to FAS in the encoded/encrypted query string where they can be parsed and used by the FAS, generally for user input via html forms added by the installer to suit the requirements of the venue.

Custom Dynamically Generated Form Fields

Custom Dynamically Generated Form Fields are a special case of Custom Variables.

ThemeSpec scripts can dynamically generate Form Field html and inject this into the dynamic splash page sequence.

This is achieved using a SINGLE line containing the keyword "input", in the form: fieldname:field-description:fieldtype

Numerous fields can be defined in this single "input=" line, separated by a semicolon (;).

The following Working Example applies to the installed ThemeSpec scripts:

theme_click-to-continue-custom-placeholders

and

theme_user-email-login-custom-placeholders





list fas_custom_variables_list 'input=phone:Phone%20Number:text;postcode:Home%20Post%20Code:text'

Custom Images

Custom images are defined in the config file and are sent as fixed name/URL pairs to FAS in the encoded/encrypted query string where they can be parsed and used by the FAS, and added by the installer to suit the requirements of the venue.

The following Working Example applies to the installed ThemeSpec scripts:
theme_click-to-continue-custom-placeholders

and

theme_user-email-login-custom-placeholders





Note: These pre-installed ThemeSpec script files will automatically download remote images to volatile storage on the router.

list fas_custom_images_list 'logo_png=https://openwrt.org/_media/logo.png'

list fas_custom_images_list 'banner1_jpg=https://raw.githubusercontent.com/openNDS/openNDS/v9.5.0/resources/bannerbw.jpg'

list fas_custom_images_list 'banner2_jpg=https://raw.githubusercontent.com/openNDS/openNDS/v9.5.0/resources/bannerpickle.jpg'

list fas_custom_images_list 'banner3_jpg=https://raw.githubusercontent.com/openNDS/openNDS/v9.5.0/resources/bannerseawolf.jpg'

Custom Files

Custom files are defined in the config file and are sent as fixed name/URL pairs to FAS in the encoded/encrypted query string where they can be parsed and used by the FAS, and added by the installer to suit the requirements of the venue. (in the same way as custom images)

The following Working Example applies to the installed ThemeSpec scripts:
theme_click-to-continue-custom-placeholders

and

theme_user-email-login-custom-placeholders





Note: These pre-installed ThemeSpec script files will automatically download remote files to volatile storage on the router.

list fas_custom_files_list 'advert1_htm=https://raw.githubusercontent.com/openNDS/openNDS/v9.5.0/resources/bannerpickle.htm'

FORWARDING AUTHENTICATION SERVICE (FAS)

Overview

openNDS (NDS) has the ability to forward requests to a third party authentication service (FAS). This is enabled via simple configuration options.

1.
fasport. This enables Forwarding Authentication Service (FAS). Redirection is changed from the default ThemeSpec to a separate FAS. The value is the IP port number of the FAS.
2.
fasremoteip. If set, this is the remote ip address of the FAS, if not set it will take the value of the NDS gateway address.
3.
fasremotefqdn If set, this is the remote fully qualified domain name (FQDN) of the FAS
4.
faspath. This is the path from the FAS Web Root (not the file system root) to the FAS login page.
5.
fas_secure_enabled. This can have four values, "0", "1", "2" or "3" providing different levels of security.
6.
faskey Used in combination with fas_secure_enable level 1, 2 and 3, this is a key phrase for NDS to encrypt data sent to FAS.


NOTE:

FAS (and Preauth/FAS) enables pre authentication processing. NDS authentication is the process that openNDS uses to allow a client device to access the Internet through the Firewall. In contrast, Forward Authentication is a process of "Credential Verification", after which FAS, if the verification process is successful, passes a request to NDS for access to the Internet to be granted for that client.


Using FAS

Note: All addresses (with the exception of fasremoteip) are relative to the client device, even if the FAS is located remotely.

When FAS is enabled, openNDS automatically configures firewall access to the FAS service.

The FAS service must serve a splash page of its own to replace the openNDS served output of the default ThemeSpec script. For fas_secure_enable "0", "1", and "2" this is enforced as http. For fas_secure_enable level "3", it is enforced as https.

Typically, the FAS service will be written in PHP or any other language that can provide dynamic web content.

FAS can then generate an action form for the client, typically requesting login, or self account creation for login.

The FAS can be on the same device as openNDS, on the same local area network as NDS, or on an Internet hosted web server.

Security

If FAS Secure is enabled (Levels 1 (default), 2 and 3), the client authentication token is kept secret at all times. Instead, faskey is used to generate a hashed id value (hid) and this is sent by openNDS to the FAS. The FAS must then in turn generate a new return hash id (rhid) to return to openNDS in its authentication request.

If set to "0" The FAS is enforced by NDS to use http protocol. The client token is sent to the FAS in clear text in the query string of the redirect along with authaction and redir. This method is easy to bypass and useful only for the simplest systems where security does not matter.

If set to "1" The FAS is enforced by NDS to use http protocol. A base64 encoded query string containing the hid is sent to the FAS, along with the clientip, clientmac, gatewayname, client_hid, gatewayaddress, authdir, originurl, clientif and custom parameters and variables.

Should the sha256sum utility not be available, openNDS will terminate with an error message on startup.

If set to "2" The FAS is enforced by NDS to use http protocol.

clientip, clientmac, gatewayname, client_hid, gatewayaddress, authdir, originurl and clientif are encrypted using faskey and passed to FAS in the query string.

The query string will also contain a randomly generated initialization vector to be used by the FAS for decryption.

The cipher used is "AES-256-CBC".

The "php-cli" package and the "php-openssl" module must both be installed for fas_secure level 2.

openNDS does not depend on this package and module, but will exit gracefully if this package and module are not installed when this level is set.

The FAS must use the query string passed initialisation vector and the pre shared fas_key to decrypt the query string. An example FAS level 2 php script (fas-aes.php) is stored in the /etc/opennds directory and also supplied in the source code. This should be copied the the web root of a suitable web server for use.

If set to "3" The FAS is enforced by openNDS to use https protocol. Level 3 is the same as level 2 except the use of https protocol is enforced for FAS. In addition, the "authmon" daemon is loaded. This allows the external FAS, after client verification, to effectively traverse inbound firewalls and address translation to achieve NDS authentication without generating browser security warnings or errors. An example FAS level 3 php script (fas-aes-https.php) is pre-installed in the /etc/opennds directory and also supplied in the source code. This should be copied the the web root of a suitable web server for use.

Option faskey has a default value. It is recommended that this is set to some secret value in the config file and the FAS script set to use a matching value, ie faskey must be pre-shared with FAS.



Example FAS Query strings

Level 0 (fas_secure_enabled = 0)
NDS sends the token and other information to FAS as clear text.

http://fasremoteip:fasport/faspath?authaction=http://gatewayaddress:gatewayport/opennds_auth/?clientip=[clientip]&gatewayname=[gatewayname]&tok=[token]&redir=[requested_url]

Note: a knowledgeable user could bypass FAS, so running fas_secure_enabled at level 1, 2 or 3 is recommended.



Level 1 (fas_secure_enabled = 1)

NDS sends a query string containing a base64 encoded string containing required parameters and variables, plus any FAS variables generated in the client dialogue, such as username and email address. The client token is never exposed.

Example Level 1 query string:

http://fasremotefqdn:fasport/faspath?fas=[b64encodedstring]&username=[client_username]&emailaddr=[client_email]


The b64encoded string will contain a comma space separated list of parameters.

The decoded string received by FAS will be of the form:

[varname1]=[var1], [varname2]=[var2], ..... etc (the separator being comma-space).



For example:

clientip=[clientipaddress], clientmac=[clientmacaddress], gatewayname=[gatewayname], client token, gatewayaddress, authdir, originurl


The FAS must return the hash of the concatenated hid value and the value of faskey identified in the query string as "tok". NDS will automatically detect this.

Levels 2 and 3 (fas_secure_enabled = 2 and fas_secure_enabled = 3), openNDS sends encrypted information to FAS.

http://fasremotefqdn:fasport/faspath?fas=[aes-256-cbc data]&iv=[random initialisation vector] (level 2)

https://fasremotefqdn:fasport/faspath?fas=[aes-256-cbc data]&iv=[random initialisation vector] (level 3)

It is the responsibility of FAS to decrypt the aes-256-cbc data it receives, using the pre shared faskey and the random initialisation vector.


The decrypted string received by FAS will be of the form: [varname1]=[var1], [varname2]=[var2], ..... etc. (the separator being comma-space).

For example:

clientip=[clientipaddress], clientmac=[clientmacaddress], gatewayname=[gatewayname], client token, gatewayaddress, authdir, originurl


It is the responsibility of FAS to parse the decrypted string for the variables it requires.



Example scripts

Full details of how to use FAS query strings can be seen in the example scripts, fas-hid.php, fas-aes.php and fas-aes-https.php

Custom Parameters

Custom Parameters are primarily intended to be used by remote configuration tools and are generally useful for passing static information to a remote FAS.

A list of Custom Parameters can be defined in the configuration file. Once a custom parameter is defined in the configuration, its value will be fixed.

Parameters must be of the form param_name=param_value and may not contain white space or single quote characters.

Custom parameters are added to the base64 encoded query string when FAS level 1 is set or the basic login option is used. Note the basic login option is a special case of FAS level 1 running a ThemeSpec script.

Custom parameters are added to the encrypted query string when FAS levels 1, 2 and 3 are set.

The fas_custom_parameters_list option in the configuration file is used to set custom parameters. This is detailed in the default configuration file.

It is the responsibility of FAS to parse the query string for the custom parameters it requires.

Network Zones - Determining the Interface the Client is Connected To

The Network coverage of a Captive Portal can take many forms, from a single SSID through to an extensive mesh network.

Using FAS, it is quite simple to dynamically adapt the Client Login page depending on the Network Zone a client is connected to. NDS can determine the local interface or 802.11s mesh network node a client is using. A simple lookup table can then be included in a custom FAS, relating interfaces or mesh nodes to sensibly named coverage zones.

A very simple example would be a captive portal set up with a wireless network for "Staff", another for "Guests" and office machines connected via ethernet.

  • Ethernet connected office machines would gain access by simply clicking "Continue".
  • Staff mobiles connect to the Staff WiFi using a standard access code then clicking "Continue".
  • Guests connect to the open Guest Wifi and are required to enter details such as Name, email address etc.



NDS is aware of the interface or mesh node a client is using.

For a FAS using fas_secure_enabled = 2, an additional variable, clientif, is sent to the FAS in the encrypted query string (local or remote FAS).

For all other levels of fas_secure_enabled, PreAuth and BinAuth, the library utility "get_client_interface" is required to be used by the relevant script (local FAS only).

Working examples can be found in the included scripts:

  • fas-aes.php
  • ThemeSpec
  • demo-preauth.sh
  • demo-preauth-remote-image.sh



For details of the clientif variable and how to use get_client_interface, see the section Library Utilities.

After Successful Verification by FAS

If the client is successfully verified by the FAS, FAS will send the return hash id (rhid) to openNDS to finally allow the client access to the Internet.

Post FAS processing

Once the client has been authenticated by the FAS, NDS must then be informed to allow the client to have access to the Internet.

The method of achieving this depends upon the fas_secure_enabled level.

Authentication Method for fas_secure_enabled levels 0,1 and 2

Once FAS has verified the client credentials, authentication is achieved by accessing NDS at a special virtual URL.

This virtual URL is of the form:

http://[nds_ip]:[nds_port]/[authdir]/?tok=[token]&redir=[landing_page_url]&custom=

This is most commonly achieved using an html form of method GET. The parameter redir can be the client's originally requested URL sent by NDS, or more usefully, the URL of a suitable landing page.



The login_option/Themespec special case

The default "login_option" library, libopennds.sh, is a local script so has access to ndsctl auth method of authentication without needing the authmon daemon so uses this rather than the authdir GET method detailed above. This means Themespec can directly set client quotas without requiring BinAuth.

Authentication Method for fas_secure_enabled level 3 (Authmon Daemon)

When fas_secure_enabled level 3 is used (https protocol), post verification authentication is achieved by the openNDS Authmon daemon.

Authmon is started by openNDS to facilitate NAT traversal and allow a remote https FAS to communicate with the local openNDS.

FAS will deposit client authentication variables for the Authmon daemon to use for the authentication process. These variables are as follows:

  • rhid: The return hashed ID of the client to be authenticated
  • sessionlength: length of session - minutes
  • uploadrate: maximum allowed upload data rate - kbits/sec
  • downloadrate: maximum allowed download data rate - kbits/sec
  • uploadquota: allowed upload data quota - kBytes
  • downloadquota: allowed download data quota - kBytes
  • custom: A custom data string that will be sent to BinAuth

Details can be found in the example script fas-aes-https.php



Be aware that many client CPD processes will automatically close the landing page as soon as Internet access is detected.

BinAuth Post FAS Processing

As BinAuth can be enabled at the same time as FAS, a BinAuth script may be used for custom post FAS processing. (see BinAuth).

The example BinAuth script, binauth_log.sh, is designed to locally log details of each client authentication and receives client data including the token, ipaddress and macaddress. In addition it receives the custom data string sent from FAS.

Manual Access of NDS Virtual URL

If the user of an already authenticated client device manually accesses the NDS Virtual URL, they will be redirected back to FAS with the "status" query string.

This will be of the form:

http://fasremoteip:fasport/faspath?clientip=[clientip]&gatewayname=[gatewayname]&status=authenticated



FAS should then serve a suitable error page informing the client user that they are already logged in.

Running FAS on your openNDS router

FAS has been tested using uhttpd, lighttpd, ngnix, apache and libmicrohttpd.

Running on OpenWrt with uhttpd/PHP:

A FAS service may run quite well on uhttpd (the web server that serves Luci) on an OpenWrt supported device with 8MB flash and 32MB ram but shortage of ram will be an issue if more than two or three clients log in at the same time.

For this reason a device with a minimum of 8MB flash and 64MB ram is recommended.



A device with 16MB flash or greater and 128MB ram or greater is recommended as a target for serious development.

Although port 80 is the default for uhttpd, it is reserved for Captive Portal Detection so cannot be used for FAS. uhttpd can however be configured to operate on more than one port.

We will use port 2080 in this example.

Install the module php7-cgi. Further modules may be required depending on your requirements.

To enable FAS with php in uhttpd you must add the lines:

list listen_http 0.0.0.0:2080

list interpreter ".php=/usr/bin/php-cgi"



to the /etc/config/uhttpd file in the config uhttpd 'main' or first section.

The two important NDS options to set will be:

1.
fasport. We will use port 2080 for uhttpd
2.
faspath. Set to, for example, /myfas/fas.php, your FAS files being placed in /www/myfas/



Using a Shared Hosting Server for a Remote FAS

A typical Internet hosted shared server will be set up to serve multiple domain names.

To access yours, it is important to configure the two options:

fasremoteip = the ip address of the remote server

AND

fasremotefqdn = the Fully Qualified Domain name of the remote server





Using a CDN (Content Delivery Network) Hosted Server for a Remote FAS

This is essentially the same as using a Shared Hosting Server with the additional requirement of also adding fasremotefqdn to the Walled Garden configuration.

The setting for fasremoteip should be one of the valid IPv4 addresses of your CDN service.



Using the FAS Example Scripts (fas-hid, fas-aes.php and fas-aes-https.php)

These three, fully functional, example FAS scripts are included in the package install and can be found in the /etc/opennds folder. To function, they need to be copied to the web root or a folder in the web root of your FAS http/php server.

fas-hid.php

You can run the FAS example script, fas-hid.php, locally on the same device that is running NDS, or remotely on an Internet based FAS server.

The use of http protocol is enforced. fas-hid is specifically targeted at local systems with insufficient resources to run PHP services, yet facilitate remote FAS support without exposing the client token or requiring the remote FAS to somehow access the local ndsctl.

If run locally on the NDS device, a minimum of 64MB of ram may be sufficient, but 128MB or more is recommended.

If run on a remote FAS server, a minimum of 32MB of ram on the local device may be sufficient, but 64MB or more is recommended.

fas-aes.php

You can run the FAS example script, fas-aes.php, locally on the same device that is running NDS (A minimum of 64MB of ram may be sufficient, but 128MB is recommended), or remotely on an Internet based FAS server. The use of http protocol is enforced.

fas-aes-https.php

You can run the FAS example script, fas-aes-https.php, remotely on an Internet based https FAS server. The use of https protocol is enforced.

On the openNDS device, a minimum of 64MB of ram may be sufficient, but 128MB is recommended.

Example Script File fas-aes.php

Http protocol is enforced.

Assuming you have installed your web server of choice, configured it for port 2080 and added PHP support using the package php7-cgi, you can do the following.

(Under other operating systems you may need to edit the opennds.conf file in /etc/opennds instead, but the process is very similar.)
  • Install the packages php7-cli and php7-mod-openssl
  • Create a folder for the FAS script eg: /[server-web-root]/nds/ on the Internet FAS server
  • Place the file fas-aes.php in /[server-web-root]/nds/

    (You can find it in the /etc/opennds directory.)

  • Edit the file /etc/config/opennds

adding the lines:
option fasport '2080'

option faspath '/nds/fas-aes.php'

option fas_secure_enabled '2'

option faskey '1234567890'





Restart NDS using the command service opennds restart



Example Script File fas-aes-https.php

Https protocol is enforced.

Assuming you have access to an Internet based https web server you can do the following.

(Under other operating systems you may need to edit the opennds.conf file in /etc/opennds instead, but the process is very similar.)
  • Install the packages php7-cli and php7-mod-openssl on your NDS router
  • Create a folder for the FAS script eg: /[server-web-root]/nds/ on the Internet FAS server
  • Place the file fas-aes.php in /[server-web-root]/nds/

    (You can find it in the /etc/opennds directory.)

  • Edit the file /etc/config/opennds

adding the lines:
option fasport '443' (or the actual port in use if different)

option faspath '/nds/fas-aes-https.php'

option fas_secure_enabled '3'

option faskey '1234567890'

option fasremoteip '46.32.240.41' (change this to the actual ip address of the remote server)

option fasremotefqdn 'blue-wave.net' (change this to the actual FQDN of the remote server)





Restart NDS using the command service opennds restart



Example Script File fas-hid.php

Http protocol is enforced.

fas-hid.php can be configured to be run locally or remotely in the same basic way as fas-aes.

However it is targeted for use on devices with limited resources as it does not require openNDS to have locally installed php-cli modules.

It uses fas_secure_enabled level 1, but sends a digest of the client token to the remote FAS. The digest is created using faskey, so the client token is not exposed.

The fas-hid.php script then uses this digest along with the pre shared faskey to request authentication by openNDS, thus mitigating any requirement for remotely accessing ndsctl that otherwise would be required.

Assuming you have access to an Internet based http web server you can do the following.

(Under other operating systems you may need to edit the opennds.conf file in /etc/opennds instead, but the process is very similar.)
  • Create a folder for the FAS script eg: /[server-web-root]/nds/ on the Internet FAS server
  • Place the file fas-hid.php in /[server-web-root]/nds/

    (You can find it in the /etc/opennds directory.)

  • Edit the file /etc/config/opennds

adding the lines:
option fasport '80' (or the actual port in use if different)

option faspath '/nds/fas-hid.php'

option fas_secure_enabled '1'

option faskey '1234567890'

option fasremoteip '46.32.240.41' (change this to the actual ip address of the remote server)

option fasremotefqdn 'blue-wave.net' (change this to the actual FQDN of the remote server)





Restart NDS using the command service opennds restart



Changing faskey

The value of option faskey should of course be changed, but must also be pre-shared with FAS by editing the example or your own script to match the new value.

THEMESPEC SCRIPT FILES

Overview

ThemeSpec Script files are an evolution of the original PreAuth/Login-Option scripts that were introduced to provide dynamic splash page sequences without requiring a separate web server or additional dependencies.

From openNDS version 9 onwards, a library script provides resources for openNDS to use. In addition, a standardised method for including themed specification files is provided. These files are used by the library script to generate the required html for the specified theme and functionality required for the venue.

Pre-installed ThemeSpec script files

Four pre-installed ThemeSpec script files are included. These provide a "Click to Continue" and a "Username/Email" sequence of "splash" pages.

The first two of these examples are selected using:

option login_option_enabled '1' (for click to continue - the default)

and

option login_option_enabled '2' (for username/email login)

Mode 1 selects the script file theme_click-to-continue.sh for inclusion.

Mode 2 selects the script file theme_user-email-login.sh for inclusion.

Automated Content Updates

The final two examples enable automated updating of content from remote sources. This is ideal for dynamic serving of venue information, news and advertising. These options are selected using:

option login_option_enabled '3'

option themespec_path '/usr/lib/opennds/theme_click-to-continue-custom-placeholders.sh'

for click to continue (with custom content) and

option themespec_path '/usr/lib/opennds/theme_user-email-login-custom-placeholders.sh'

for username-email login (with custom content).

The content to be downloaded is then specified in the configuration. See "ThemeSpec Templates" below.

libopennds.sh

This utility controls many of the functions required for PreAuth/ThemeSpec scripts.

Warning: This file will not normally be modified for customisation of the splash page sequence. Do not edit unless you know what you are doing!

Customisation should be carried out in a related Themespec file.

Usage: libopennds arg1 arg2 ... argN
arg1: "?fas=<b64string>", generates ThemeSpec html using b64encoded data sent from openNDS
arg2: urlencoded_useragent_string

arg3: mode (1, 2 or 3) (this is the mode specified in option login_option in the config file.

arg4: themespecpath (if mode = 3. Will be supplied by the call from openNDS)



returns: html for the specified ThemeSpec.





ThemeSpec Templates

Two additional example Themespec script files are provided. These make full use of custom parameters, custom variables, custom images and custom files to define custom placeholders.

1.
theme_click-to-continue-custom-placeholders.sh
2.
theme_user-email-login-custom-placeholders.sh


The first gives a click to continue login, but with the custom placeholders in place.

The second gives the user email login with custom placeholders.

These two are very similar with a login form added to the second.

The second file will be used here as an example template.

Template: theme_user-email-login-custom-placeholders.sh

The default openNDS config file contains the custom options ready to uncomment.

These options are as follows:

list fas_custom_parameters_list 'logo_message=openNDS:%20Perfect%20on%20OpenWrt!'

list fas_custom_parameters_list 'banner1_message=BlueWave%20-%20Wireless%20Network%20Specialists'

list fas_custom_parameters_list 'banner2_message=HMS%20Pickle'

list fas_custom_parameters_list 'banner3_message=SeaWolf%20Cruiser%20Racer'

list fas_custom_variables_list 'input=phone:Phone%20Number:text;postcode:Home%20Post%20Code:text'

list fas_custom_images_list 'logo_png=https://openwrt.org/_media/logo.png'

list fas_custom_images_list 'banner1_jpg=https://raw.githubusercontent.com/openNDS/openNDS/9.0.0/resources/bannerbw.jpg'

list fas_custom_images_list 'banner2_jpg=https://raw.githubusercontent.com/openNDS/openNDS/9.0.0/resources/bannerpickle.jpg'

list fas_custom_images_list 'banner3_jpg=https://raw.githubusercontent.com/openNDS/openNDS/9.0.0/resources/bannerseawolf.jpg'

list fas_custom_files_list 'advert1_htm=https://raw.githubusercontent.com/openNDS/openNDS/9.0.0/resources/bannerpickle.htm'

As can be seen, these are of the form: placeholder=value

Custom Parameters

In this case the custom parameters each define a short text string. These strings will be used as titles for custom images.

Custom Images

The custom images define remote image files with the URL for download. The images will be downloaded and saved in the tmpfs volatile storage of the router. The themespec script will add the images and the custom parameters (as titles) to the output html served to the client.

Custom Files

A single custom file is defined. This is a remote html file that is downloaded in the same way as custom images are. This downloaded file is included in the html at the relevant placeholder location in the html served to the client.

Custom Variables

A single custom variable is defined. Instead of a single placeholder, in this case, the variable definition has the keyword "input=".

The value of this variable is used by the themespec script to inject a list of html form input fields, the location in the output html determined by placeholders.

In this case the custom variable value is:

phone:Phone%20Number:text;postcode:Home%20Post%20Code:text

This is a list of semi-colon separated fields.

Each field is a colon separated field specification in the form of name:title:type.

In this example we have two input fields:

  • name=phone, title=Phone%20Number, and input type=text
  • name=postcode, title=Home%20Post%20Code



The resulting html served to the client will have two additional input fields on the login page ie. phone number and post code.

Note: Spaces must be url encoded ie replaced with %20, to prevent parsing issues.

Serving the Splash Page Sequence

When a client connects, openNDS calls the libopennds.sh library script passing a request for client verification along with information about the client device. This information is b64encoded into a single argument.

This argument is identified by the initial character string "?fas="

The libopennds library then decodes the string and parses for data required for verification and logging.

The libopennds library then calls the themespec file configured in the openNDS config.

For this example theme_user-email-login-custom-placeholders is called:

  • The themespec script sets Quotas and Data Rates that may be required for this theme, overriding global values. These new values, if set, can be set again later in this script on a client by client basis if required. In this case we will set them to "0" (zero), meaning the global values will take effect.
  • The themespec script then configures itself for any custom requirements such as parameters, images, files and form inputs.
  • Control is then passed back to libopennds
  • libopennds then calls download_image_files() if required by themespec. Files are not downloaded if already present.
  • libopennds then calls download_data_files() if required by themespec. Files are not downloaded if already present.
  • libopennds then sends the html page header to openNDS to be served to the client.
  • libopennds checks if "Terms of Service" has been clicked and if it has, calls display_terms().
  • libopennds checks if the landing page has been requested and if it has, calls landing_page().
  • libopennds calls generate_splash_sequence() in the themespec script.
  • themespec checks if this is the initial redirect of the client. If is is, the first page of the splash page sequence is then served ie the "login page".
  • themespec serves the second page of the splash sequence (thankyou page) once the login page is completed by the client.
  • themespec returns to libopennds with a request for authentication once the "thankyou page" is accepted by the client.
  • libopennds calls landing_page() - the landing page defined in themespec is served to the client.
  • libopennds finally calls openNDS to authenticate the client, passing on any quotas specific to the theme or client.



PREAUTH OPTION

Overview

PreAuth is an implementation of FAS without the resource utilisation of a separate web server, particularly useful for legacy devices with limited flash and RAM capacity.

PreAuth is a pre-authentication process that enables NDS to directly serve dynamic web content generated by a script or executable program, using its own built in Web server.

NOTE:

PreAuth is the underlying method used by Themespec scripts.


A custom PreAuth script can be enabled by configuring openNDS FAS to point to a virtual URL in the openNDS webserver root instead of an independent FAS server. The location of the PreAuth script or program is configured in the config file.

The PreAuth script can be a shell script or any other script type that an interpreter is available for (for example, PHP-cli, Python etc.).

It can even be a compiled executable binary program if desired, for example, a compiled program written in C or any other language that has a compiler available for the platform.

The PreAuth script or program will parse the url encoded command line (query string) passed to it and output html depending on the contents of the query string it receives from openNDS. In turn, openNDS will serve this html to the client device that is attempting to access the Internet.

Configuring a Custom PreAuth

A custom PreAuth is set up using the standard NDS configuration for FAS (See the Forwarding Authentication Service (FAS) section of this documentation).

In addition a single PreAuth configuration option is required to inform NDS of the location of the PreAuth script or program.

1.
fasport. This enables FAS and must be set to the same value as the gateway port.
2.
faspath. This must be set to the PreAuth virtual url, "/opennds_preauth/" by default.
3.
preauth. This the path to the PreAuth script.


The remaining FAS configuration options must be left unset at the default values.

1.
fasremoteip. Not set (defaults to the gateway ip address).
2.
fasremotefqdn. Not set.
3.
fas_secure_enable. Not set (defaults to enabled).


What Does the Default PreAuth Login Script Do?

It generates html output for openNDS to serve as a dynamic series of splash pages. The html it outputs can dynamically change according to the inputs received from a client in the html forms it generates.

Writing A PreAuth Script

A Preauth script can be written as a shell script or any other language that the system has an interpreter for. It could also be a complied program.

openNDS calls the PreAuth script with a b64 encoded argument containing the equivalent of an html query string but with ", " (comma space) in place of "&" (ampersand).

Full details of programming a custom PreAuth script can be found by reading and following the login flow in the libopennds script and accompanying ThemeSpec files.

Custom Parameters, Variables, Images and Files

Custom Parameters, Variables, Images and Files, defined in the config and the definitions are passed to PreAuth in the b64 encoded query string as well as being cached in a local database file for each client.

BINAUTH OPTION

Overview

BinAuth provides a method of running a post authentication script or extension program. BinAuth is ALWAYS local to NDS and as such will have access to all the resources of the local system.

BinAuth is available when FAS is used at all levels of fas_secure_enabled (0, 1, 2 and 3).

A custom variable is forwarded to BinAuth This can contain an embedded payload of custom data defined by the FAS. As FAS is typically remote from the NDS router, this provides a link to the local system.

BinAuth has the means to override session timeout, data rate and data volume quotas on a client by client basis.

BinAuth is called by openNDS at the following times:

  • After the client CPD browser makes an authentication request to openNDS
  • After the client device is granted Internet access by openNDS
  • After the client is deauthenticated by request
  • After the client idle timeout interval has expired
  • After the client session timeout interval has expired
  • After a data upload or download quota has been exceeded
  • After the client is authenticated by ndsctl command
  • After the client is deauthenticated by ndsctl command
  • After NDS has received a shutdown command



BinAuth Command Line Arguments

When OpenNDS calls the configured BinAuth script, it sends a set of command line arguments depending on the reason for the call.

BinAuth Command Methods

The first argument, arg[1], is always the "method".

  • "auth_client" This is a request for authentication by the client.
  • "client_auth" This is an acknowledgement of successful authentication by NDS.
  • "client_deauth" This is an acknowledgement that the client has been deauthenticated by NDS.
  • "idle_deauth" - NDS has deauthenticated the client because the idle timeout duration has been exceeded.
  • "timeout_deauth" - NDS has deauthenticated the client because the session length duration has been exceeded.
  • "downquota_deauth" - NDS has deauthenticated the client because the client's download quota has been exceeded
  • "upquota_deauth" - NDS has deauthenticated the client because the client's upload quota has been exceeded
  • "ndsctl_auth" - NDS has authorised the client because of an ndsctl command (for example, sent by the NDS AuthMon daemon).
  • "ndsctl_deauth" - NDS has deauthenticated the client because of an ndsctl command.
  • "shutdown_deauth" - NDS has deauthenticated the client because it received a shutdown command.


Additional arguments depend on the method type:

Method auth_client

The first argument is auth_client and the following arguments are set to:

  • arg[2] = client_mac
  • arg[3] = username (deprecated)
  • arg[4] = password (deprecated)
  • arg[5] = url-escaped redir variable (the URL originally requested by the client.
  • arg[6] = url-escaped client user agent string
  • arg[7] = client_ip
  • arg[8] = client_token
  • arg[9] = url-escaped custom variable string



Method ndsctl_auth

The first argument is ndsctl_auth and the following arguments are set to:

  • arg[2] = client_mac
  • arg[3] = bytes_incoming (set to 0, reserved for future use)
  • arg[4] = bytes_outgoing (set to 0, reserved for future use)
  • arg[5] = session_start - the session start time
  • arg[6] = session_end - the session end time
  • arg[7] = client_token
  • arg[8] = url-escaped custom variable string



All Other Methods

When the first argument is other than auth_client or ndsctl_auth, the following arguments are set to:

  • arg[2] = client_mac
  • arg[3] = bytes_incoming (total incoming bytes for client)
  • arg[4] = bytes_outgoing (total incoming bytes for client)
  • arg[5] = session_start - the session start time
  • arg[6] = session_end - the session end time
  • arg[7] = client_token



Using the Custom Variable string

Method auth_client - arg[9] and ndsctl_auth - arg[8], contain the url-escaped custom variable string. openNDS extracts this variable from the query string of the http auth_client call from a FAS or PreAuth page.

It is provided for general unspecified use and is url-escaped. A typical example of its use is for a level 0, 1, or 2 FAS to communicate special values for individual clients, or groups of clients.

Example BinAuth Script

An example BinAuth script is pre-installed. It provides a local NDS Access Log

NOTE:

Other example scripts from previous versions are no longer supported.


FAS is often remote from the NDS router and this script provides a simple method of interacting directly with the local openNDS. FAS can send custom data to BinAuth as a payload in the custom variable string that is relayed to BinAuth.

The log file is stored by default in the operating system tmpfs volatile storage area to prevent flash storage wear.

On OpenWrt this location is /tmp/ndslog/

and on Debian and OpenSuse it is /run/ndslog/

The location is automatically detected on most operating systems.

Free space checking is done and if the log file becomes too large, logging ceases and an error is sent to syslog.

Log files do not persist through a reboot so if required the location can be changed to, for example, a USB stick.

The binauth_log example is pre-installed.

This script has a single component, the shell script:

binauth_log.sh


The file binauth_log.sh is preinstalled in the /usr/lib/opennds directory.

This is enabled by setting the BinAuth option in the config file (/etc/config/opennds on Openwrt, or /etc/opennds/opennds.conf on other operating systems.

This script is then activated with the command:

service opennds restart


WALLED GARDEN

Manual Walled Garden

Preauthenticated clients are, by default, blocked from all access to the Internet.

Access to certain web sites can be allowed. For example, clients will automatically be granted access to an external FAS server for the purpose of authentication.

Access to other web sites may be manually granted so clients can be served content such as news, information, advertising, etc. This is achieved in openNDS by allowing access to the IP address of the web sites as required.

A set of such web sites is referred to as a Walled Garden.

Autonomous Walled Garden

Granting access by specifying the site IP address works well in the simplest of cases but the administrative overhead can rapidly become very difficult, for example with social media sites that load balance high volumes of traffic over many possible IP addresses.

In addition, the IP address of any web site may change.

Rather than using IP addresses, a much more efficient method of granting access would be by using the Fully Qualified Domain Name (FQDN) of each site and have a background process populate a database of allowed IP addresses.

openNDS supports Autonomous Walled Garden by means of a simple configuration option. This does have additional dependencies but these only apply if the Autonomous Walled Garden is enabled.

OpenWrt Walled Garden

The additional dependencies are the ipset and dnsmasq-full packages. Install these by running the following commands:

opkg update
opkg install ipset
opkg remove dnsmasq
opkg install dnsmasq-full


Configure as follows:

uci add_list opennds.@opennds[0].walledgarden_fqdn_list='<fqdn1> <fqdn2> <fqdn3> [......] <fqdnN>'


where <fqdn1> to <fqdnN> are the fully qualified domain names of the URLs you want to use to populate the ipset.

eg. For Facebook use facebook.com and fbcdn.net as fqdn1 and fqdn2

In addition you can limit access to the Walled Garden to a list of IP ports:

uci add_list opennds.@opennds[0].walledgarden_port_list='<port1> <port2> <port3> [......] <portN>'


Restart openNDS to activate the Walled Garden.

To make these changes permanent (eg survive a reboot), run the command:

uci commit opennds


Generic Linux Walled Garden

On most generic Linux platforms the procedure is in principle the same as for OpenWrt.

The ipset and full dnasmasq packages are requirements.

You can check the compile time options of dnsmasq with the following command:

dnsmasq --version | grep -m1 'Compile time options:' | cut -d: -f2


If the returned string contains "no-ipset" then you will have to upgrade dnsmasq to the full version.

To enable Walled Garden, add the following to the /etc/opennds/opennds.conf file

walledgarden_fqdn_list <fqdn1> <fqdn2> <fqdn3> [......] <fqdnN>


In addition you can specify a restricted set of ports for access to the walled garden by adding the line:

walledgarden_port_list <port1> <port2> <port3> [......] <portN>


Restart openNDS to activate the Walled Garden.

Warning When Port 80 is Enabled

Port 80 is used by all devices to detect Captive Portals.

If port 80 is enabled in the Walled Garden configuration (either implicitly by adding to the ports list, or explicitly by not defining a ports list) then any Captive Portal Detection attempted by a device using a Walled Garden FQDN will fail.

For example if the FQDN "apple.com" is defined in the Walled Garden list, then Apple devices will fail to trigger the Portal Splash Page sequence (login page) if port 80 is enabled.

LIBRARY UTILITIES

Overview

A number of library utilities are included. These may be used by NDS itself, FAS and Preauth. These may in the future, be enhanced, have additional functionality added.

By default, library utilities will be installed in the folder

/usr/lib/opennds/

List of Library Utilities

get_client_interface.sh

This utility allows the interface a client is using to be determined from the client mac address.

It can be used in PreAuth and local FAS scripts.

Its output is also sent to FAS in the encrypted query string as the variable "clientif"

Usage: get_client_interface.sh [clientmac]

Returns: [local_interface] [meshnode_mac] [local_mesh_interface]

Where:

[local_interface] is the local interface the client is using.

[meshnode_mac] is the mac address of the 802.11s meshnode the client is using (null if mesh not present).

[local_mesh_interface] is the local 802.11s interface the client is using (null if mesh not present).





unescape.sh

This utility allows an input string to be unescaped. It currently only supports url-decoding.

It can be used by NDS as the unescape callback for libmicrohttpd.

To enable, set the unescape_callback_enabled option to "1"

To disable, set the unescape_callback_enabled option to "0"

The default is disabled (use internal MHD unescape)

eg In the OpenWrt configuration file

option unescape_callback_enabled '0'


Usage: unescape.sh [-option] [escapedstring]

Returns: [unescapedstring]

Where:

[-option] is unescape type, currently -url only




libopennds.sh

This utility controls many of the functions required for PreAuth/ThemeSpec scripts.

Usage: libopennds arg1 arg2 ... argN


clean:

arg1: "clean", removes custom files, images and client data

returns: tmpfsmountpoint (the mountpoint of the tmpfs volatile storage of the router.



tmpfs:

arg1: "tmpfs", finds the tmpfs mountpoint

returns: tmpfsmountpoint (the mountpoint of the tmpfs volatile storage of the router.



mhdcheck:

arg1: "mhdcheck", checks if MHD is running (used by MHD watchdog)

returns: "1" if MHD is running, "2" if MHD is not running



gatewaymac:

arg1: "gatewaymac", finds the mac address of an interface.
arg2: ifname


returns: mac address of the interface



gatewayroute:

arg1: "gatewayroute", checks for a valid gateway route for an interface.

returns: the ip gateway address and the ip gateway interface, or "offline" if the router is offline



clientaddress:

arg1: "clientaddress", find and return both ip and mac of a client
arg2: contains either client mac or client ip


returns: client ip and mac



rmcid:

arg1: "rmcid", Remove an existing cidfile (client identifcation file)
arg2: contains the cid (client id)

arg3: contains mountpoint of the ndscids database



returns: "done"



write:

arg1: "write", Write client info element to cidfile (client identifcation file)
arg2: contains the cid (client id)

arg2: contains mountpoint of the ndscids database

arg3: contains info element



returns: "done"



parse:

arg1: "parse", Parse for sub elements and write to cidfile (client identification file)
arg2: contains the cid (client id)

arg3: contains mountpoint of the ndscids database

arg4: contains info elements to parse



returns: "done"



download:

arg1: "download", Download files required for themespec
arg2: contains the themespec path

arg3: contains the image list

arg4: contains the file list

arg5: contains the refresh flag, set to 0 to download if file missing, 1 to refresh downloads, 3 to skip downloads

arg6: contains the webroot



returns: "done"



get_option_from_config:

arg1: "get_option_from_config", Get the config option value
arg2: contains the option to get


returns: the requested config option, or an empty string if not configured



debuglevel:

arg1: "debuglevel", Sets the debuglevel for externals
arg2: contains the debuglevel


returns: the debuglevel



get_debuglevel:

arg1: "get_debuglevel", Gets the debuglevel set for externals


returns: the debuglevel



syslog:

arg1: "syslog", Write a debug message to syslog
arg2: contains the string to to write to syslog if enabled by debuglevel

arg3: "debugtype" contains debug type: debug, info, warn, notice, err, emerg.





returns: "done"



startdaemon:

arg1: "startdaemon", Start a daemon process
arg2: contains the b64 encoded daemon startup command


returns: pid of the daemon and exit code 0 if successful. If unsuccessful or terminated immediately returns "0" or a status information string with code 1



stopdaemon:

arg1: "stopdaemon", Stop a daemon process
arg2: contains the pid of the daemon to stop


returns: "done" if successful or "nack" with exit code 1 if unsuccessful



get_interface_by_ip:

arg1: "get_interface_by_ip", get the interface name that is the gateway for an IP address
arg2: contains the ip to check


returns: Interface name with exit code 0, or exit code 1 if failed to get interface name



write_log:

arg1: "write_log", write a string to the openNDS log
arg2: contains the string to log


returns: "done"



dhcpcheck:

arg1: "dhcpcheck", Checks if an ip address was allocated by dhcp
arg2: contains the ip to check


returns: The mac address that was allocated to the ip address or null and exit code 1 if not allocated



?fas:

arg1: "?fas=<b64string>", generates ThemeSpec html using b64encoded data sent from openNDS
arg2: urlencoded_useragent_string

arg3: mode (1, 2 or 3) (this is the mode specified in option login_option in the config file.

arg4: themespecpath (if mode = 3)



returns: html for the specified ThemeSpec.



USING NDSCTL

openNDS includes ndsctl, a separate utility application. Some command line options:

To print to stdout the status of the openNDS daemon:
/usr/bin/ndsctl status


To print to stdout the list of clients and trusted devices in json format:
/usr/bin/ndsctl json


To print to stdout the details of a particular client in json format (This is particularly useful if called from a FAS or Binauth script.):
/usr/bin/ndsctl json [mac|ip|token|hid]

Note: clients that are not in the preauthenticated state (ie CPD has not triggered redirection) will not be authenticated unless the configuration option "allow_preemptive_authentication" is enabled.



To authenticate client given their IP or MAC address:
/usr/bin/ndsctl auth IP|MAC


To deauthenticate a currently authenticated client given their IP or MAC address:
/usr/bin/ndsctl deauth IP|MAC


To b64encode a plain text string:
/usr/bin/ndsctl b64encode "character string"


To b64decode a b64encoded string:
/usr/bin/ndsctl b64decode "b64encodedstring"


To set the verbosity of logged messages to n:
/usr/bin/ndsctl debuglevel n


  • debuglevel 0 : Silent (only LOG_ERR and LOG_EMERG messages will be seen, otherwise there will be no logging.)
  • debuglevel 1 : LOG_ERR, LOG_EMERG, LOG_WARNING and LOG_NOTICE (this is the default level).
  • debuglevel 2 : debuglevel 1 + LOG_INFO
  • debuglevel 3 : debuglevel 2 + LOG_DEBUG

All other levels are undefined and will result in debug level 3 being set.


For details, run ndsctl -h. (Note that the effect of ndsctl commands does not persist across openNDS restarts.)

DATA QUOTAS AND TRAFFIC SHAPING

Data volume and Rate Quotas

openNDS (NDS) has built in Data Volume and Data Rate quota support.

Data volume and data rate quotas can be set globally in the config file.

The global values can be overridden on a client by client basis as required.

Global Data Volume Quota

If a client exceeds the global data volume quota, or the individual client quota, that client will be forced out by deauthentication. To continue, the client must re-authenticate.

Configuring Data Volume Quotas

Global volume quotas are configured in the config file.

Example UCI configuration options:

# If the client data quota exceeds the value set here, the client will be forced out
# Values are in kB
# If set to 0, there is no limit
# Integer values only
#
option uploadquota '0'
option downloadquota '0'


Note: upload means to the Internet, download means from the Internet

Quotas for individual clients will override configured global values and are set either by BinAuth or the Authmon Daemon (fas_secure_enable level 3) - see example BinAuth script (binauth_log.sh) and example FAS script (fas-aes-https.php).

Data Rate Quota Threshold

Both upload and download data rate quotas are a threshold above which traffic is rate limited using a dynamic bucket filter.

There are no additional packages required or further dependencies.

The client data rate is calculated using a moving average.

If the client's average rate exceeds the set quota, packets will be queued using a dynamic bucket filter. This allows clients to burst at a rate exceeding the set quota for a short interval thus improving the user experience compared with a fixed ceiling rate limit.

Upload and download rate limiting is provided independently for upload and download traffic.

The configured rate quotas can be overridden on a client by client basis according to criteria determined by the FAS.

The moving average window size is equal to ratecheckwindow times checkinterval (seconds).

The default value of ratecheckwindow is 2 and is a good working setting. Increasing the value allows a longer period of bursting. Setting to 0 disables all Data Rate Quotas.

Data Rate Quotas are ideal for allowing opening of web pages and emails etc in the fastest way possible, yet preventing an individual client from monopolizing all the available bandwidth by streaming or transferring large files.

Configuring Data Rate Quotas

Data Rate quota thresholds are configured in the config file along with options that allow tuning of the bursting intervals and bucket filter sizes to suit a wide range of venue requirements.

The configuration options and their defaults are as follows:

  • ratecheckwindow (Default 2)
  • download_bucket_ratio (Default 10)
  • upload_bucket_ratio (Default 10)
  • max_download_bucket_size (Default 250)
  • max_upload_bucket_size (Default 250)
  • download_unrestricted_bursting (Default 0, disabled)
  • upload_unrestricted_bursting (Default 0, disabled)
  • downloadrate (Default 0, unlimited)
  • uploadrate (Default 0, unlimited)

See the Configuration Options section for details.

Note: upload means to the Internet, download means from the Internet

Data Rate Quotas for Individual Clients

Data Rate Quotas for individual clients will override configured global values and are set by ThemeSpec, BinAuth or the Authmon Daemon.

FAS Level 3

FAS level 3 uses the Authmon daemon to set quota values determined by the FAS. The example script fas-aes-https.php shows how to implement this.

FAS level 0, 1 and 2

These levels can either use BinAuth to set quota values determined by the FAS, or if local to the router can use ndsctl authentication with quota values passed as arguments.

If using BinAuth, the FAS would utilise the BinAuth custom variable to send quota values to a BinAuth script configured to interpret the data passed to it in the variable. There is no set method for doing this, it is left to individual installers to develop their own method.

Traffic Shaping

If a fixed ceiling data rate is required, third party traffic shaping packages can be used in place of the built in openNDS Rate Quota Thresholds.

For example, SQM - Smart Queue Management (sqm-scripts) package is fully compatible and available for OpenWrt and generic Linux.

See: https://github.com/tohojo/sqm-scripts

Installing SQM

The generic Linux scripts can be downloaded from the link above.

On OpenWrt, SQM can be installed from the LuCi interface or by the following CLI commands on your router:

opkg update

opkg install sqm-scripts

Note: The standard and default SQM installation expects monitoring of the interface connecting to the WAN. What we need is for SQM to monitor the interface NDS is bound to. This of course will be a LAN interface. The default configuration will limit bandwidth from the WAN connection to services on the Internet. Our configuration will limit client bandwidth TO NDS, thus enabling a true fair usage policy.

To prevent confusion it is important to understand that SQM defines "Upload" as traffic "Out" of the interface SQM is monitoring and "Download" as traffic "In" to the SQM interface.

In the default SQM configuration, Upload will mean what is normally accepted, ie traffic to the Internet and Download will mean traffic from the Internet.

In our case however the terms will be reversed!

The default SQM configuration file on OpenWrt is:

config queue

option enabled '0'
option interface 'eth1'
option download '85000'
option upload '10000'
option qdisc 'fq_codel'
option script 'simple.qos'
option qdisc_advanced '0'
option ingress_ecn 'ECN'
option egress_ecn 'ECN'
option qdisc_really_really_advanced '0'
option itarget 'auto'
option etarget 'auto'
option linklayer 'none'


For simple rate limiting, we are interested in setting the desired interface and the download/upload rates.

We may also want to optimize for the type of Internet feed and change the qdisc.

A typical Internet feed could range from a high speed fiber optic connection through fast VDSL to a fairly poor ADSL connection and configured rates should be carefully chosen when setting up your Captive Portal.

A typical Captive Portal however will be providing free Internet access to customers and guests at a business or venue, using their mobile devices.

A good compromise for a business or venue might be a download rate from the Internet of ~3000 Kb/s and an upload rate to the Internet of ~1000 Kb/s will be adequate, allowing for example, a client to stream a YouTube video, yet have minimal effect on other clients browsing the Internet or downloading their emails. Obviously the values for upload and download rates for best overall performance depend on many factors and are best determined by trial and error.

If we assume we have NDS bound to interface br-lan and we have a VDSL connection, a good working setup for SQM will be as follows:

  • Rate to Internet 1000 Kb/s (but note this is from the perspective of the interface SQM is monitoring, so this means DOWNLOAD from the client).
  • Rate from Internet 3000 Kb/s (also note this is from the perspective of the interface SQM is monitoring, so is means UPLOAD to the client).
  • VDSL connection (usually an ethernet like connection)
  • NDS bound to br-lan



We will configure this by issuing the following commands:

Note the reversed "upload" and "download" values.

uci set sqm.@queue[0].interface='br-lan'
uci set sqm.@queue[0].download='1000'
uci set sqm.@queue[0].upload='3000'
uci set sqm.@queue[0].linklayer='ethernet'
uci set sqm.@queue[0].overhead='22'
uci set sqm.@queue[0].qdisc='cake'
uci set sqm.@queue[0].script='piece_of_cake.qos'
uci set sqm.@queue[0].enabled='1'
uci commit sqm
service sqm restart


Replace the linklayer and overhead values to match your Internet feed.

The following table lists LinkLayer types and Overhead for common feed types:

Connection Type LinkLayer Overhead
Fibre/Cable Ethernet 18
VDSL2 Ethernet 22
Ethernet Ethernet 38
ADSL/DSL ATM 44


Some broadband providers use variations on the values shown here, contacting them for details sometimes helps but often the request will be "off script" for a typical helpdesk. These table values should give good results regardless. Trial and error and the use of a good speed tester is often the only way forward. A good speed tester web site is http://dslreports.com/speedtest

Further details about SQM can be found at the following links:

https://openwrt.org/docs/guide-user/network/traffic-shaping/sqm

https://openwrt.org/docs/guide-user/network/traffic-shaping/sqm-details

THE CLIENT STATUS/ERROR511 PAGE

If the client is redirected by the CPI (RFC 8910) process, this page is displayed.

This page is also accessible by any connected client at the default url:

http://status.client

Default "Quick Status" and optional "Advanced Status" options can be selected.

If the client has been authenticated in the normal way by the client CPD process, a page is served displaying the Gatewayname and the Network Zone the client device is currently using.

A list of allowed quotas and current usage is displayed along with "Refresh" and "Logout" buttons.

If the client has not been authenticated, or has been deauthenticated due to timeout or quota usage, then a "Error 511 Network Authentication Required" page is displayed with "Refresh" and "Portal Login" buttons.

The "Portal Login" button allows the client to immediately attempt to login without waiting for the client CPD to trigger.

The URL used to access this page can be changed by setting the config option gatewayfqdn.

For best results it is recommended that gatewayfqdn is set to two words separated by a single period eg in OpenWrt:

option gatewayfqdn 'my.status'


Warning - if set, services on port 80 of the gateway will no longer be accessible (eg Luci AdminUI)

By default, the Error511/Status page will be found at http://status.client/ by a redirection of port 80 to http://gatewayaddress:gatewayport/

*Disable GatewayFQDN* by setting the option to 'disable' ie:

option gatewayfqdn 'disable'



An alternate Useful Example:

option gatewayfqdn 'login.page'

Custom Status Page

The default client status page is generated dynamically by the script /usr/lib/opennds/client_params.sh

An alternate Status page script can be used by setting the configuration option "statuspath" in the config file. Ensure the alternate script file is flagged as executable.

FREQUENTLY ASKED QUESTIONS

What's the difference between versions?

NoDogSplash and openNDS are derived from the same code base.

You cannot upgrade from NoDogSplash to openNDS, instead you must first uninstall NodogSplash before installing openNDS.

NoDogSplash is optimised for running on devices with very limited resources and supports only a single static templated html splash page.

openNDS supports dynamic html splash page generation (at default, still with minimal resource utilisation) and an API to support the coding of sophisticated Captive Portal solutions.

openNDS v5 This was the first release of openNDS after forking from NoDogsplash. The following enhancements are included:

  • openNDS API (FAS)

    A forwarding authentication service. FAS supports development of "Credential Verification" running on any dynamic web serving platform, on the same device as openNDS, on another device on the local network, or on an Internet hosted web server.

  • PreAuth

    An implementation of FAS running on the same device as openNDS and using openNDS's own web server to generate dynamic web pages. Any scripting language or even a compiled application program can be used. This has the advantage of not requiring the resources of a separate web server.

  • BinAuth

    Enabling an external script to be called for doing post authentication processing such as setting session durations or writing local logs.

  • Enforce HTTPS option

    This option enables https access to a remote, Internet based FAS server, ensuring the client device does not receive any security warnings or errors. Access to the FAS server using https protocol is enforced.

  • Data volume and Rate Quotas

    This option enables built in Data Volume and Data Rate quota support. Data volume and data rate quotas can be set globally in the config file. The global values can be overridden on a client by client basis as required.

  • Introduction of library scripts

    Numerous library scripts are introduced to simplify development of applications.




openNDS v6 This is the first version of openNDS to use the updated libmicrohttpd (MHD) API introduced with v0.9.71.

openNDS REQUIRES MHD v0.9.71 or higher.



openNDS v7 This version contains several major enhancements, including:

  • Autonomous Walled Garden Support

    A simple openNDS configuration option enables Autonomous Walled Garden operation based on a list of target FQDNs

  • Custom Parameter Support

    A list of static Custom Parameters can be set as a configuration option. Once set, these parameters are fixed and will be sent to remote FAS servers.

    This functionality was added specifically to support remote configuration tools such as Opensync, but can be generally useful for passing local fixed information to a remote FAS.

    It is important that this is NOT confused with the dynamic Custom Variables that can be defined as a part of a FAS/Client dialogue.

  • Legacy Templated splash.html Deprecated and Disabled

    The legacy splash.html page and its templated variables is deprecated and disabled. This is replaced by an enhanced login option script capable of generating a dynamic html dialogue. The default is a simple click to continue page, similar to the old splash.html.




openNDS v8 This version contains several major enhancements, including:

  • Base 64 encoding of the Query string

    The introduction of Base 64 encoding of the query string into the FAS API, enables easier customisation of FAS scripts.

  • Global use of Hashed ID (hid)

    Hashed ID (hid), carried in the base64 encoded query string for levels 1, 2 and 3, including the default click to continue page, provides a uniform level of security against portal bypass. The option "faskey" is now enabled at all times with a simple default value and settable in the config files and FAS scripts.

  • Client User Status Page

    A client user status page is now available at a configurable Gateway FQDN. This page includes a listing of the client's quota allocation and usage, as well as a "Logout" button. A client that is connected butnot logged in for any reason will be redirected to an RFC6585 Status Code 511 "Network Authentication Required" page with a "Login" button. the default url for a client to access their status page is http://status.client




openNDS v9 This version contains several major enhancements, including:

  • Introduction of ThemeSpec Script Files

    Option login_option is extended to include Themed page sequences with custom parameters, variables, images and files. A ThemeSpec file has the ability to inject html form fields, text strings, images from external sources and content files also from external sources, all defined in the config file.

  • Enhanced Data Rate Quotas

    Data Rate Quotas are now enhanced with packet rate limiting being applied when a client average rate rises above its preset threshold. The time window over which the rate is averaged can be tuned using settings in the config file, allowing rate bursting for best user experience while still limiting the rate of larger downloads or uploads that might otherwise impact other clients.




Can I upgrade from NoDogSplash to openNDS?

No.

You must first uninstall NoDogSplash before installing openNDS.

Can I upgrade from v5 to v6

Yes.

But you must upgrade libmicrohttpd to version v0.9.71 or higher.

Can I upgrade from v6 to v7?

You can, if:

  • You don't use RedirectURL (this has been deprecated for some time as it mostly did not work with client CPD implementations. It has now been removed. A reliable replacement is a FAS Welcome Page.
  • You don't use the Templated html splash page (splash.html). Templated splash is now deprecated and disabled. It can be re-enabled by setting the allow_legacy_splash option to allow time for migration. Support will be removed entirely in a later version.

Can I upgrade from v7 to v8?

You can, if:

  • You modify your FAS scripts to use the openNDS v8 API. The FAS query string is now either base64 encoded, or encrypted.
  • In addition Hashed ID (hid) is used for authentication, removing the need for a FAS script to somehow obtain the client Token.



Can I upgrade from v8 to v9

You can, if:

  • You modify your FAS scripts to use the openNDS v9 API
  • You move to ThemeSpec scripts or FAS from Legacy Splash. Legacy Splash Pages are no longer supported. The default ThemeSpec (option login_option 1) is equivalent to the old splash.html click to continue page.



How can I add custom parameters, such as site specific information?

Custom parameters were introduced in openNDS version 7 and are defined simply in the config file. These parameters are passed to the FAS in the query string. Version 8 embeds any custom parameters in the encoded/encrypted query string, macing it much simpler to parse for them in the FAS script.

How can I add custom fields on the login page, such as phone number, car licence plate number etc.?

A simple configuration option allows fields to be added automatically to the pages of ThemeSpec login sequences.

Is it possible to display custom info or advertising on the login pages?

Yes! Simple config options specify the URLs of images and html content. These will be automatically downloaded and injected into the dynamic pages created by suitable Themespec scripts.

How do I manage client data usage?

openNDS (NDS) has built in Data Volume and Data Rate quota support.

  • Data volume and data rate quotas can be set globally in the config file.
  • The global values can be overridden on a client by client basis as required, either by FAS or BinAuth.
  • If a client exceeds their volume quota they will be deauthenticated.
  • If a client exceeds their rate quota, they will be packet rate limited to ensure their average rate stays below the rate quota value. This allows clients to burst at a higher rate for short intervals, improving performance, but prevents them from hogging bandwidth.



Can I use Traffic Shaping with openNDS?

SQM Scripts (Smart Queue Management), is fully compatible with openNDS and if configured to operate on the openNDS interface (br-lan by default) will provide efficient IP connection based traffic control to ensure fair usage of available bandwidth.

This can be installed as a package on OpenWrt. For other distributions of Linux it is available at: https://github.com/tohojo/sqm-scripts

Is an https splash page supported?

Yes. FAS Secure Level 3 enforces https protocol for the splash login page on an external FAS server.

Is https capture supported?

No.

  • If it was supported, all connections would have a critical certificate failure.
  • HTTPS web sites are now more or less a standard and to maintain security and user confidence it is essential that captive portals DO NOT attempt to capture port 443.
  • All modern client devices have the built in, industry standard, Captive Portal Detection (CPD) service. This is responsible for triggering the captive portal splash/login page and is specifically intended to make https capture unnecessary.

What is CPD / Captive Portal Detection?

CPD (Captive Portal Detection) has evolved as an enhancement to the network manager component included with major Operating Systems (Linux, Android, iOS/MacOS, Windows).

Using a pre-defined port 80 web page (the one that gets used depends on the vendor) the network manager will detect the presence of a captive portal hotspot and notify the user. In addition, most major browsers now support CPD.


HOW TO COMPILE OPENNDS

Linux/Unix - Compile in Place on Target Hardware

Make sure the development suite for your Linux distribution is installed.

The libmicrohttpd library (MHD) is a dependency of openNDS so compiling and installing this is a prerequisite.

First, create a working directory and "cd" into it.

Next, Download and un-tar the libmicrohttpd source files.

You can find a version number for MHD at https://ftp.gnu.org/gnu/libmicrohttpd/

The version number for MHD must not exceed 0.9.70 for versions of openNDS less than 6.0.0

wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-0.9.71.tar.gz
tar  -xf libmicrohttpd-0.9.71.tar.gz
cd libmicrohttpd-0.9.71


where "0.9.71" is the MHD version number we are using in this example (use at least this version).

Now configure and compile:

./configure --disable-https
make
sudo rm /usr/local/lib/libmicrohttpd*
sudo make install
sudo rm /etc/ld.so.cache
sudo ldconfig -v
cd ..


Then proceed to download the opennds source files.

You can find a release version number for openNDS at https://github.com/openNDS/openNDS/releases

wget https://codeload.github.com/opennds/opennds/tar.gz/v7.0.1
tar -xf v9.1.0
cd openNDS-9.1.0
make
sudo make install
sudo systemctl enable opennds


Where "9.1.0" is the openNDS version we are using in this example.

openNDS should now start automatically at boot time.

It can be manually started, restarted, stopped or disabled with the following commands:

sudo systemctl start opennds
sudo systemctl restart opennds
sudo systemctl stop opennds
sudo systemctl disable opennds


The status of openNDS can be checked with the following command:

sudo ndsctl status


On most Linux distributions you can read the last few entries for openNDS in the system message log with the command:

sudo systemctl status opennds


If openNDS fails to start, check for error messages with the command:

sudo journalctl -e


OpenWrt Package

The OpenWrt package feed supports cross-compiled openNDS packages for all OpenWrt targets. See the "Installing openNDS" section of this documentation. The latest release of openNDS will be found in OpenWrt Snapshots, but will nevertheless be a stable release.

To include openNDS into your OpenWRT image or to create an .ipk package (similar to Debian's .deb files), you can build an OpenWRT image.

You need a Unix console to enter commands into.

Install the dependencies of the build environment (eg on Debian/Ubuntu):

sudo apt-get install git subversion g++ libncurses5-dev gawk zlib1g-dev build-essential


Build Commands:

git clone https://git.openwrt.org/openwrt/openwrt.git
cd openwrt
./scripts/feeds update -a
./scripts/feeds install -a
./scripts/feeds uninstall opennds
git clone git://github.com/opennds/opennds.git
cp -rf opennds/openwrt/opennds package/
rm -rf opennds/
make defconfig
make menuconfig


At this point select the appropriate "Target System" and "Target Profile" depending on what target chipset/router you want to build for. Now select the openNDS package in "Network ---> Captive Portals".

Now compile/build everything:

make


The images and all ipk packages are now inside the bin/ folder. You can install the openNDS .ipk using opkg install <ipkg-file> on the router or just use the whole image.

For details please check the OpenWRT documentation.

### Note for developers

## Build Notes

You might want to use your own source location and not the remote repository. To do this you need to checkout the repository yourself and commit your changes locally:


... apply your changes

git commit -am "my change"


Now create a symbolic link in the openNDS package folder using the absolute path:

ln -s /my/own/project/folder/opennds/.git openwrt/package/opennds/git-src


Also make sure to enable

"Advanced configuration options" => "Enable package source tree override"


in the menu when you do make menuconfig.

DEBUGGING OPENNDS

Syslog Logging

openNDS supports four levels of debugging to syslog.

  • debuglevel 0 : Silent (only LOG_ERR and LOG_EMERG messages will be seen, otherwise there will be no logging.)
  • debuglevel 1 : LOG_ERR, LOG_EMERG, LOG_WARNING and LOG_NOTICE (this is the default level).
  • debuglevel 2 : debuglevel 1 + LOG_INFO
  • debuglevel 3 : debuglevel 2 + LOG_DEBUG

All other levels are undefined and will result in debug level 3 being set.



To see maximally verbose debugging output from openNDS, set log level to 3.

On OpenWrt, you can use the following commands:

uci set opennds.@opennds[0].debuglevel='3'
uci commit opennds
service opennds restart


Debug messages are logged to syslog. You can view messages with the logread command.

The default level of logging is 1, and is more appropriate for routine use.

Logging level can also be set using ndsctl.



Firewall Cleanup

When stopped, openNDS deletes its iptables rules, attempting to leave the router's firewall in its original state. If not (for example, if openNDS crashes instead of exiting cleanly) subsequently starting and stopping openNDS should remove its rules.

On OpenWrt, restarting the firewall will overwrite openNDS's iptables rules, so when the firewall is restarted it will automatically restart openNDS if it is running.



Packet Marking

openNDS operates by marking packets. Many packages, such as mwan3 and SQM scripts, also mark packets.

By default, openNDS marks its packets in such a way that conflicts are unlikely to occur but the masks used by openNDS can be changed if necessary in the configuration file.



IPtables Conflicts

Potential conflicts may be investigated by looking at your overall iptables setup. To list all the rules in all the chains, run
iptables -L


For extensive suggestions on debugging iptables, see for example, Oskar Andreasson's tutorial at:

https://www.frozentux.net/iptables-tutorial/iptables-tutorial.html



TODO LIST

Features should be aimed at providing tools to allow openNDS to be used as flexible Captive Portal engine, rather than building in specific solutions.

Here is a list of things that should be done soon:

  • Use uci style config file for all OSes then remove opennds.conf
  • Add support for definable language lookup files for otherwise hard coded text eg http error codes

Here is a list of possible things TO DO

  • Consider providing an openNDS-mini package for OpenWrt - for legacy devices with very restricted resources.
  • ip version 6 is not currently supported by NDS. It is not essential or advantageous to have in the short term but should be added at some time in the future.
  • Automatic Offline mode/ Built in DNS forwarder. Some thought and discussion has been put into this and it is quite possible to achieve.

  • genindex
  • search

AUTHOR

The openNDS Contributors

COPYRIGHT

2015 - 2022 BlueWave Projects and Services and The openNDS Contributors <opennds@blue-wave.net>

March 18, 2022 9.7.0