NoCatSplash

From DD-WRT Wiki

Revision as of 07:19, 24 June 2008 by S2s2 (Talk | contribs)
Jump to: navigation, search

Contents

NOTICE from 2007 10 23 to Present

NoCatSplash does not work in v2.4 'Final', and several prior Release Candidates. There is an existing bugtracker entry at: 2764
Please, when NoCat does not work for you (e.g. everyone), put an entry in the link above. Do not open a new bugtracker entry. Sorry about dragging my feet getting this posted into the wiki. I guess I overlooked it! Please read the Introduction first if you are new to NoCat. The Work-Around starts after.

Introduction

NoCatSplash is a special type of web server. It redirects clients connecting to a DD-WRT box to a specific web page. Usually used for disclaimers and advertising, it can be a very useful tool when you have unknown people connecting wirelessly. After a configurable period of time, the client's internet access is cut off, unless the Client has agreed again to the Terms. If the client has a Web Browser open & configured with a Direct Internet Connection, and loads a website, their browser is redirected again, to the NoCatSplash page.

The DD-WRT Device must have an active Internet connection working in order to use NoCat. For instance, a client trying to ping an Internet address, like www.google.com, must be able to get an IP returned for Google, although the Ping packets will not go through until the Client clicks the I Agree button on the splash page.

Terms

