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 before you start.

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 is deprecated and disabled. It will be removed entirely in later releases.

To allow time for migration, this can be re-enabled by setting options:

allow_legacy_splash = ‘1’ and login_option_enabled = “0” (default)

The legacy splash page can be found at:

/etc/opennds/htdocs/splash.html

When the splash page is served, the following variables in the page are replaced by their values:

  • $gatewayname The value of GatewayName as set in opennds.conf.

  • $authtarget A URL which encodes a unique token and the URL of the user’s original web request. If opennds receives a request at this URL, it completes the authentication process for the client and replies to the request with a “302 Found” to the encoded originally requested URL.

    It should be noted however that, depending on vendor, the client’s built in CPD may not respond to simple html links.

An href link example that my prove to be problematical:

<a href="$authtarget">Enter</a>

(You should instead use a GET-method HTML form to send this information to the opennds server; see below.)

  • $tok, $redir, $authaction, and $denyaction are available and should be used to write the splash page to use a GET-method HTML form instead of using $authtarget as the value of an href attribute to communicate with the opennds server.

$authaction and $denyaction are virtual urls used to inform NDS that a client should be authenticated or deauthenticated and are of the form:

http://gatewayaddress:gatewayport/opennds_auth/

and

http://gatewayaddress:gatewayport/opennds_deny/

A simple example of a GET-method form:

<form method='GET' action='$authaction'>
  <input type='hidden' name='tok' value='$tok'>
  <input type='hidden' name='redir' value='$redir'>
  <input type='submit' value='Click Here to Enter'>
</form>
  • $clientip, $clientmac and $gatewaymac The respective addresses of the client or gateway. This might be useful in cases where the data needs to be forwarded to some other place by the splash page itself.
  • $nclients and $maxclients User stats. Useful when you need to display something like “n of m users online” on the splash site.
  • $uptime The time opennds has been running.

A list of all available variables are included in the splash.html file.

If the user accesses the virtual url $authaction when already authenticated, a status page is shown:

/etc/opennds/htdocs/status.html

In the status.html file, the same variables as in the splash.html site can be used.

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.

Also, note that any images you reference should reside in the subdirectory /etc/opennds/htdocs/images/.

Dynamic Splash Pages

Default Dynamic Click to Continue

The pre-installed dynamic login page is enabled by setting option login_option_enabled = “0”. This is the default assuming allow_legacy_splash = ‘0’, the default value.

It generates a Click to Continue page.

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 itself.

Pre-Installed User Login Dynamic Splash Page

The pre-installed dynamic login page is enabled by setting option login_option_enabled = “1”.

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 itself.

Custom Dynamic Splash Pages

Custom designed dynamically generated splash pages are supported using FAS and PreAuth (such as the included alternative username/email login script).

For details see the FAS and PreAuth chapters.