Provided by: opennds-daemon-common_9.7.0-3_all 
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.
• openNDS: https://github.com/openNDS/openNDS
• Original Homepage down: http://kokoro.ucsd.edu/nodogsplash
• Archive: https://web.archive.org/web/20140210131130/http://kokoro.ucsd.edu/nodogsplash
• Wifidog: http://dev.wifidog.org/
• NoDogSplash: https://github.com/nodogsplash/nodogsplash
• GNU GPL: http://www.gnu.org/copyleft/gpl.html
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.
Typical CPD URLs used are, for example:
• http://captive.apple.com/hotspot-detect.html
• http://connectivitycheck.gstatic.com/generate_204
• http://connectivitycheck.platform.hicloud.com/generate_204
• http://www.samsung.com/
• http://detectportal.firefox.com/success.txt
• Plus many more
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
•
To install on 19.7.x or lower, download libmicrohttpd-no-ssl_0.9.71-1 or higher to the
/tmp directory on your router. Then install using the command:
opkg install <packagename> --force-reinstall
•
Similarly, download openNDS v9.0.0 or higher to /tmp, again installing using the
command:
opkg install <packagename> --force-reinstall
• 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 ' instead.
For example:
option gatewayname 'Bill's WiFi' is invalid.
Instead use:
option gatewayname 'Bill'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:
Grant access overriding operating system firewall
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.
A Walled Garden can be configured either:
• 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.
These options are:
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.
These are:
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.
In summary, the following configuration options should be set:
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.
ie:
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".
The method will be set to one of the following values:
• "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:
git clone git://github.com/opennds/opennds.git
cd opennds
... 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>