NoCatSplash 
Herein referred to as NoCat or splashd (the technical name).
Client 
referrers to the roaming laptop user with a browser configured for direct internet connections. LAN clients are normally included, so anyone wired into the LAN ports on the DD-WRT box is also a Client. LAN Servers, for instance, can be excluded from being involved in the NoCat system within the configuration of NoCat.
Terms 
referrers to the Terms of Use, or Agreement, which protects the DD-WRT owner from legal liability for the use of the open internet connection. For more information on how an Agreement contract can effectively block a legal conviction for state-blocked internet use, please consult legal advice in your own jurisdiction. This Wiki article only describes how to make the agreement appear, and under what circumstances it might not appear (Limitations). In any case, failure of NoCat to force Clients to see an agreement page, or the failure of the Splash page content to protect the DD-WRT box operator from legal attacks, does not make the authors of NoCat, or this Wiki, or DD-WRT, liable.
CLI 
Command Line Interface. Either SSH (more secure, recommended) or Telnet (less or not secure). Windows users use Putty, a free download, as your SSH Client.
NoKaid 
A build of DD-WRT with no specific XBOX support. Leaves room for a tiny read/write folder, storing custom nocat scripts and web pages.
Gateway Name 
The name of the gateway. Whatever you want to call it. "Joe's Pizza Shop and free DSL Cafe" for example. Use the variable $GatewayName in your splash.html page to display this.
AllowedWebHosts 
Space separated list of websites [hostnames] accessible without requiring I Agree to be clicked (without requiring NoCat Login).
List any webservers, that you would like connecting clients to be able to access, before clicking on I Agree on the NoCatSplash screen. I.E. the webserver hosting your EULA or Welcome Page, if it isn't the router itself.
Document Root 
Web pages for Splashd are stored here. Default configuration is /www.
Splash URL 
Optional URL to fetch dynamic remote splash page from.
Leave empty if using a page stored on the router.
ExcludePorts 
Space-separated list of ports clients cannot use (i.e. port 25, commonly blocked by ISP's).
Users blocked by NoCat cannot send through the ports specified, period.
You should *always* exclude port 25 (SMTP), unless you want to run a portal for wanton spam sending. Normal user web-mail and users using TLS or SSL (both use non-25 port designations) for their Thunderbird or other Mail Programs are not affected by this. Only users using unencrypted, unauthenticated outgoing mail are blocked. Obviously, such activity is a good idea to discourage anyway.
MAC White List 
Add a space separated list of MAC-addresses that should have unlimited Internet Access. The MAC addresses listed in this field will not be redirected to the Splash-page but have internet-access straight away.
Login Timeout 

How much time, in seconds, elapses before the client has to see the splash screen again, and click on 'I Agree'. How often a client is shown the EULA or other designated splash page.
For Open Mode portals, you probably want to set LoginTimeout to something large (like 86400, for one notification per day). Open Mode, is the only mode supported at this time.

Verbosity 
Log verbosity (to syslogd)
    • 0 is (almost) no logging.
    • 10 is log everything.
    • 5 is probably a safe middle road.
Route only 
Required only if you DO NOT want your gateway to act as a NAT.

Enable this only if you're running a strictly routed network, and don't need the gateway to enable NAT for you.
You would not normally use this option. So if you don't understand it, leave it to No/Off.

Work-Around

If you need NoCat working (otherwise, why would be here?), v24RC1 at minimum works, but there are some bugs: such as not waiting long enough to start on WAN connections, and crashing after a couple of hours. The work-arounds for all of these to get a 'stable' NoCatSplash for a production environment of 10-20 users is included.

Requirements:

  • Your custom website needs to be hosted through the local filesystem, /jffs, to work [1]. This is only a limitation of the compile-time flags given to NoCat on DD-WRT.
  • JFFS must be enabled, with native space on the device's local main flash, or by adding a mount --bind /somewhere /jffs command in Startup Commands - supplemental flash card, USB stick, or NAS.
  • CRON must be enabled (usually is enabled for other things anyway)

After enabling and configuring NoCatSplash in the Web Interface, make a copy of your nocat.conf in /tmp/etc to /jffs/etc - from the CLI:

 mkdir /jffs/etc
 cp /tmp/etc/nocat.conf /jffs/etc
 less /jffs/etc

Create 'restart_splashd.sh', and save it in your /jffs/ folder. It contains:

#!/bin/sh
/usr/bin/killall -q splashd
/bin/sleep 1
# the sleep command may not be necessary
cp /jffs/etc/nocat.conf /tmp/etc/nocat.conf
/usr/sbin/splashd >> /tmp/nocat.log &

From /jffs, type 'chmod 777 restart_splashd.sh' to make the script executable.

Create 'start_splashd.sh' in /jffs:

#!/bin/sh
sleep 110
# use sleep 110 for PPPoE connections. The default in the DD-WRT-generated nocat.conf does not seem long enough. Probably less time, like sleep 20, works better with DHCP (e.g. Cable modem)
splashd >> /tmp/nocat.log &

From /jffs, type 'chmod 777 start_splashd.sh' to make 'start_splashd.sh' executable.

Disable NoCatSplash in the Web Interface. Go to Administration, Commands, and Edit the Startup Commands. Add:

/jffs/start_splashd.sh &
  • This means you are going to start splashd with the script above instead of having the DD-WRT firmware start it. I find this helps with devices which, due to their upstream provider, take a long time to bring up their WAN interface. Especially true with PPPoE (DSL) connections.

Enable CRON in the Web Interface, and add:

15 * * * * root /jffs/restart_splashd.sh &

The command above restarts 'splashd' every hour, at the 15 minute mark, and does not appear to interfere with existing connections (tested in a production environment).

If you are running a stable version of DD-WRT with a stable version of NoCatSplash, the above instructions also work. Beginners with a stable version of DD-WRT can use the instructions below.

Procedure

DD-WRT firmware comes complete with sample splash and status pages. Setting up basic NoCat through the Web Interface is easy. More complex options are possible by editing the nocat.conf file directly. NoCat can use a Splash URL hosted outside of the DD-WRT box, such as on NAS. Or NoCat can use the JFFS2 filesystem services on the router. A straight-forward setup is modifying the sample splash page (highly suggested) and storing it directly on the DD-WRT Device.

Enable NoCatSplash in the DD-WRT Web Interface.
- v23: Administration, Hotspot
- v24: Services, Hotspot

  • Enter your Homepage (the page people will be redirected to, after seeing the splash page),
  • Add your Allowed Web Hosts (NoCat automatically includes the Splash URL domain). Only put the domain name in, this means, do not prefix the name with http://.
  • For starters, leave the Document Root as /www.
  • Enter your Splash URL (ex: http://yoursite.com/splash/).
    • When using Document Root, Splash URL is ignored. Splash URL must be filled in with a website, otherwise Splashd does not work!

Leave all of the other settings alone. Apply your changes, and test it out.

Customize the Splash Website

Overview: Copy the default splash pages from the read-only area /www to a writeable area on the DD-WRT Device. Then the basic Splash pages can be improved to add your logo or other necessary disclaimers, agreement terms, and customizations.

Steps:

  1. See the Wiki Article Enabling JFFS2 or Adding additional Flash memory to DD-WRT to create the space on the router which is writable.
  2. Using the CLI, create a folder named nocat
    mkdir /jffs/nocat
  3. Check if the folder exists
    cd /jffs/nocat
  4. Copy the default content from /www to /jffs/nocat
    cp -R /www/* /jffs/nocat/*
  5. Next edit the /jffs/nocat/splash.html web page.
    See WinSCP and Mirroring
  6. Change the NoCatSplash configuration using the DD-WRT Web Interface from /www to /jffs/nocat. Apply. Restart DD-WRT Device if necessary.

Configuration Screen Photos

v23 NoCatSplash Configuration Web Interface

Image:V23-hotspot-nocatsplash-conf.png

Advanced Notes

  • If splash.html calls another page, such as when using HTML Frames, the final page's form for the 'I Accept' button must have action="http://the DD-WRT enabled box's IP:5280/" instead of action="$action", and any other variables filled out with the values in the Web Interface/nocat.conf. The variables present in the original splash.html sample do not pass to sub-pages.
  • Your Splash page won't show anything linked outside of the html file if the Splash URL isn't hosted on the router or through a Samba mount. For example .css and images won't load, but style tags in the HEAD of your html page will.
  • A few things I found while looking for documentation on the net: In the nocat.conf file (you'll have to be using a nocat.conf stored in /jffs/etc and use the CLI to edit these)
    GatewayMode Open 
    The only supported option at this time. I don't think it has to be set.
    LocalNetwork 192.168.1.0/24 
    The IP Range which will see the splash page.
    InsideIP 192.168.1.1 
    The LAN/wLAN IP of the router. I don't think it needs to be set
    DNSAddr 4.2.2.4 
    Your DNS Server. Again, I don't think this needs to be set here.

Daemon:
/usr/sbin/splashd

Default Configuration file:
/etc # cat nocat.conf

nvram entries:

NC_Verbosity=0
NC_SplashURL=http://www.mydomain.com/
NC_DocumentRoot=/jffs/nocat
NC_RouteOnly=0
NC_HomePage=http://www.mydomain.com/
NC_GatewayName=DDWRT
NC_ExcludePorts=25 21 23
NC_enable=1
NC_LoginTimeout=86400
NC_AllowedWebHosts=mydomain.com

History

While Authentication was originally envisioned for NoCat (NoCatAuth), support has been removed to make this as streamlined as possible.

References

http://cvs.sourceforge.net/viewcvs.py/nocatsplash/nocatsplash/man/nocat.conf.5?rev=1.1.1.1&view=markup
http://www.aixmarseille.com/NoCatSplash

Remarks

Please:

  • The place for Questions and Conjecture is on the Article Discussion page, or post your Questions in the DD-WRT Forum.

PolskiKrol Comments: It would appear that that nokaid version of DD-WRT v24 RC7 no longer leaves any space for JFFS2 on 4MB Firmware. This issue was seen on the WRT150N. The last working firmware [for me, with enough space,] is DD-WRT v24 RC6.2.