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

docs: more 4.0.2 updates

docs/source/customize.rst

@@ -11,6 +11,19 @@ As NDS is a package that requires hardware configured as an IP router, perhaps t
 
 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
 **********************
 
@@ -128,3 +141,11 @@ It should be noted when designing a custom splash page that for security reasons
  * Prohibit the execution of javascript.
 
 Also, note that any images you reference should reside in the subdirectory /etc/nodogsplash/htdocs/images/.
+
+Dynamic Splash Pages
+********************
+
+Dynamically generated splash pages are supported using FAS and PreAuth (including the included alternative username/email login script).
+
+For details see the FAS and PreAuth chapters.
+

docs/source/howitworks.rst

@@ -10,39 +10,25 @@ Summary of Operation
 
  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's built in Captive Portal Detection (CPD).
 
- 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.
 
- 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).
 
- 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's 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.
 
- 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.
+ Once the user on the client device has successfully completed the splash page actions, that page then links directly back to NDS.
 
- However if Binauth is enabled, NDS first calls the Binauth script, passing if required a username and password to that script.
+ 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.
 
- If the binauth script returns positively (ie return code 0), NDS then "authenticates" the client device, allowing access to the Internet.
+ Post authentication processing extensions may be added to NDS (See BinAuth). Once NDS has received a valid token it calls a Binauth script.
 
- 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.
+ If the BinAuth script returns positively (ie return code 0), NDS then "authenticates" the client device, allowing access to the Internet.
 
- 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.
 
 .. note::
 
- 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.
-
-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.
+ 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.
 
 Packet filtering
 ****************
@@ -64,4 +50,4 @@ Traffic control
 
 Data rate control on an IP connection basis can be achieved using Smart Queue Management (SQM) configured separately, with NDS being fully compatible.
 
-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.

docs/source/preauth.rst

@@ -9,7 +9,7 @@ Overview
 **PreAuth** is a pre-authentication process that enables NDS to directly serve dynamic web content generated by a script or executable program.
 
 .. note::
- 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 4.0.2 onwards** it is enabled by a single line in the config file that overrides any other FAS configuration. 
+ 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. **From version 4.0.2 onwards** it is enabled by a single line in the config file that overrides any other FAS configuration. 
 
 **PreAuth is enabled** 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.
 
@@ -21,7 +21,9 @@ The PreAuth script or program will parse the url encoded command line (query str
 
 Using PreAuth version 4.0.2 onwards
 ***********************************
-From version 4.0.2 onwards, PreAuth is enabled with a single line in the config files setting "option preauth".
+From version 4.0.2 onwards, PreAuth is enabled with a single configuration option:
+ * **preauth**. This the path to the PreAuth script or executable.
+
 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:
 
@@ -39,26 +41,20 @@ In addition a single PreAuth configuration option is required to inform NDS of t
 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, "/nodogsplash_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. **fas_secure_enable**. Not set (defaults to enabled).
 
-**Finally** 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.
-
 Enabling the Preinstalled Login Script (v3.3.1 to 4.0.1)
 ********************************************************
 
 .. note::
  From version 3.3.1 onwards, this example PreAuth script is preinstalled.
 
-**Enabling the Preinstalled Script**
-
 On Openwrt, edit (to uncomment) following lines in the /etc/config/nodogsplash file:
 
     `#option fasport '2050'`
@@ -198,3 +194,21 @@ 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.
 
 The query string will be truncated if it does exceed this length.
+
+Displaying Remote Banner Images
+*******************************
+
+A modified version of the Username/Email-address login script is available that demonstrates how to display remotely hosted images on its login pages.
+
+This additional example PreAuth script, demo-preauth-remote-image.sh, is available in the source code:
+
+ `https://github.com/nodogsplash/nodogsplash/archive/master.zip`
+
+and extracting from the folder:
+
+ "forward_authentication_service/PreAuth/"
+
+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.
+
+The example displays the NodogSplash avatar image dynamically retrieved from Github.
+

docs/source/splash.rst

@@ -35,51 +35,20 @@ This Splash page can be one of the following:
 The Two Installed Basic Splash Pages
 ************************************
 
-By default, two fully functional but basic "Splash" pages are installed.
- * The Simple "Click to Continue" splash page. This is enabled on installing NoDogSplash.
- * The "Username/Email-address" PreAuth script. This is enabled simply by un-commenting three lines in the config file.
+By default, two fully functional but basic "Splash" pages are installed. Simple config options allow you to choose which one to use.
 
-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.
-
-Enable Username/Email-address Login
-***********************************
-
-On Openwrt, edit (to uncomment) following lines in the /etc/config/nodogsplash file:
-
-    `#option fasport '2050'`
-
-    `#option faspath '/nodogsplash_preauth/'`
-
-    `#option preauth '/usr/lib/nodogsplash/login.sh'`
-
-To read:
-
-    `option fasport '2050'`
-
-    `option faspath '/nodogsplash_preauth/'`
-
-    `option preauth '/usr/lib/nodogsplash/login.sh'`
+ * The Simple "Click to Continue" splash page. (Default)
+ * The "Username/Email-address" Login script.
 
-For other operating systems edit the equivalent lines in the /etc/nodogsplash/nodogsplash.conf file
+*See the chapter on PreAuth for details on how to switch between these splash page types.*
 
-After making the change, save the file and restart the router.
-
-Displaying Remote Banner Images
-*******************************
-
-A modified version of the Username/Email-address login script is available that demonstrates how to display remotely hosted images on its login pages.
-
-This additional example PreAuth script, demo-preauth-remote-image.sh, is available in the source code:
-
- `https://github.com/nodogsplash/nodogsplash/archive/master.zip`
-
-and extracting from the folder:
-
- "forward_authentication_service/PreAuth/"
-
-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.
-
-The example displays the NodogSplash avatar image dynamically retrieved from Github.
+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.
 
+Displaying Remote Content
+*************************
 
+FASand PreAuth can be used to display remote content on the client user login screen.
+This is ideal for serving information, banner advertising etc.
 
+An example is described in the **Displaying Remote Banner Images**
+section of the PreAuth chapter.