diff --git a/ChangeLog b/ChangeLog index feb6423..1ca1d79 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,15 @@ +nodogsplash (3.2.0) + + * Add Redirect to Status page support for FAS [bluewavenet] + * Add iptables version check [mwarning] + * Add ndsctl status output for FAS and Binauth status. [bluewavenet] + * Initialize fas_remoteip with gw_address and simplify code [mwarning] + * Fix Readthedocs updates and update Docs URL [bluewavenet] + * Update documentation and Debian man page [bluewavenet] + + -- Rob White Sun, 2 Sep 2018 16:09:00 +0000 + + nodogsplash (3.1.0) * Integrated support for separate Forward Authentication Service (FAS), adding the following configuration options [bluewavenet, mwarning]: diff --git a/README.md b/README.md index 849a995..fd39664 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,11 @@ ## 0. The Nodogsplash project -Nodogsplash offers a simple way to provide restricted access to an internet -connection. It is derived from the codebase of the Wifi Guard Dog project. +Nodogsplash is a Captive Portal that offers a simple way to provide restricted access to the Internet by showing a splash page to the user before Internet access is granted. + +It also incorporates an API that allows the creation of sophisticated authentication applications. + +It was derived originally from the codebase of the Wifi Guard Dog project. + Nodogsplash is released under the GNU General Public License. * Mailing List: http://ml.ninux.org/mailman/listinfo/nodogsplash @@ -14,23 +18,29 @@ how to customize its behavior for your application. ## 1. Overview -Nodogsplash offers a solution to this problem: You want to provide controlled -and reasonably secure public access to an internet connection; and while you -want to require users to give some acknowledgment of the service you are -providing, you don't need or want the complexity of user account names and -passwords and maintaining a separate database-backed authentication server. -When installed and running, Nodogsplash implements a simple 'authentication' -protocol. First, it detects any user attempting to use your internet connection -to request a web page. It captures the request, and instead serves back a -'splash' web page using its own builtin web server. The splash page contains a -link which, when the user clicks on it, opens limited access for them to the -internet via your connection, beginning by being redirected to their originally -requested page. This access expires after a certain time interval. -Nodogsplash also permits limiting the aggregate bandwidth provided to users, if -you don't want to grant all of your available upload or download bandwidth. -Specific features of Nodogsplash are configurable, by editing the configuration -file and the splash page. The default installed configuration may be all you -need, though. +**Nodogspash** (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. + +**If you want to provide simple and immediate public access** to an Internet connection with users giving some acknowledgment of the service, Nodogsplash does this by default. +Customising the page seen by users is a simple matter of editing the simple default html splash page file. + +**If you want to enforce use of a set of preset usernames** and passwords with perhaps a limited connection time, the addition of a simple shell script is all that is required. + +**If you want a more sophisticated authentication system** 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. + +**Taking this to the extreme**, if you want to link Nodogsplash 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. + +All modern mobile devices, 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 'splash' web page. + +The splash page in its most basic form, contains a Continue button. When the user clicks on it, access to the internet is granted subject to a preset time interval. + +Nodogsplash does not currently support traffic control but is fully compatible with other stand alone systems such as SQM scripts. + +**Nodogsplash supports multiple means of authentication**: + +- Click the submit button (default) +- Call an external script that may accept username/password and set session durations per user. +- Forwarding authentication to an external service + ## 2. Documentation diff --git a/debian/changelog b/debian/changelog index 8d267e6..4bb03ea 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,3 +1,14 @@ +nodogsplash (3.2.0) stable; urgency=medium + + * Add Redirect to Status page support for FAS [bluewavenet] + * Add iptables version check [mwarning] + * Add ndsctl status output for FAS and Binauth status. [bluewavenet] + * Initialize fas_remoteip with gw_address and simplify code [mwarning] + * Fix Readthedocs updates and update Docs URL [bluewavenet] + * Update documentation and Debian man page [bluewavenet] + + -- Rob White Sun, 2 Sep 2018 16:09:00 +0000 + nodogsplash (3.1.0) stable; urgency=medium * Integrated support for separate Forward Authentication Service (FAS), adding the following configuration options: @@ -8,7 +19,6 @@ nodogsplash (3.1.0) stable; urgency=medium -- Rob White Sun, 26 Aug 2018 10:05:00 +0000 - nodogsplash (3.0.0-1) stable; urgency=medium * Removed settings without implementation due to the change of the http library: diff --git a/debian/copyright b/debian/copyright index 8864c5b..8cac369 100644 --- a/debian/copyright +++ b/debian/copyright @@ -3,14 +3,15 @@ Upstream-Name: nodogsplash Source: http://github.com/nodogsplash Files: * -Copyright: 2013 Moritz Warning +Copyright: 2013-18 BlueWave Projects and Services + 2013-18 Moritz Warning 2013 Shiao-An Yuan 2010 Fred Moyer 2010 Paul Kube License: GPL-2.0+ -Files: libhttpd/* -Copyright: 2001-2006, Hughes Technologies Pty Ltd, Australia +Files: libmicrohttpd/* +Copyright (C) 2007-2014 Daniel Pittman and Christian Grothoff License: GPL-2.0+ License: GPL-2.0+ diff --git a/debian/doc/nodogsplash.1 b/debian/doc/nodogsplash.1 index ebca732..6166e0a 100644 --- a/debian/doc/nodogsplash.1 +++ b/debian/doc/nodogsplash.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NODOGSPLASH" "1" "August 26, 2018" "2.0.0" "nodogsplash" +.TH "NODOGSPLASH" "1" "September 02, 2018" "3.2.0" "nodogsplash" .SH NAME nodogsplash \- nodogsplash Documentation . @@ -31,8 +31,11 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .sp -Nodogsplash offers a simple way to provide restricted access to an internet -connection. It is derived from the codebase of the Wifi Guard Dog project. +Nodogspash 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. +.sp +It was derived originally from the codebase of the Wifi Guard Dog project. +.sp Nodogsplash is released under the GNU General Public License. .INDENT 0.0 .IP \(bu 2 @@ -51,43 +54,53 @@ how to customize its behavior for your application. Contents: .SH OVERVIEW .sp -Nodogsplash (NDS) offers a solution to this problem: You want to provide controlled -and reasonably secure public access to an internet connection; and while you -want to require users to give some acknowledgment of the service you are -providing, you don\(aqt need or want the complexity of user account names and -passwords and maintaining a separate database\-backed authentication server. -When installed and running, Nodogsplash implements a simple \(aqauthentication\(aq -protocol. First, it detects any user attempting to use your internet connection -to request a web page. It captures the request, and instead serves back a -\(aqsplash\(aq web page using its own builtin web server. The splash page contains a -link which, when the user clicks on it, opens limited access for them to the -internet via your connection, beginning by being redirected to their originally -requested page. This access expires after a certain time interval. -Nodogsplash also permits limiting the aggregate bandwidth provided to users, if -you don\(aqt want to grant all of your available upload or download bandwidth. -Specific features of Nodogsplash are configurable, by editing the configuration -file and the splash page. The default installed configuration may be all you -need, though. +\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. .sp -Nodogsplash supports multiple means of authentication: +\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. +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 +\fBTaking this to the extreme\fP, if you want to link Nodogsplash 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 +All modern mobile devices, 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. +.sp +The splash page in its most basic form, contains a Continue 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 SQM scripts. +.sp +\fBNodogsplash supports multiple means of authentication\fP: .INDENT 0.0 .IP \(bu 2 -hit the submit button (default) +Click the submit button (default) .IP \(bu 2 -call an external script that may accept username/password +Call an external script that may accept username/password and set session durations per user. .IP \(bu 2 -forwarding authentication to an external service +Forwarding authentication to an external service .UNINDENT .SH INSTALLING NODOGSPLASH .SS OpenWrt .INDENT 0.0 .IP \(bu 2 -Have a router working with OpenWrt. At the time of writing, Nodogsplash has been tested with OpenWrt 18.06.0; -it may or may not work on older versions of OpenWrt or on other kinds of Linux\-based router firmware. +Have a router working with OpenWrt. At the time of writing, Nodogsplash has been tested with OpenWrt 17.01.4/5 and 18.06.0 +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +It may or may not work on older versions of OpenWrt or on other kinds of Linux\-based router firmware. +.UNINDENT +.UNINDENT +.INDENT 0.0 .IP \(bu 2 -Make sure your router is basically working before you try to install -Nodogsplash. In particular, make sure your DHCP daemon is serving addresses on the interface that nodogsplash will manage. +Make sure your router is basically working before you try to install Nodogsplash. In particular, make sure your DHCP daemon is serving addresses on the interface that nodogsplash will manage. +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 The default is br\-lan but can be changed to any interface by editing the /etc/config/nodogsplash file. +.UNINDENT +.UNINDENT +.INDENT 0.0 .IP \(bu 2 To install Nodogsplash, you may use the OpenWrt Luci web interface or alternatively, ssh to your router and run the command: .INDENT 2.0 @@ -115,15 +128,22 @@ To start Nodogsplash, run the following, or just reboot the router: .UNINDENT .UNINDENT .IP \(bu 2 -To test the installation, connect a client device to the interface on your -router that is managed by Nodogsplash (for example, connect to the router\(aqs -wireless lan). +To test the installation, connect a client device to the interface on your router that is managed by Nodogsplash (for example, connect to the router\(aqs wireless lan). +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 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. +.sp CPD will trigger Nodogsplash to serve the default splash page where you can click or tap Continue to access the Internet. .sp See the Authentication section for details of setting up a proper authentication process. .sp -If your client device does not display the splash page it most likely does not support CPD. You should then manually trigger Nodogsplash by trying to access a port 80 web site (for example, google.com:80 is a good choice). +If your client device does not display the splash page it most likely does not support CPD. +.sp +You should then manually trigger Nodogsplash by trying to access a port 80 web site (for example, google.com:80 is a good choice). +.UNINDENT +.UNINDENT +.INDENT 0.0 .IP \(bu 2 To stop Nodogsplash: .INDENT 2.0 @@ -142,6 +162,7 @@ To uninstall Nodogsplash: .SS Debian .sp There isn\(aqt a package in the repository (yet). But we have support for a debian package. +.sp Requirements beside debian tools are: .INDENT 0.0 .IP \(bu 2 @@ -258,160 +279,140 @@ v0.9 and v1 are the same codebase with the same feature set. If the documentation says something about v1, this is usally also valid for v0.9. .sp -v2 was developed while version v1 wasn\(aqt released. In v2 the http code got replaced by libmicrohttpd -as well the template engine got rewritten. Many feature were defunct because of this procedure. +v2 was developed before version v1 was released. In v2 the http code was replaced by libmicrohttpd and the template engine was rewritten. Many features became defunct because of this procedure. .sp -v3 cleans up the source code and adds the binauth feature to be able to call an external script -for authentication. This is similar to the old binvoucher feature, but more flexible. -The ClientTimeout setting was split into PreauthIdleTimeout and AuthIdleTimeout and -for the ClientForceTimeout setting SessionTimeout is now used instead. +v3 cleans up the source code and adds two major new features, +.INDENT 0.0 +.INDENT 3.5 +FAS enabling an external forwarding authentication service to be called, +.sp +and +.sp +binauth, enabling an external script to be called for simple username/password authentication as well as doing post authentication processing such as setting session durations. This is similar to the old binvoucher feature, but more flexible. +.UNINDENT +.UNINDENT +.sp +In addition, in v3, the ClientTimeout setting was split into PreauthIdleTimeout and AuthIdleTimeout and for the ClientForceTimeout setting, SessionTimeout is now used instead. .SS Can I update from v0.9 to v1 .sp -This is a very smooth update with full compatibility. +Updating to v1.0.0 and v1.0.1, this is a very smooth update with full compatibility. +.sp +Updating to 1.0.2 requires iptables v1.4.21 or above. .SS Can I update from v0.9/v1 to v2.0.0 .sp -You can, if you don\(aqt use: +You can, if: .INDENT 0.0 .IP \(bu 2 -BinVoucher +You don\(aqt use BinVoucher +.IP \(bu 2 +You have iptables v1.4.21 or above +.UNINDENT +.SS Can I update from v0.9/v1/v2 to v3.0.0 +.sp +You can, if: +.INDENT 0.0 +.IP \(bu 2 +You don\(aqt use BinVoucher +.IP \(bu 2 +You have iptables v1.4.21 or above +.IP \(bu 2 +You use the new options contained in the version 3 configuration file .UNINDENT .SS I would like to use QoS or TrafficControl on OpenWrt .sp -The original pre version 1 feature has been broken since OpenWrt 12.09 (Attitude Adjustment), because -OpenWrt removed the IMQ (Intermediate queueing device) support. We\(aqre looking for somebody who to fix this! +The original pre version 1 feature has been broken since OpenWrt 12.09 (Attitude Adjustment), because the IMQ (Intermediate queueing device) is no longer supported. +.INDENT 0.0 +.INDENT 3.5 +\fBPull Requests are welcome!\fP +.UNINDENT +.UNINDENT .sp However the OpenWrt package, SQM Scripts, is fully compatible with Nodogsplash and if configured to operate on the Nodogsplash interface (br\-lan by default) will provide efficient IP connection based traffic control to ensure fair usage of available bandwidth. -.SS Is \fI\%https://\fP redirection supported? +.SS Is https capture supported? .sp -No. We believe this is the wrong way to do it, because 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. +\fBNo\fP\&. Because all connections would have a critical certificate failure. .sp -Captive Portal Detection (CPD) 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 (depending 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. +HTTPS web sites are now more or less a standard and to maintain security and user confidence it is essential that captive portals \fBDO NOT\fP attempt to capture port 443. +.sp +\fBCaptive Portal Detection\fP (CPD) 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 (that depends upon 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. .SH HOW NODOGSPLASH (NDS) WORKS .sp -A wireless router running OpenWrt has two or more interfaces; NDS -manages one of them. This will typically be br\-lan, the bridge to both the -wireless and wired LAN; or could be for example wlan0 if you wanted NDS -to work just on the wireless interface. -.SS A simplified summary of operation is as follows: +A wireless router, typically running OpenWrt or some other Linux distribution, has two or more interfaces; NDS manages one of them. This will typically be br\-lan, the bridge to both the wireless and wired LAN; or could be for example wlan0 if you wanted NDS to work just on the wireless interface. .sp +\fBA simplified summary of operation is as follows\fP: +.INDENT 0.0 +.INDENT 3.5 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). +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 either its own splash page, or a splash page on a configured Forwarding Authentication Service (FAS). .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). +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). .sp -Once the user on the client device has sucessfully 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. +Once the user on the client device has sucessfully 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. .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. +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. -If the binauth script returns positively (ie return code 0), NDS then "authenticates" the -client device, allowing access to the Internet. +.sp +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 mode, it is the responsibility of the FAS to obtain the client token in a secure manner from NDS. .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. +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. +.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. +This can give great flexibility with FAS providing authentication and Binauth providing post authentication processing closely linked to NDS. +.UNINDENT +.UNINDENT .SS Packet filtering .sp -Nodogsplash considers four kinds of packets coming into the router over the -managed interface. Each packet is one of these kinds: +Nodogsplash considers four kinds of packets coming into the router over the managed interface. Each packet is one of these kinds: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP 1. 3 -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. +\fBBlocked\fP, 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. .IP 2. 3 -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 nodogsplash.conf configuration file, or by -the EmptyRuleSetPolicy trusted\-users EmptyRuleSetPolicy trusted\-users\-to\- -router directives. +\fBTrusted\fP, 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 nodogsplash.conf configuration file, or by the EmptyRuleSetPolicy trusted\-users EmptyRuleSetPolicy trusted\-users\-to\-router directives. .IP 3. 3 -Authenticated, if the packet\(aqs IP and MAC source addresses have gone -through the nodogsplash 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 nodogsplash.conf configuration file). +\fBAuthenticated\fP, if the packet\(aqs IP and MAC source addresses have gone through the nodogsplash 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 nodogsplash.conf configuration file). .IP 4. 3 -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 -nodogsplash.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 nodogsplash\(aqs builtin libhttpd\-based web server -is listening. This begins the \(aqauthentication\(aq 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. -.UNINDENT -.UNINDENT +\fBPreauthenticated\fP\&. 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 nodogsplash.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 nodogsplash\(aqs builtin libhttpd\-based web server is listening. This begins the \(aqauthentication\(aq 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. .UNINDENT .sp -Nodogsplash implements these actions by inserting rules in the router\(aqs -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, -nodogsplash should be insensitive to most typical existing firewall -configurations. +Nodogsplash implements these actions by inserting rules in the router\(aqs 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. +.sp +Because it inserts its rules at the beginning of existing chains, nodogsplash should be insensitive to most typical existing firewall configurations. +.UNINDENT +.UNINDENT .SS Traffic control .sp -Data rate control on an IP connection basis can be achived using SQM scripts -configured separately, with NDS being fully compatible. +Data rate control on an IP connection basis can be achived using SQM scripts 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 FORWARDING AUTHENTICATION SERVICE (FAS) .SS Overview .sp Nodogsplash (NDS) supports external (to NDS) authentication service via simple configuration options. -.sp -These options are: .INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -1. fasport. This enables Forwarding Authentication Service (FAS). -Redirection is changed from splash.html to a 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. faspath. This is the path to the login page on the FAS. - -4. fas secure enable. If set to "1", authaction and the client -token are not revealed and it is the responsibility of the FAS -to request the token from NDSCTL. If set to "0", the client -token is sent to the FAS in clear text in the query string -of the redirect along with authaction and redir. -.ft P -.fi +.TP +.B These options are: +.INDENT 7.0 +.IP 1. 3 +\fBfasport\fP\&. This enables Forwarding Authentication Service (FAS). Redirection is changed from splash.html to a FAS. The value is the IP port number of the FAS. +.IP 2. 3 +\fBfasremoteip\fP\&. If set, this is the remote ip address of the FAS, if not set it will take the value of the NDS gateway address. +.IP 3. 3 +\fBfaspath\fP\&. This is the path to the login page on the FAS. +.IP 4. 3 +\fBfas_secure_enable\fP\&. If set to "1", authaction and the client token are not revealed and it is the responsibility of the FAS to request the token from NDSCTL. If set to "0", the client token is sent to the FAS in clear text in the query string of the redirect along with authaction and redir. .UNINDENT .UNINDENT .SS Using FAS @@ -440,8 +441,12 @@ A Secure Internet based FAS is best implemented as a two stage process, first us .sp A FAS service will 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 may well 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. .sp -Running on uhttpd with PHP: +\fBRunning on uhttpd with PHP\fP: +.INDENT 0.0 +.INDENT 3.5 Install the modules php7 and php7\-cgi on LEDE for a simple example. Further modules may be required depending on your requirements. +.UNINDENT +.UNINDENT .sp To enable php in uhttpd you must add the line: .INDENT 0.0 @@ -461,7 +466,7 @@ The two important NDS options to set will be: 1. fasport. By default this will be port 80 for uhttpd 2. faspath. Set to, for example, /myfas/fas.php, -your FAS files being placed in /www/myfas/ + your FAS files being placed in /www/myfas/ .ft P .fi .UNINDENT @@ -475,20 +480,15 @@ A typical Internet hosted Apache/PHP shared server will be set up to serve multi To access yours, use: .INDENT 0.0 .INDENT 3.5 -.sp -.nf -.ft C fasremoteip = the ip address of the remote server - +.sp and, for example, - +.sp faspath = /domainname/pathto/myfas/fas.php - +.sp or - +.sp faspath = /accountname/pathto/myfas/fas.php -.ft P -.fi .UNINDENT .UNINDENT .sp @@ -610,9 +610,7 @@ After initial authentication by the script, Nodogsplash will immediately acknowl Nodogsplash will also call the script when the client is authenticated and deauthenticated in general. .SH USING NDSCTL .sp -A nodogsplash install includes ndsctl, a separate application which provides -some control over a running nodogsplash process by communicating with it over a -unix socket. Some command line options: +A nodogsplash install includes ndsctl, a separate application which provides some control over a running nodogsplash process by communicating with it over a unix socket. Some command line options: .INDENT 0.0 .IP \(bu 2 To print to stdout some information about your nodogsplash process: @@ -687,46 +685,106 @@ To set the verbosity of logged messages to n: .UNINDENT .UNINDENT .sp -For more options, run ndsctl \-h. (Note that if you want the effect of ndsctl -commands to to persist across nodogsplash restarts, you have to edit the -configuration file.) -.SH CUSTOMIZING NODOGSPLASH +For more options, run ndsctl \-h. (Note that if you want the effect of ndsctl commands to to persist across nodogsplash restarts, you have to edit the configuration file.) +.SH CUSTOMISING NODOGSPLASH .sp -The default shipped configuration is intended to be usable and reasonably -secure as\-is for basic internet sharing applications, but it is customizable. -.INDENT 0.0 -.IP \(bu 2 -To change basic nodogsplash settings, edit the configuration file: +After initial installation, Nogogsplash (NDS) should be working in its most basic mode and client Captive Portal Detection (CPD) should pop up the default splash page. .sp -\fB/etc/nodogsplash/nodogsplash.conf\fP -.UNINDENT +Before attempting to customise NDS you should ensure it is working in this basic mode before you start. .sp -In the configuration file, a FirewallRule has the form: +NDS reads its configuration file when it starts up but the location of this file varies depending on the operating system. +.sp +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 varients (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 The Configuration File +.sp +In OpenWrt, or operating systems supporting UCI (such as LEDE) the configuration is kept in the file: .INDENT 0.0 .INDENT 3.5 -\fBFirewallRule permission [protocol [port portrange] [to ip]\fP +\fB/etc/config/nodogsplash\fP .UNINDENT .UNINDENT .sp -where +In other operating systems the configuration is kept in the file: .INDENT 0.0 -.IP \(bu 2 -\fIpermission\fP is required and must be allow, block, drop, log, or ulog. -.IP \(bu 2 -\fIprotocol\fP is optional. If present, it must be tcp, udp, icmp, or all. -Defaults to all. -.IP \(bu 2 -port \fIportrange\fP is optional. If present, protocol must be tcp or udp. -portrange can be a single integer port number, or a colon\-separated port -range, e.g. 1024:1028. Defaults to all ports. -.IP \(bu 2 -\fIto ip\fP is optional. If present, ip must be a decimal dotted\-quad IP address -with optional mask. Defaults to 0.0.0.0/0, i.e. all addresses. -.IP \(bu 2 -To change the contents of the splash page, edit the splash page file: +.INDENT 3.5 +\fB/etc/nodogsplash/nodogsplash.conf\fP +.UNINDENT +.UNINDENT .sp +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. +.sp +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. +.sp +For example, to list the full configuration, at the command line type: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +uci show nodogsplash +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To display the Gateway Name, type: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +uci get nodogsplash.@nodogsplash[0].gatewayname +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To set the Gateway Name to a new value, type: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +uci set nodogsplash.@nodogsplash[0].gatewayname=\(aqmy new gateway\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To add a new firewall rule allowing access to another service running on port 8888 on the router, type: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +uci add_list nodogsplash.@nodogsplash[0].users_to_router=\(aqallow +tcp port 8888\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Finally you must tell UCI to commit your changes to the configuration file: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +uci commit nodogsplash +.ft P +.fi +.UNINDENT +.UNINDENT +.SS The Splash Page +.sp +The default simple splash page can be found at: +.INDENT 0.0 +.INDENT 3.5 \fB/etc/nodogsplash/htdocs/splash.html\fP .UNINDENT +.UNINDENT .sp When the splash page is served, the following variables in the page are replaced by their values: @@ -734,22 +792,26 @@ replaced by their values: .IP \(bu 2 \fI$gatewayname\fP The value of GatewayName as set in nodogsplash.conf. .IP \(bu 2 -\fI$authtarget\fP A URL which encodes a unique token and the URL of the user\(aqs -original web request. If nodogsplash 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. (Alternatively, you can use a GET\-method HTML form to send this -information to the nodogsplash server; see below.) As a simple example: +\fI$authtarget\fP A URL which encodes a unique token and the URL of the user\(aqs original web request. If nodogsplash 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. .sp +It should be noted however that, depending on vendor, the client\(aqs built in CPD may not respond to simple html links. +(You should instead use a GET\-method HTML form to send this information to the nodogsplash server; see below.) +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +As an example: +.INDENT 0.0 +.INDENT 3.5 \fBEnter\fP +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 .IP \(bu 2 -\fI$imagesdir\fP The directory in nodogsplash\(aqs web hierarchy where images to be -displayed in the splash page must be located. +\fI$imagesdir\fP The directory in nodogsplash\(aqs web hierarchy where images to be displayed in the splash page must be located. .IP \(bu 2 -\fI$tok\fP,*$redir*,*$authaction*, and \fI$denyaction\fP are also available and can be -useful if you want 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 nodogsplash server. As a simple example: +\fI$tok\fP, \fI$redir\fP, \fI$authaction\fP, and \fI$denyaction\fP 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 nodogsplash server. As a simple example: .UNINDENT .INDENT 0.0 .INDENT 3.5 @@ -768,59 +830,69 @@ communicate with the nodogsplash server. As a simple example: .INDENT 0.0 .IP \(bu 2 \fI$clientip\fP, \fI$clientmac\fP and \fI$gatewaymac\fP The respective addresses -of the client or gateway. This might be usefull in cases where the data -needs to be forwarded to some other place by the plash page itself. +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. .IP \(bu 2 \fI$nclients\fP and \fI$maxclients\fP User stats. Usefull when you need to display something like "n of m users online" on the splash site. .IP \(bu 2 \fI$uptime\fP The time Nodogsplash is running. -.IP \(bu 2 -A list of all available variables are included in the splash.html file. -.IP \(bu 2 -If the user accesses the splash page while being authenticated, a status page is shown: .UNINDENT .INDENT 0.0 .INDENT 3.5 +A list of all available variables are included in the splash.html file. +.sp +If the user accesses the splash page when already authenticated, a status page is shown: +.sp \fB/etc/nodogsplash/htdocs/status.html\fP -.UNINDENT -.UNINDENT .sp In the status.html file, the same variables as in the splash.html site can be used. +.UNINDENT +.UNINDENT .SH DEBUGGING NODOGSPLASH .INDENT 0.0 -.IP \(bu 2 -To see maximally verbose debugging output from nodogsplash, edit the -/etc/init.d/nodogsplash file to set the OPTIONS variable to the flags "\-s \-d 7", -restart or reboot, and view messages with logread. The \-s flag logs to -syslog; the \-d 7 flag sets level 7, LOG_DEBUG, for debugging messages -(see syslog.h). You don\(aqt want to run with these flags routinely, as it will -quickly fill the syslog circular buffer, unless you enable remote logging. A -lower level of logging, for example level 5, LOG_NOTICE, is more appropriate -for routine use (this is the default). Logging level can also be set using -ndsctl as shown above. -Alternatively, you can set the flag \-f instead of \-s, and restart. -This will run nodogsplash in the foreground, logging to stdout. -.IP \(bu 2 -When stopped, nodogsplash deletes its iptables rules, attempting to leave the -router\(aqs firewall in its original state. If not (for example, if nodogsplash -crashes instead of exiting cleanly) subsequently starting and stopping -nodogsplash should remove its rules. -.IP \(bu 2 -Nodogsplash operates by marking packets (and, if traffic control is enabled, -passing packets through intermediate queueing devices). Most QOS packages -will also mark packets and use IMQ\(aqs. Therefore one or both of Nodogsplash and -a QOS package may malfunction if used together. Potential conflicts may be -investigated by looking at your overall iptables setup. To check to see all -the rules in, for example, the mangle table chains, run -.INDENT 2.0 .INDENT 3.5 -\fBiptables \-t mangle \-v \-n \-L\fP +To see maximally verbose debugging output from nodogsplash, set log level to 7. This can be done in the UCI configuration file on OpenWrt adding the line: +.INDENT 0.0 +.INDENT 3.5 +\fBoption debuglevel \(aq7\(aq\fP .UNINDENT .UNINDENT .sp -For extensive suggestions on debugging iptables, see for example Oskar -Andreasson\(aqs_tutorial. +or by editing the file +.INDENT 0.0 +.INDENT 3.5 +\fB/etc/init.d/nodogsplash\fP +.UNINDENT +.UNINDENT +.sp +and setting the OPTIONS variable to the flags "\-s \-d 7". +.sp +Restart or reboot, and view messages with logread. Debug messages are logged to syslog. +.sp +The default level of logging is 5, LOG_NOTICE, and is more appropriate for routine use. +.sp +Logging level can also be set using ndsctl. +.sp +When stopped, nodogsplash deletes its iptables rules, attempting to leave the router\(aqs firewall in its original state. If not (for example, if nodogsplash crashes instead of exiting cleanly) subsequently starting and stopping nodogsplash should remove its rules. +.sp +On OpenWrt, restarting the firewall will overwrite Nodogsplash\(aqs iptables rules, so when the firewall is restarted it will automatically restart Nodogsplash if it is running. +.sp +Nodogsplash operates by marking packets. Many packages, such as mwan3 and SQM scripts, also mark packets. +.sp +By default, Nodogsplash marks its packets in such a way that conficts are unlikely to occur but the masks used by Nodogsplash can be changed if necessary in the configuration file. +.sp +Potential conflicts may be investigated by looking at your overall iptables setup. To list all the rules in all the chains, run +.INDENT 0.0 +.INDENT 3.5 +\fBiptables \-L\fP +.UNINDENT +.UNINDENT +.sp +For extensive suggestions on debugging iptables, see for example, Oskar Andreasson\(aqs tutorial at: +.sp +\fI\%https://www.frozentux.net/iptables\-tutorial/iptables\-tutorial.html\fP +.UNINDENT .UNINDENT .SH TODO LIST .sp @@ -840,8 +912,8 @@ genindex search .UNINDENT .SH AUTHOR -the nodogsplash contributors +The Nodogsplash Contributors .SH COPYRIGHT -2016, the nodogsplash contributors +2016 - 2018, The Nodogsplash Contributors .\" Generated by docutils manpage writer. . diff --git a/docs/source/conf.py b/docs/source/conf.py index 874e305..74256fe 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -60,9 +60,9 @@ author = 'The Nodogsplash Contributors' # built documents. # # The short X.Y version. -version = '3.1.0' +version = '3.2.0' # The full version, including alpha/beta/rc tags. -release = '3.1.0' +release = '3.2.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/source/customize.rst b/docs/source/customize.rst index 1e23616..2e958f0 100644 --- a/docs/source/customize.rst +++ b/docs/source/customize.rst @@ -1,29 +1,67 @@ -Customizing nodogsplash +Customising nodogsplash ######################## -The default shipped configuration is intended to be usable and reasonably -secure as-is for basic internet sharing applications, but it is customizable. +After initial installation, Nogogsplash (NDS) should be working in its most basic mode and client Captive Portal Detection (CPD) should pop up the default splash page. -* To change basic nodogsplash settings, edit the configuration file: +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 varients (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. + +The Configuration File +********************** + +In OpenWrt, or operating systems supporting UCI (such as LEDE) the configuration is kept in the file: + + ``/etc/config/nodogsplash`` + + +In other operating systems the configuration is kept in the file: ``/etc/nodogsplash/nodogsplash.conf`` -In the configuration file, a FirewallRule has the form: +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. - ``FirewallRule permission [protocol [port portrange] [to ip]`` +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. -where +For example, to list the full configuration, at the command line type: -* *permission* is required and must be allow, block, drop, log, or ulog. -* *protocol* is optional. If present, it must be tcp, udp, icmp, or all. - Defaults to all. -* port *portrange* is optional. If present, protocol must be tcp or udp. - portrange can be a single integer port number, or a colon-separated port - range, e.g. 1024:1028. Defaults to all ports. -* *to ip* is optional. If present, ip must be a decimal dotted-quad IP address - with optional mask. Defaults to 0.0.0.0/0, i.e. all addresses. +.. code-block:: sh -* To change the contents of the splash page, edit the splash page file: + uci show nodogsplash + +To display the Gateway Name, type: + +.. code-block:: sh + + uci get nodogsplash.@nodogsplash[0].gatewayname + +To set the Gateway Name to a new value, type: + +.. code-block:: sh + + uci set nodogsplash.@nodogsplash[0].gatewayname='my new gateway' + +To add a new firewall rule allowing access to another service running on port 8888 on the router, type: + +.. code-block:: sh + + uci add_list nodogsplash.@nodogsplash[0].users_to_router='allow + tcp port 8888' + +Finally you must tell UCI to commit your changes to the configuration file: + +.. code-block:: sh + + uci commit nodogsplash + +The Splash Page +*************** + +The default simple splash page can be found at: ``/etc/nodogsplash/htdocs/splash.html`` @@ -31,21 +69,17 @@ 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 nodogsplash.conf. -* *$authtarget* A URL which encodes a unique token and the URL of the user's - original web request. If nodogsplash 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. (Alternatively, you can use a GET-method HTML form to send this - information to the nodogsplash server; see below.) As a simple example: +* *$authtarget* A URL which encodes a unique token and the URL of the user's original web request. If nodogsplash 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. + (You should instead use a GET-method HTML form to send this information to the nodogsplash server; see below.) + + As an example: ``Enter`` -* *$imagesdir* The directory in nodogsplash's web hierarchy where images to be - displayed in the splash page must be located. -* *$tok*,*$redir*,*$authaction*, and *$denyaction* are also available and can be - useful if you want 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 nodogsplash server. As a simple example: +* *$imagesdir* The directory in nodogsplash's web hierarchy where images to be displayed in the splash page must be located. +* *$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 nodogsplash server. As a simple example: .. code:: @@ -56,18 +90,18 @@ replaced by their values: * *$clientip*, *$clientmac* and *$gatewaymac* The respective addresses - of the client or gateway. This might be usefull in cases where the data - needs to be forwarded to some other place by the plash page itself. + 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. Usefull when you need to display something like "n of m users online" on the splash site. * *$uptime* The time Nodogsplash is running. -* A list of all available variables are included in the splash.html file. + A list of all available variables are included in the splash.html file. -* If the user accesses the splash page while being authenticated, a status page is shown: + If the user accesses the splash page when already authenticated, a status page is shown: ``/etc/nodogsplash/htdocs/status.html`` -In the status.html file, the same variables as in the splash.html site can be used. + In the status.html file, the same variables as in the splash.html site can be used. diff --git a/docs/source/debug.rst b/docs/source/debug.rst index 70a3635..d4d625b 100644 --- a/docs/source/debug.rst +++ b/docs/source/debug.rst @@ -1,31 +1,36 @@ -Debugging nodogsplash +Debugging Nodogsplash ##################### -* To see maximally verbose debugging output from nodogsplash, edit the - /etc/init.d/nodogsplash file to set the OPTIONS variable to the flags "-s -d 7", - restart or reboot, and view messages with logread. The -s flag logs to - syslog; the -d 7 flag sets level 7, LOG_DEBUG, for debugging messages - (see syslog.h). You don't want to run with these flags routinely, as it will - quickly fill the syslog circular buffer, unless you enable remote logging. A - lower level of logging, for example level 5, LOG_NOTICE, is more appropriate - for routine use (this is the default). Logging level can also be set using - ndsctl as shown above. - Alternatively, you can set the flag -f instead of -s, and restart. - This will run nodogsplash in the foreground, logging to stdout. -* When stopped, nodogsplash deletes its iptables rules, attempting to leave the - router's firewall in its original state. If not (for example, if nodogsplash - crashes instead of exiting cleanly) subsequently starting and stopping - nodogsplash should remove its rules. -* Nodogsplash operates by marking packets (and, if traffic control is enabled, - passing packets through intermediate queueing devices). Most QOS packages - will also mark packets and use IMQ's. Therefore one or both of Nodogsplash and - a QOS package may malfunction if used together. Potential conflicts may be - investigated by looking at your overall iptables setup. To check to see all - the rules in, for example, the mangle table chains, run + To see maximally verbose debugging output from nodogsplash, set log level to 7. This can be done in the UCI configuration file on OpenWrt adding the line: - ``iptables -t mangle -v -n -L`` + ``option debuglevel '7'`` - For extensive suggestions on debugging iptables, see for example Oskar - Andreasson's_tutorial. + or by editing the file + + ``/etc/init.d/nodogsplash`` + + and setting the OPTIONS variable to the flags "-s -d 7". + + Restart or reboot, and view messages with logread. Debug messages are logged to syslog. + + The default level of logging is 5, LOG_NOTICE, and is more appropriate for routine use. + + Logging level can also be set using ndsctl. + + When stopped, nodogsplash deletes its iptables rules, attempting to leave the router's firewall in its original state. If not (for example, if nodogsplash crashes instead of exiting cleanly) subsequently starting and stopping nodogsplash should remove its rules. + + On OpenWrt, restarting the firewall will overwrite Nodogsplash's iptables rules, so when the firewall is restarted it will automatically restart Nodogsplash if it is running. + + Nodogsplash operates by marking packets. Many packages, such as mwan3 and SQM scripts, also mark packets. + + By default, Nodogsplash marks its packets in such a way that conficts are unlikely to occur but the masks used by Nodogsplash can be changed if necessary in the configuration file. + + 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 diff --git a/docs/source/faq.rst b/docs/source/faq.rst index f749698..04697ad 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -8,37 +8,57 @@ v0.9 and v1 are the same codebase with the same feature set. If the documentation says something about v1, this is usally also valid for v0.9. -v2 was developed while version v1 wasn't released. In v2 the http code got replaced by libmicrohttpd -as well the template engine got rewritten. Many feature were defunct because of this procedure. +v2 was developed before version v1 was released. In v2 the http code was replaced by libmicrohttpd and the template engine was rewritten. Many features became defunct because of this procedure. -v3 cleans up the source code and adds two major new features, FAS enabling an external forwarding authentication service to be called, and binauth, enabling an external script to be called for simple username/password authentication as well as doing post authentication processing such as setting session durations. This is similar to the old binvoucher feature, but more flexible. +v3 cleans up the source code and adds two major new features, -The ClientTimeout setting was split into PreauthIdleTimeout and AuthIdleTimeout and for the ClientForceTimeout setting SessionTimeout is now used instead. + FAS enabling an external forwarding authentication service to be called, + + and + + binauth, enabling an external script to be called for simple username/password authentication as well as doing post authentication processing such as setting session durations. This is similar to the old binvoucher feature, but more flexible. + +In addition, in v3, the ClientTimeout setting was split into PreauthIdleTimeout and AuthIdleTimeout and for the ClientForceTimeout setting, SessionTimeout is now used instead. Can I update from v0.9 to v1 **************************** -This is a very smooth update with full compatibility. +Updating to v1.0.0 and v1.0.1, this is a very smooth update with full compatibility. + +Updating to 1.0.2 requires iptables v1.4.21 or above. Can I update from v0.9/v1 to v2.0.0 *********************************** -You can, if you don't use: +You can, if: -* BinVoucher +* You don't use BinVoucher +* You have iptables v1.4.21 or above + + +Can I update from v0.9/v1/v2 to v3.0.0 +************************************** + +You can, if: + +* You don't use BinVoucher +* You have iptables v1.4.21 or above +* You use the new options contained in the version 3 configuration file I would like to use QoS or TrafficControl on OpenWrt **************************************************** -The original pre version 1 feature has been broken since OpenWrt 12.09 (Attitude Adjustment), because -OpenWrt removed the IMQ (Intermediate queueing device) support. We're looking for somebody who to fix this! +The original pre version 1 feature has been broken since OpenWrt 12.09 (Attitude Adjustment), because the IMQ (Intermediate queueing device) is no longer supported. + + **Pull Requests are welcome!** However the OpenWrt package, SQM Scripts, is fully compatible with Nodogsplash and if configured to operate on the Nodogsplash interface (br-lan by default) will provide efficient IP connection based traffic control to ensure fair usage of available bandwidth. -Is https:// redirection supported? -********************************** +Is https capture supported? +****************************** -No. We believe this is the wrong way to do it, because 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. +**No**. Because all connections would have a critical certificate failure. -Captive Portal Detection (CPD) 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 (depending 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. +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. + +**Captive Portal Detection** (CPD) 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 (that depends upon 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. diff --git a/docs/source/fas.rst b/docs/source/fas.rst index a675e28..34db619 100644 --- a/docs/source/fas.rst +++ b/docs/source/fas.rst @@ -6,22 +6,11 @@ Overview Nodogsplash (NDS) supports external (to NDS) authentication service via simple configuration options. -These options are:: - - 1. fasport. This enables Forwarding Authentication Service (FAS). - Redirection is changed from splash.html to a 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. faspath. This is the path to the login page on the FAS. - - 4. fas secure enable. If set to "1", authaction and the client - token are not revealed and it is the responsibility of the FAS - to request the token from NDSCTL. If set to "0", the client - token is sent to the FAS in clear text in the query string - of the redirect along with authaction and redir. +These options are: + 1. **fasport**. This enables Forwarding Authentication Service (FAS). Redirection is changed from splash.html to a 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. **faspath**. This is the path to the login page on the FAS. + 4. **fas_secure_enable**. If set to "1", authaction and the client token are not revealed and it is the responsibility of the FAS to request the token from NDSCTL. If set to "0", the client token is sent to the FAS in clear text in the query string of the redirect along with authaction and redir. Using FAS @@ -50,46 +39,84 @@ A Secure Internet based FAS is best implemented as a two stage process, first us Running FAS on your Nodogsplash router ************************************** -A FAS service will 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 may well 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 FAS service will 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 may well be an issue if more than two or three clients log in at the same time. -Running on uhttpd with PHP: -Install the modules php7 and php7-cgi on LEDE for a simple example. Further modules may be required depending on your requirements. +For this reason a device with a minimum of 8MB flash and 64MB ram is recommended. + +**Running on uhttpd with PHP**: + + Install the modules php7 and php7-cgi on OpenWrt for a simple example. Further modules may be required depending on your requirements. To enable php in uhttpd you must add the line: - list interpreter ".php=/usr/bin/php-cgi" + ``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:: +The two important NDS options to set will be: - 1. fasport. By default this will be port 80 for uhttpd + 1. fasport. By default this will be port 80 for uhttpd - 2. faspath. Set to, for example, /myfas/fas.php, + 2. faspath. Set to, for example, /myfas/fas.php, your FAS files being placed in /www/myfas/ -**Note 1**: +**Note 1**: - A typical Internet hosted Apache/PHP shared server will be set up to serve multiple domain names. + A typical Internet hosted Apache/PHP shared server will be set up to serve multiple domain names. - To access yours, use:: + To access yours, use: - fasremoteip = the ip address of the remote server + fasremoteip = the ip address of the remote server - and, for example, + and, for example, - faspath = /domainname/pathto/myfas/fas.php + faspath = /domainname/pathto/myfas/fas.php - or + or - faspath = /accountname/pathto/myfas/fas.php + faspath = /accountname/pathto/myfas/fas.php - If necessary, contact your hosting service provider. + If necessary, contact your hosting service provider. **Note 2:** - The configuration file /etc/config/nodogsplash contains the line "option enabled 1". + The configuration file /etc/config/nodogsplash contains the line "option enabled 1". - If you have done something wrong and locked yourself out, you can still SSH to your router and stop NoDogSplash (ndsctl stop) to fix the problem. + If you have done something wrong and locked yourself out, you can still SSH to your router and stop NoDogSplash (ndsctl stop) to fix the problem. +Using the simple example files +****************************** + +Assuming you want to run the FAS example demo locally under uhttpd on the same OpenWrt device that is running NDS, configured as above, do the following. + + (Under other operating systems you may need to edit the nodogsplash.conf file in /etc/nodogsplash instead, but the process is very similar.) + +First you should obtain the demo files by downloading the Nodogsplash zip file from + + https://github.com/nodogsplash/nodogsplash/ + +Then extract the php files from the folder + + ``"forward_authentication_service/nodog/"`` + +OpenWrt and uhttpd: + + * Create a folder + + ``/www/nodog/`` + + * Place the files fas.php, landing.php, css.php, querycheck.php, tos.php, users.dat in + + ``/www/nodog/`` + + * Edit + + ``/etc/config/nodogsplash`` + + adding the lines: + - option fasport '80' + - option faspath '/nodog/fas.php' + - option fas_secure_enabled '0' + + * Restart NDS using the command "service nodogsplash restart". diff --git a/docs/source/howitworks.rst b/docs/source/howitworks.rst index a25c22c..3d10b77 100644 --- a/docs/source/howitworks.rst +++ b/docs/source/howitworks.rst @@ -1,97 +1,53 @@ -How nodogsplash (NDS) works +How Nodogsplash (NDS) works ########################### -A wireless router, typically running OpenWrt or some other Linux distribution, has two or more interfaces; NDS -manages one of them. This will typically be br-lan, the bridge to both the -wireless and wired LAN; or could be for example wlan0 if you wanted NDS -to work just on the wireless interface. +A wireless router, typically running OpenWrt or some other Linux distribution, has two or more interfaces; NDS manages one of them. This will typically be br-lan, the bridge to both the wireless and wired LAN; or could be for example wlan0 if you wanted NDS to work just on the wireless interface. -A simplified summary of operation is as follows: -************************************************ +**A simplified summary of operation is as follows**: -By default, NDS blocks everything, but intercepts port 80 requests. + By default, NDS blocks everything, but intercepts port 80 requests. -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). + 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 either its own splash page, or a splash page on a configured Forwarding Authentication Service (FAS). -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). + 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). -Once the user on the client device has sucessfully 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. + Once the user on the client device has sucessfully 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. -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. + 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. -However if Binauth is enabled, NDS first calls the Binauth script, passing if required a username and password to that script. -If the binauth script returns positively (ie return code 0), NDS then "authenticates" the -client device, allowing access to the Internet. + However if Binauth is enabled, NDS first calls the Binauth script, passing if required a username and password to that script. -In FAS secure mode, it is the responsibility of the FAS to obtain the client token in a secure manner from NDS. + 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 mode, it is the responsibility of the FAS to obtain the client token in a secure manner from NDS. + + 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. .. 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. + + 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 **************** -Nodogsplash considers four kinds of packets coming into the router over the -managed interface. Each packet is one of these kinds: +Nodogsplash 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 nodogsplash.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 nodogsplash 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 nodogsplash.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 - nodogsplash.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 nodogsplash's builtin 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. + 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 nodogsplash.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 nodogsplash 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 nodogsplash.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 nodogsplash.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 nodogsplash's builtin 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. -Nodogsplash 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, -nodogsplash should be insensitive to most typical existing firewall -configurations. + + Nodogsplash 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, nodogsplash should be insensitive to most typical existing firewall configurations. Traffic control *************** -Data rate control on an IP connection basis can be achived using SQM scripts -configured separately, with NDS being fully compatible. +Data rate control on an IP connection basis can be achived using SQM scripts 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. diff --git a/docs/source/index.rst b/docs/source/index.rst index 80d57da..1457566 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,11 +3,14 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to nodogsplash's documentation! +Welcome to Nodogsplash's documentation! ======================================= -Nodogsplash offers a simple way to provide restricted access to an internet -connection. It is derived from the codebase of the Wifi Guard Dog project. +Nodogspash 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 was derived originally from the codebase of the Wifi Guard Dog project. + Nodogsplash is released under the GNU General Public License. * Mailing List: http://ml.ninux.org/mailman/listinfo/nodogsplash diff --git a/docs/source/install.rst b/docs/source/install.rst index 75765ee..a0fd9e8 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -4,38 +4,43 @@ Installing Nodogsplash OpenWrt ******* -* Have a router working with OpenWrt. At the time of writing, Nodogsplash has been tested with OpenWrt 18.06.0; - it may or may not work on older versions of OpenWrt or on other kinds of Linux-based router firmware. -* Make sure your router is basically working before you try to install - Nodogsplash. In particular, make sure your DHCP daemon is serving addresses on the interface that nodogsplash will manage. - The default is br-lan but can be changed to any interface by editing the /etc/config/nodogsplash file. +* Have a router working with OpenWrt. At the time of writing, Nodogsplash has been tested with OpenWrt 17.01.4/5 and 18.06.0 + + It may or may not work on older versions of OpenWrt or on other kinds of Linux-based router firmware. + +* Make sure your router is basically working before you try to install Nodogsplash. In particular, make sure your DHCP daemon is serving addresses on the interface that nodogsplash will manage. + + The default is br-lan but can be changed to any interface by editing the /etc/config/nodogsplash file. + * To install Nodogsplash, you may use the OpenWrt Luci web interface or alternatively, ssh to your router and run the command: ``opkg update`` - + followed by - + ``opkg install nodogsplash`` * Nodogsplash is enabled by default and will start automatically on reboot or can be started and stopped manually. - * If the interface that you want Nodogsplash to manage is not br-lan, edit /etc/config/nodogsplash and set GatewayInterface. + * To start Nodogsplash, run the following, or just reboot the router: ``/etc/init.d/nodogsplash start`` -* To test the installation, connect a client device to the interface on your - router that is managed by Nodogsplash (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 Nodogsplash 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 Nodogsplash by trying to access a port 80 web site (for example, google.com:80 is a good choice). - +* To test the installation, connect a client device to the interface on your router that is managed by Nodogsplash (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 Nodogsplash 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 Nodogsplash by trying to access a port 80 web site (for example, google.com:80 is a good choice). + * To stop Nodogsplash: ``/etc/init.d/nodogsplash stop`` @@ -48,6 +53,7 @@ Debian ****** There isn't a package in the repository (yet). But we have support for a debian package. + Requirements beside debian tools are: - libmicrohttpd-dev (>= 0.9.51) [avaiable in **stretch**] diff --git a/docs/source/ndsctl.rst b/docs/source/ndsctl.rst index 1bcc128..742235f 100644 --- a/docs/source/ndsctl.rst +++ b/docs/source/ndsctl.rst @@ -1,9 +1,7 @@ Using ndsctl ############ -A nodogsplash install includes ndsctl, a separate application which provides -some control over a running nodogsplash process by communicating with it over a -unix socket. Some command line options: +A nodogsplash install includes ndsctl, a separate application which provides some control over a running nodogsplash process by communicating with it over a unix socket. Some command line options: * To print to stdout some information about your nodogsplash process: @@ -47,7 +45,5 @@ unix socket. Some command line options: ``/usr/bin/ndsctl loglevel n`` -For more options, run ndsctl -h. (Note that if you want the effect of ndsctl -commands to to persist across nodogsplash restarts, you have to edit the -configuration file.) +For more options, run ndsctl -h. (Note that if you want the effect of ndsctl commands to to persist across nodogsplash restarts, you have to edit the configuration file.) diff --git a/docs/source/overview.rst b/docs/source/overview.rst index 3af56be..ee55337 100644 --- a/docs/source/overview.rst +++ b/docs/source/overview.rst @@ -1,26 +1,25 @@ Overview ######## -Nodogsplash (NDS) offers a solution to this problem: You want to provide controlled -and reasonably secure public access to an internet connection; and while you -want to require users to give some acknowledgment of the service you are -providing, you don't need or want the complexity of user account names and -passwords and maintaining a separate database-backed authentication server. -When installed and running, Nodogsplash implements a simple 'authentication' -protocol. First, it detects any user attempting to use your internet connection -to request a web page. It captures the request, and instead serves back a -'splash' web page using its own builtin web server. The splash page contains a -link which, when the user clicks on it, opens limited access for them to the -internet via your connection, beginning by being redirected to their originally -requested page. This access expires after a certain time interval. -Nodogsplash also permits limiting the aggregate bandwidth provided to users, if -you don't want to grant all of your available upload or download bandwidth. -Specific features of Nodogsplash are configurable, by editing the configuration -file and the splash page. The default installed configuration may be all you -need, though. +**Nodogspash** (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. -Nodogsplash supports multiple means of authentication: +**If you want to provide simple and immediate public access** to an Internet connection with users giving some acknowledgment of the service, Nodogsplash does this by default. +Customising the page seen by users is a simple matter of editing the simple default html splash page file. -- hit the submit button (default) -- call an external script that may accept username/password -- forwarding authentication to an external service +**If you want to enforce use of a set of preset usernames** and passwords with perhaps a limited connection time, the addition of a simple shell script is all that is required. + +**If you want a more sophisticated authentication system** 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. + +**Taking this to the extreme**, if you want to link Nodogsplash 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. + +All modern mobile devices, 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 'splash' web page. + +The splash page in its most basic form, contains a Continue button. When the user clicks on it, access to the internet is granted subject to a preset time interval. + +Nodogsplash does not currently support traffic control but is fully compatible with other stand alone systems such as SQM scripts. + +**Nodogsplash supports multiple means of authentication**: + +- Click the submit button (default) +- Call an external script that may accept username/password and set session durations per user. +- Forwarding authentication to an external service diff --git a/forward_authentication_service/FAS-Docs/readme b/forward_authentication_service/FAS-Docs/readme index 8533096..b823c22 100644 --- a/forward_authentication_service/FAS-Docs/readme +++ b/forward_authentication_service/FAS-Docs/readme @@ -1,36 +1,16 @@ Forwarding Authentication Service (FAS) ####################################### - -Author: Rob White - BlueWave Projects and Services -Copyright (C) 2015-2017 BlueWave Projects and Services. This software is released under the GNU GPL license. - -Nodogsplash (NDS) supports external (to NDS) authentication with with simple config options. -In addition, Binauth can be used for post authentication processing. - -Some simple example files are provided here and at the time of writing these are installed on an Internet server for demonstation purposes. - Overview ******** Nodogsplash (NDS) supports external (to NDS) authentication service via simple configuration options. -These options are:: - - 1. fasport. This enables Forwarding Authentication Service (FAS). - Redirection is changed from splash.html to a 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. faspath. This is the path to the login page on the FAS. - - 4. fas secure enable. If set to "1", authaction and the client token - are not revealed and it is the responsibility of the FAS to request - the token from NDSCTL. If set to "0", the client token is sent to - the FAS in clear text in the query string of the redirect along - with authaction and redir. +These options are: + 1. **fasport**. This enables Forwarding Authentication Service (FAS). Redirection is changed from splash.html to a 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. **faspath**. This is the path to the login page on the FAS. + 4. **fas_secure_enable**. If set to "1", authaction and the client token are not revealed and it is the responsibility of the FAS to request the token from NDSCTL. If set to "0", the client token is sent to the FAS in clear text in the query string of the redirect along with authaction and redir. Using FAS @@ -59,72 +39,84 @@ A Secure Internet based FAS is best implemented as a two stage process, first us Running FAS on your Nodogsplash router ************************************** -A FAS service will 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 may well be an issue if more than two or three clients log in at the same time with uhttpd becoming very slow. For this reason a device with a minimum of 8MB flash and 64MB ram is recommended. +A FAS service will 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 may well be an issue if more than two or three clients log in at the same time. -Running on uhttpd with PHP: -Install the modules php7 and php7-cgi on LEDE for a simple example. Further modules may be required depending on your requirements. +For this reason a device with a minimum of 8MB flash and 64MB ram is recommended. -To enable php in uhttpd you must add the line:: +**Running on uhttpd with PHP**: - list interpreter ".php=/usr/bin/php-cgi" + Install the modules php7 and php7-cgi on LEDE for a simple example. Further modules may be required depending on your requirements. + +To enable php in uhttpd you must add the line: + + ``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:: +The two important NDS options to set will be: - 1. fasport. By default this will be port 80 for uhttpd + 1. fasport. By default this will be port 80 for uhttpd - 2. faspath. Set to, for example, /myfas/fas.php, + 2. faspath. Set to, for example, /myfas/fas.php, your FAS files being placed in /www/myfas/ **Note 1**: - A typical Internet hosted Apache/PHP shared server will be set up to serve multiple domain names. + A typical Internet hosted Apache/PHP shared server will be set up to serve multiple domain names. - To access yours, use + To access yours, use: - **fasremoteip = the ip address of the remote server** + fasremoteip = the ip address of the remote server - and, for example, + and, for example, - **faspath = /domainname/pathto/myfas/fas.php** + faspath = /domainname/pathto/myfas/fas.php - or + or - **faspath = /accountname/pathto/myfas/fas.php** + faspath = /accountname/pathto/myfas/fas.php - If necessary, contact your hosting service provider. + If necessary, contact your hosting service provider. **Note 2:** - The configuration file /etc/config/nodogsplash contains the line "option enabled 1". - - If you have done something wrong and locked yourself out, you can still SSH to your router and stop NoDogSplash (ndsctl stop) to fix the problem. + The configuration file /etc/config/nodogsplash contains the line "option enabled 1". + If you have done something wrong and locked yourself out, you can still SSH to your router and stop NoDogSplash (ndsctl stop) to fix the problem. Using the simple example files ****************************** Assuming you want to run the FAS example demo locally under uhttpd on the same OpenWrt device that is running NDS, configured as above, do the following. -(Under other operating systems you may need to edit the nodogsplash.conf file in /etc/nodogsplash instead, but the process is very similar.) + (Under other operating systems you may need to edit the nodogsplash.conf file in /etc/nodogsplash instead, but the process is very similar.) -OpenWrt and uhttpd:: +First you should optain the demo files by downloading the Nodogsplash zip file from - 1. Create a folder /www/nodog/ + https://github.com/nodogsplash/nodogsplash/ - 2. Place the files fas.php, landing.php, css.php, - querycheck.php, tos.php and users.dat in /www/nodog/ +Then extract the php files from the folder - 3. Edit /etc/config/nodogsplash adding the lines:: - - option fasport '80' - - option faspath '/nodog/fas.php' - - option fas_secure_enabled '0' + ``"forward_authentication_service/nodog/"`` - 4. Restart NDS using the command "service nodogsplash restart". +OpenWrt and uhttpd: + * Create a folder + ``/www/nodog/`` + * Place the files fas.php, landing.php, css.php, querycheck.php, tos.php, users.dat in + ``/www/nodog/`` + * Edit + + ``/etc/config/nodogsplash`` + + adding the lines: + - option fasport '80' + - option faspath '/nodog/fas.php' + - option fas_secure_enabled '0' + + * Restart NDS using the command "service nodogsplash restart". diff --git a/src/conf.h b/src/conf.h index d54b81e..3f29cb9 100644 --- a/src/conf.h +++ b/src/conf.h @@ -27,7 +27,7 @@ #ifndef _CONF_H_ #define _CONF_H_ -#define VERSION "3.1.0" +#define VERSION "3.2.0" /*@{*/ /** Defines */