github/openNDS
1
1
Fork 0
mirror of https://github.com/openNDS/openNDS.git synced 2026-05-04 03:01:32 -04:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #417 from nodogsplash/v4.0.2beta

Browse Source 
Bump to version 4.0.2
This commit is contained in:
Rob White
2019-08-15 15:38:08 +01:00
committed by GitHub
parent 59735e6b5c 89a0aadc5b
commit 0600a3258a
6 changed files with 148 additions and 119 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
ChangeLog
View File

@@ -1,3 +1,15 @@
nodogsplash (4.0.2)
* Fix bug - fas_remotefqdn not supported with option fas_secure_enabled 0 [bluewavenet]
* Fix bug - prevent deadlock causing ndsctl to hang and NDS to become unresponsive [bluewavenet]
* PreAuth - Override FAS settings making configuration foolproof [bluewavenet]
* ndsctl - make json parsing consistent for all client variables [bluewavenet]
* Fix memory leak in template generation [lynxis]
* When executing the ndsctl stop command, cleanup all structures [lynxis]
* Check for positive errno in thread_ndsctl [lynxis]
-- Rob White <dot@blue-wave.net> Mon, 15 Aug 2019 15:01:00 +0000
nodogsplash (4.0.1)
* Make debuglevel platform independent [mwarning]

12
debian/changelog vendored
View File

@@ -1,3 +1,15 @@
nodogsplash (4.0.2-1) stable; urgency=medium
* Fix bug - fas_remotefqdn not supported with option fas_secure_enabled 0 [bluewavenet]
* Fix bug - prevent deadlock causing ndsctl to hang and NDS to become unresponsive [bluewavenet]
* PreAuth - Override FAS settings making configuration foolproof [bluewavenet]
* ndsctl - make json parsing consistent for all client variables [bluewavenet]
* Fix memory leak in template generation [lynxis]
* When executing the ndsctl stop command, cleanup all structures [lynxis]
* Check for positive errno in thread_ndsctl [lynxis]
-- Rob White <dot@blue-wave.net> Mon, 15 Aug 2019 15:01:00 +0000
nodogsplash (4.0.1-1) stable; urgency=medium
* Make debuglevel platform independent [mwarning]

235
debian/doc/nodogsplash.1 vendored
View File

@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "NODOGSPLASH" "1" "Jul 29, 2019" "4.0.1" "NoDogSplash"
.TH "NODOGSPLASH" "1" "Aug 15, 2019" "4.0.2" "NoDogSplash"
.SH NAME
nodogsplash \- nodogsplash Documentation
.
@@ -54,38 +54,41 @@ how to customize its behavior for your application.
Contents:
.SH OVERVIEW
.sp
\fBNodogspash\fP (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.
\fBNoDogSplash\fP (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.
.SS Captive Portal Detection (CPD)
.INDENT 0.0
.INDENT 3.5
\fBIf you want to provide simple and immediate public access\fP to an Internet connection with users giving some acknowledgment of the service, Nodogsplash does this by default.
.sp
Customising the page seen by users is a simple matter of editing the simple default html splash page file.
.sp
\fBIf you want to enforce use of a set of preset usernames\fP and passwords with perhaps a limited connection time, the addition of a simple shell script is all that is required.
.sp
\fBIf you want a more sophisticated authentication system\fP providing a dynamic web interface you can do that too by providing your own web service written in a language such as php running on its own server.
.sp
\fBIf you want to link Nodogsplash\fP to your own centralised Internet based authentication service with user account self generation and access charging, you can do that too, or anything in between.
.sp
\fBAll modern mobile devices\fP, most desktop operating systems and most browsers now have a Captive Portal Detection process that automatically issues a port 80 request on connection to a network. Nodogsplash detects this and serves a \(aqsplash\(aq web page.
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 "\fBsplash\fP" web page to the connecting client device.
.UNINDENT
.UNINDENT
.sp
The splash page in its most basic form, contains a \fIContinue\fP button. When the user clicks on it, access to the Internet is granted subject to a preset time interval.
.sp
Nodogsplash does not currently support traffic control but is fully compatible with other stand alone systems such as Smart Queue Management (SQM).
.SS Nodogsplash Methods of authentication
.sp
Nodogsplash offers numerous methods of authentication:
.SS Provide simple and immediate public Internet access
.INDENT 0.0
.INDENT 3.5
NDS provides two pre\-installed methods.
.INDENT 0.0
.IP \(bu 2
Click the \fIContinue\fP button (default)
\fBClick to Continue\fP\&. A simple static web page with template variables (\fIdefault\fP). This provides basic notification and a simple click/tap to continue button.
.IP \(bu 2
Call an external script that may accept username/password and set session durations per user.
\fBusername/email\-address login\fP\&. A simple dynamic set of web pages that provide username/email\-address login, a welcome page and logs access by client users. (\fIInstalled by default and enabled by un\-commenting a line in the configuration file\fP)
.UNINDENT
.INDENT 0.0
.INDENT 3.5
Customising the page seen by users is a simple matter of editing the respective html or script files.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Write Your Own Captive Portal.
.INDENT 0.0
.INDENT 3.5
NDS can be used as the "Engine" behind the most sophisticated Captive Portal systems using the tools provided.
.INDENT 0.0
.IP \(bu 2
Forwarding authentication to an external service
\fBForward Authentication Service (FAS)\fP\&. 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.
.IP \(bu 2
\fBPreAuth\fP\&. 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.
.IP \(bu 2
\fBBinAuth\fP\&. A method of running a post authentication script or extension program.
.UNINDENT
.UNINDENT
.UNINDENT
@@ -219,46 +222,28 @@ By default, NDS blocks everything, but intercepts port 80 requests.
.sp
An initial port 80 request will be generated on a client device, either by the user manually browsing to an http web page, or automatically by the client device\(aqs built in Captive Portal Detection (CPD).
.sp
As soon as this initial port 80 request is received, NDS will redirect the client to either its own splash page, or a splash page on a configured Forwarding Authentication Service (FAS).
As soon as this initial port 80 request is received, NDS will redirect the client to a "splash" page.
.sp
The user of the client device will then be expected to complete some actions on the splash page, such as accepting terms of service, entering a username and password etc. (this will of course be on either the basic NDS splash.html or the page presented by the FAS, depending on the NDS configuration).
This splash page is either one of the two standard options or a custom configuration provided by the user (See FAS, PreAuth).
.sp
Once the user on the client device has successfully completed the splash page actions, the page then links directly, with a query string, to an NDS virtual http directory provided by NDS\(aqs built in web server.
The user of the client device will then be expected to complete some actions on the splash page, such as accepting terms of service, entering a username and password etc.
.sp
Once the user on the client device has successfully completed the splash page actions, that page then links directly back to NDS.
.sp
For security, NDS expects to receive the same valid token it allocated when the client issued its initial port 80 request. If the token received is valid, NDS then "authenticates" the client device, allowing access to the Internet.
.sp
However if Binauth is enabled, NDS first calls the Binauth script, passing if required a username and password to that script.
Post authentication processing extensions may be added to NDS (See BinAuth). Once NDS has received a valid token it calls a Binauth script.
.sp
If the binauth script returns positively (ie return code 0), NDS then "authenticates" the client device, allowing access to the Internet.
If the BinAuth script returns positively (ie return code 0), NDS then "authenticates" the client device, allowing access to the Internet.
.sp
In FAS secure modes (levels 1 and 2), the client token and other required information is kept securely hidden from the Client, ensuring verification cannot be bypassed.
.sp
When FAS is disabled, the token is supplied to the basic splash.html page served by NDS and passed back in clear text in the query string along with any username and password required for Binauth.
In FAS secure modes are provided (levels 1, 2 and 3), where the client token and other required variables are kept securely hidden from the Client, ensuring verification cannot be bypassed.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
FAS and Binauth can be enabled together.
This can give great flexibility with FAS providing authentication and Binauth providing post authentication processing closely linked to NDS.
.UNINDENT
.UNINDENT
.SS Rules for Customised Splash Pages
.sp
It should be noted when designing a custom splash page that for security reasons many client device CPD implementations:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Immediately close the browser when the client has authenticated.
.IP \(bu 2
Prohibit the use of href links.
.IP \(bu 2
Prohibit downloading of external files (including .css and .js, even if they are allowed in NDS firewall settings).
.IP \(bu 2
Prohibit the execution of javascript.
.UNINDENT
FAS and Binauth can be enabled together. This can give great flexibility with FAS providing authentication and Binauth providing post authentication processing closely linked to NDS.
.UNINDENT
.UNINDENT
.SS Packet filtering
@@ -286,7 +271,7 @@ Because it inserts its rules at the beginning of existing chains, nodogsplash sh
.sp
Data rate control on an IP connection basis can be achieved using Smart Queue Management (SQM) configured separately, with NDS being fully compatible.
.sp
It should be noted that while setup options and binauth do accept traffic/quota settings, these values currently have no effect and are reserved for future development.
It should be noted that while setup options and BinAuth do accept traffic/quota settings, these values currently have no effect and are reserved for future development.
.SH THE SPLASH PAGE
.sp
As you will see mentioned in the "How Nodogsplash (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\(aqs built in Captive Portal Detection (CPD).
@@ -333,66 +318,29 @@ This not only enables a dialogue with the client user, for dissemination of info
.UNINDENT
.UNINDENT
.SS The Two Installed Basic Splash Pages
.sp
By default, two fully functional but basic "Splash" pages are installed. Simple config options allow you to choose which one to use.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B By default, two fully functional but basic "Splash" pages are installed.
.INDENT 7.0
.IP \(bu 2
The Simple "Click to Continue" splash page. This is enabled on installing NoDogSplash.
The Simple "Click to Continue" splash page. (Default)
.IP \(bu 2
The "Username/Email\-address" PreAuth script. This is enabled simply by un\-commenting three lines in the config file.
The "Username/Email\-address" Login script.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fISee the chapter on PreAuth for details on how to switch between these splash page types.\fP
.sp
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.
.SS Enable Username/Email\-address Login
.SS Displaying Remote Content
.sp
On Openwrt, edit (to uncomment) following lines in the /etc/config/nodogsplash file:
.INDENT 0.0
.INDENT 3.5
\fI#option fasport \(aq2050\(aq\fP
FASand PreAuth can be used to display remote content on the client user login screen.
This is ideal for serving information, banner advertising etc.
.sp
\fI#option faspath \(aq/nodogsplash_preauth/\(aq\fP
.sp
\fI#option preauth \(aq/usr/lib/nodogsplash/login.sh\(aq\fP
.UNINDENT
.UNINDENT
.sp
To read:
.INDENT 0.0
.INDENT 3.5
\fIoption fasport \(aq2050\(aq\fP
.sp
\fIoption faspath \(aq/nodogsplash_preauth/\(aq\fP
.sp
\fIoption preauth \(aq/usr/lib/nodogsplash/login.sh\(aq\fP
.UNINDENT
.UNINDENT
.sp
For other operating systems edit the equivalent lines in the /etc/nodogsplash/nodogsplash.conf file
.sp
After making the change, save the file and restart the router.
.SS Displaying Remote Banner Images
.sp
A modified version of the Username/Email\-address login script is available that demonstrates how to display remotely hosted images on its login pages.
.sp
This additional example PreAuth script, demo\-preauth\-remote\-image.sh, is available in the source code:
.INDENT 0.0
.INDENT 3.5
\fIhttps://github.com/nodogsplash/nodogsplash/archive/master.zip\fP
.UNINDENT
.UNINDENT
.sp
and extracting from the folder:
.INDENT 0.0
.INDENT 3.5
"forward_authentication_service/PreAuth/"
.UNINDENT
.UNINDENT
.sp
This is an enhancement of the preinstalled login.sh, giving an example of how to display images pulled in from remote web servers, both http and https.
.sp
The example displays the NodogSplash avatar image dynamically retrieved from Github.
An example is described in the \fBDisplaying Remote Banner Images\fP
section of the PreAuth chapter.
.SH FORWARDING AUTHENTICATION SERVICE (FAS)
.SS Overview
.sp
@@ -504,6 +452,8 @@ For example, the following command returns just the token:
.UNINDENT
.UNINDENT
.sp
A more sophisticated json parser could be used to extract all the client variables supplied by ndsctl, an example can be found in the default PreAuth Login script in /usr/lib/nogogsplash/login.sh.
.sp
\fBLevel 2\fP (fas_secure_enabled = 2), NDS sends enrypted information to FAS.
.sp
\fIhttp://fasremotefqdn:fasport/faspath?fas=[aes\-256\-cbc data]&iv=[random initialisation vector]\fP
@@ -679,20 +629,36 @@ The value of option faskey should of course be changed, but must also be pre\-sh
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
From version 3.3.1 onwards, a PreAuth login script is preinstalled. This generates a page asking for username and email address. Logins are recorded in a log file. It is enabled by uncommenting just 3 lines in the config file.
From version 3.3.1 onwards, a PreAuth login script is pre\-installed. This generates a page asking for username and email address. Logins are recorded in a log file. It is enabled by un\-commenting just 3 lines in the config file. \fBFrom version 4.0.2 onwards\fP it is enabled by a single line in the config file that overrides any other FAS configuration.
.UNINDENT
.UNINDENT
.sp
\fBPreAuth is enabled\fP by configuring NDS FAS to point to a virtual URL in the NDS web root instead of an independent FAS server. In addition, NDS is configured with the location of the PreAuth script or program.
\fBPreAuth is enabled\fP by configuring NDS FAS to point to a virtual URL in the NDS web root instead of an independent FAS server. The location of the PreAuth script or program is provided in the config file.
.sp
\fBThe PreAuth script\fP can be a shell script or any other script type that an interpreter is available for (for example, PHP\-cli, Python etc.).
.sp
A PreAuth program could be, for example, a compiled program written in C or any other language that has a compiler available for the platform.
.sp
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 NDS. In turn, NDS will serve this html to the client device that is attempting to access the Internet.
.SS Using PreAuth
.SS Using PreAuth version 4.0.2 onwards
.INDENT 0.0
.TP
.B From version 4.0.2 onwards, PreAuth is enabled with a single configuration option:
.INDENT 7.0
.IP \(bu 2
\fBpreauth\fP\&. This the path to the PreAuth script or executable.
.UNINDENT
.UNINDENT
.sp
PreAuth is set up using the standard NDS configuration for FAS
This option overrides any other FAS configuration and takes the form of the path to the PreAuth script.
The path to the preinstalled login script is included in option preauth in the default config files, for example in OpenWrt:
.sp
\fI#option preauth \(aq/usr/lib/nodogsplash/login.sh\(aq\fP
.sp
The "#" symbol means the line is commented. To activate, remove the "#". save and restart Nodogsplash.
.SS Using PreAuth version 3.3.1 to version 4.0.1
.sp
From version 3.3.1 to version 4.0.1, PreAuth is set up using the standard NDS configuration for FAS
(See the \fBForwarding Authentication Service (FAS)\fP section of this documentation).
.sp
In addition a single PreAuth configuration option is required to inform NDS of the location of the PreAuth script or program.
@@ -704,6 +670,8 @@ In addition a single PreAuth configuration option is required to inform NDS of t
\fBfasport\fP\&. This enables FAS and \fImust\fP be set to the same value as the gateway port.
.IP 2. 3
\fBfaspath\fP\&. This \fImust\fP be set to the PreAuth virtual url, "/nodogsplash_preauth/" by default.
.IP 3. 3
\fBpreauth\fP\&. This the path to the PreAuth script.
.UNINDENT
.UNINDENT
.sp
@@ -718,22 +686,15 @@ The remaining FAS configuration options must be left unset at the default values
\fBfas_secure_enable\fP\&. Not set (defaults to enabled).
.UNINDENT
.UNINDENT
.sp
\fBFinally\fP the Preauth configuration must be set.
In OpenWrt this will be of the form
option preauth /etc/nodogsplash/demo\-preauth.sh
For other Linux distributions this is set in the nodogsplash.conf file.
.SS Enabling the Preinstalled UserName/Email\-address Login Script
.SS Enabling the Preinstalled Login Script (v3.3.1 to 4.0.1)
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
From version 3.1.1 onwards, this example PreAuth script is preinstalled.
From version 3.3.1 onwards, this example PreAuth script is preinstalled.
.UNINDENT
.UNINDENT
.sp
\fBEnabling the Preinstalled Script\fP
.sp
On Openwrt, edit (to uncomment) following lines in the /etc/config/nodogsplash file:
.INDENT 0.0
.INDENT 3.5
@@ -759,6 +720,7 @@ To read:
For other operating systems edit the equivalent lines in the /etc/nodogsplash/nodogsplash.conf file
.sp
After making the change, save the file and restart the router.
.SS What Does the Example Login Script Do?
.sp
\fBThis example shell script\fP generates html output for NDS to serve as a dynamic splash page.
.sp
@@ -923,6 +885,27 @@ See the example script which uses $username and $emailaddr
There is no limit to the number of variables we can define dynamically as long as the query string does not exceed 2048 bytes.
.sp
The query string will be truncated if it does exceed this length.
.SS Displaying Remote Banner Images
.sp
A modified version of the Username/Email\-address login script is available that demonstrates how to display remotely hosted images on its login pages.
.sp
This additional example PreAuth script, demo\-preauth\-remote\-image.sh, is available in the source code:
.INDENT 0.0
.INDENT 3.5
\fIhttps://github.com/nodogsplash/nodogsplash/archive/master.zip\fP
.UNINDENT
.UNINDENT
.sp
and extracting from the folder:
.INDENT 0.0
.INDENT 3.5
"forward_authentication_service/PreAuth/"
.UNINDENT
.UNINDENT
.sp
This is an enhancement of the preinstalled login.sh, giving an example of how to display images pulled in from remote web servers, both http and https.
.sp
The example displays the NodogSplash avatar image dynamically retrieved from Github.
.SH BINAUTH OPTION
.sp
\fBKey: BinAuth\fP
@@ -1306,6 +1289,23 @@ NDS reads its configuration file when it starts up but the location of this file
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).
.sp
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.
.SS Rules for Customised Splash Pages
.sp
It should be noted when designing a custom splash page that for security reasons many client device CPD implementations:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Immediately close the browser when the client has authenticated.
.IP \(bu 2
Prohibit the use of href links.
.IP \(bu 2
Prohibit downloading of external files (including .css and .js, even if they are allowed in NDS firewall settings).
.IP \(bu 2
Prohibit the execution of javascript.
.UNINDENT
.UNINDENT
.UNINDENT
.SS The Configuration File
.sp
In OpenWrt, or operating systems supporting UCI (such as LEDE) the configuration is kept in the file:
@@ -1488,6 +1488,11 @@ Prohibit the execution of javascript.
.UNINDENT
.sp
Also, note that any images you reference should reside in the subdirectory /etc/nodogsplash/htdocs/images/.
.SS Dynamic Splash Pages
.sp
Dynamically generated splash pages are supported using FAS and PreAuth (including the included alternative username/email login script).
.sp
For details see the FAS and PreAuth chapters.
.SH FREQUENTLY ASKED QUESTIONS
.SS What\(aqs the difference between v0.9, v1, v2, v3 and v4?
.sp

4
docs/source/conf.py
View File

@@ -60,9 +60,9 @@ author = 'The Nodogsplash Contributors'
# built documents.
#
# The short X.Y version.
version = '4.0.2beta'
version = '4.0.2'
# The full version, including alpha/beta/rc tags.
release = '4.0.2beta'
release = '4.0.2'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.

2
openwrt/nodogsplash/Makefile
View File

@@ -7,7 +7,7 @@ include $(TOPDIR)/rules.mk
PKG_NAME:=nodogsplash
PKG_FIXUP:=autoreconf
PKG_VERSION:=4.0.2beta
PKG_VERSION:=4.0.2
PKG_RELEASE:=1
PKG_SOURCE_URL:=https://codeload.github.com/nodogsplash/nodogsplash/tar.gz/v$(PKG_VERSION)?

2
src/conf.h
View File

@@ -29,7 +29,7 @@
#ifndef _CONF_H_
#define _CONF_H_
#define VERSION "4.0.2beta"
#define VERSION "4.0.2"
/*@{*/
/** Defines */