openNDS/resources/opennds.conf

#
# openNDS Configuration File
#
# The "#" character at the beginning of a line indicates that the whole line is a comment.
#
# "#" characters within a line are assumed to be part of the configured option
#

# GatewayName
# Default: openNDS
#
# gatewayname is used as an identifier for the instance of openNDS
#
# It is displayed on the default static splash page and the default preauth login script.
#
# It is particularly useful in the case of a single remote FAS server that serves multiple
# openNDS sites, allowing the FAS to customise its response for each site.
#
# Note: The single quote (or apostrophe) character ('), cannot be used in the gatewayname.
# If it is required, use the htmlentity ' instead.
#
# For example:
# GatewayName Bill's WiFi is invalid.
# Instead use:
# GatewayName Bill's WiFi
#
# GatewayName openNDS
###########################################################################################

# Option: GatewayInterface
# Default: NONE
#
# GatewayInterface is not autodetected, has no default, and must be set here.
# Set GatewayInterface to the interface on your router
# that is to be managed by openNDS.
# The selected interface must be allocated an IPv4 address.
# Typically br-lan for the wired and wireless lan combined in a bridge.
#
GatewayInterface br-lan
###########################################################################################

# Login Option
# Default: 0
# Integer value sent to PreAuth script as login mode
#
# opennds comes preconfigured for two basic modes of operation
#
# 1.Default Dynamic Click to Continue
# The pre-installed dynamic login page is enabled by setting option login_option_enabled = “0”.
# This is the default assuming allow_legacy_splash = ‘0’, the default value.
# It generates a Click to Continue page followed by a info/advertising page.
# User clicks on “Continue” are recorded in the log file /[tmpfs_dir]/ndslog/ndslog.log
#
# 2.Username/Emailaddress Dynamic Login
# The pre-installed dynamic login page is enabled by setting option login_option_enabled = “1”.
# It generates a login page asking for username and email address followed by a info/advertising page.
# User logins are recorded in the log file /[tmpfs_dir]/ndslog/ndslog.log
#
login_option_enabled 0
###########################################################################################

# Define Custom Parameters
# Custom parameters are sent as fixed values to FAS
# Default None
#
# Custom Parameters listed in the form of param_name=param_value
# param_name and param_value must be htmlentity encoded if containing white space or single quotes
#
#fas_custom_parameters_list <param_name1=param_value1> <param_name2=param_value2> [.....] <param_nameN=param_valueN>
#
# Example:
#fas_custom_parameters_list location=main_building admin_email=norman@bates-motel.com> 
###########################################################################################

# Use outdated libmicrohttpd (MHD)
# Older versions of MHD convert & and + characters to spaces when present in form data
# This can make a PreAuth or BinAuth impossible to use for a client if form data contains either of these characters
# eg. in username or password
# MHD versions earlier than 0.9.71 are detected.
# If this option is set to 0 (default), NDS will terminate if MHD is earlier than 0.9.71
# If this option is set to 1, NDS will attempt to start and log an error.
use_outdated_mhd 0
###########################################################################################

# MHD Unescape callback
# MHD has a built in unescape function that urldecodes incoming queries from browsers
# This option allows an external unescape script to be enabled
# The script must be named unescape.sh, be present in /usr/lib/openNDS/ and be executable.
# A standard unescape.sh script is installed by default
# Set to 1 to enable this option, 0 to disable
# default is disabled
#
unescape_callback_enabled 0
###########################################################################################

# Allow use of legacy html splash page
# Default 0
# If set to 0 use of legacy html splash page is not allowed
# If set to 1 the legacy html splash page is allowed if FAS is not configured
# allow_legacy_splash 0
###########################################################################################

# Option: WebRoot
# Default: /etc/openNDS/htdocs
#
# The local path where the splash page content resides.
###########################################################################################

# FirewallRuleSet: authenticated-users
#
# Control access for users after authentication.
# These rules are inserted at the beginning of the
# FORWARD chain of the router's filter table, and
# apply to packets that have come in to the router
# over the GatewayInterface from MAC addresses that
# have authenticated with openNDS, and that are
# destined to be routed through the router.  The rules are
# considered in order, and the first rule that matches
# a packet applies to it.
# If there are any rules in this ruleset, an authenticated
# packet that does not match any rule is rejected.
# N.B.: This ruleset is completely independent of
# the preauthenticated-users ruleset.
#
FirewallRuleSet authenticated-users {

# You may want to open access to a machine on a local
# subnet that is otherwise blocked.  If so,
# allow that explicitly here, e.g:
#  FirewallRule allow tcp port 80 to 192.168.254.254

# Your router may have several interfaces, and you
# probably want to keep them private from the GatewayInterface.
# If so, you should block the entire subnets on those interfaces, e.g.:
#  FirewallRule block to 192.168.0.0/16
#  FirewallRule block to 10.0.0.0/8

# Typical ports you will probably want to open up include
# 53 udp and tcp for DNS,
# 80 for http,
# 443 for https,
# 22 for ssh:
#  FirewallRule allow tcp port 53	
#  FirewallRule allow udp port 53	
#  FirewallRule allow tcp port 80
#  FirewallRule allow tcp port 443
#  FirewallRule allow tcp port 22
# Or for happy customers allow all
  FirewallRule allow all
# You might use ipset to easily allow/block range of ips, e.g.: 
# FirewallRule allow ipset WHITELISTED_IPS
# FirewallRule allow tcp port 80 ipset WHITELISTED_IPS
}
###########################################################################################

# Walled Garden
# Allow preauthenticated users to access external services
# This is commonly referred to as a Walled Garden.

FirewallRuleSet preauthenticated-users {

# For preauthenticated users to resolve IP addresses in their
# initial request not using the router itself as a DNS server.
# Leave commented to help prevent DNS tunnelling
#  FirewallRule allow tcp port 53	
#  FirewallRule allow udp port 53
#
# For splash page content not hosted on the router, you
# will want to allow tcp to the remote host here.
#
# Note that the remote host's numerical IP address must be known
# and used here.  
#  FirewallRule allow tcp port 80 to 123.121.123.121

#
# A Walled Garden can be configured either:
# 1. Manually for known ip addresses
# or
# 2. Autonomously from a list of FQDNs and ports

#####
# Manual Walled Garden configuration requires research to determine the ip addresses of the Walled Garden site(s)
# This can be problematic as sites can use many dynamic ip addresses.
# However, manual configuration does not require any additional dependencies (ie additional installed packages)
#
# Manual configuration example:
#
#FirewallRule allow tcp port 80 to 112.122.123.124
#FirewallRule allow udp port 8020 to 112.122.123.124
#
#
# This is the end of "FirewallRuleSet preauthenticated-users" section so we need a closing "}"
#
}


#####
# Autonomous Walled Garden configuration using a list of FQDNs and Ports.
#
# This has the advantage of discovering all ip addresses used by the Walled Garden sites.
# But it does require the ipset and dnsmasq-full packages to be installed.
# Check your Linux distribution for details on how to install these.
#
#
# Configuration of the Walled Garden is then a simple matter of adding two lists as follows:
# 
# walledgarden_fqdn_list fqdn1 fqdn2 fqdn3 .... fqdnN
# walledgarden_port_list port1 port2 port3 .... portN
#
# Note: If walledgarden_port_list is NOT specified, then Walled Garden access is granted
# for both tcp and udp protocols on ALL ports for each fqdn specified in walledgarden_fqdn_list.
#
# Note: If walledgarden_port_list IS specified, then:
#  1. Specified port numbers apply to ALL FQDN's specified in walledgarden_fqdn_list.
#  2. Only tcp protocol Walled Garden access is granted.
#
# Autonomous configuration examples
#
# 1. To add Facebook to the Walled Garden, the list entries would be:
# walledgarden_fqdn_list facebook.com fbcdn.net
# walledgarden_port_list 443 80
#
# 2. To add Paypal to the Walled Garden, the list entries would be:
# walledgarden_fqdn_list paypal.com paypalobjects.com'
# walledgarden_port_list 443

###########################################################################################

# FirewallRuleSet: users-to-router
#
# Control access to the router itself from the GatewayInterface.
# These rules are inserted at the beginning of the
# INPUT chain of the router's filter table, and
# apply to packets that have come in to the router
# over the GatewayInterface from MAC addresses that
# are not on the TrustedMACList, and are destined for
# the router itself.  The rules are
# considered in order, and the first rule that matches
# a packet applies to it. 
# If there are any rules in this ruleset, a
# packet that does not match any rule is rejected.
#
FirewallRuleSet users-to-router {
 # openNDS automatically allows tcp to GatewayPort,
 # at GatewayAddress, to serve the splash page.
 # However you may want to open up other ports, e.g.
 # 53 for DNS and 67 for DHCP if the router itself is
 # providing these services.
    FirewallRule allow udp port 53	
    FirewallRule allow tcp port 53	
    FirewallRule allow udp port 67
 # You may want to allow ssh, http, and https to the router
 # for administration from the GatewayInterface.  If not,
 # comment these out.
   FirewallRule allow tcp port 22
   FirewallRule allow tcp port 80
   FirewallRule allow tcp port 443
}
###########################################################################################

# EmptyRuleSetPolicy directives
# The FirewallRuleSets that openNDS permits are:
#
# authenticated-users
# preauthenticated-users
# users-to-router
# trusted-users
# trusted-users-to-router
#
# For each of these, an EmptyRuleSetPolicy can be specified.
# An EmptyRuleSet policy applies to a FirewallRuleSet if the
# FirewallRuleSet is missing from this configuration file,
# or if it exists but contains no FirewallRules.
#
# The possible values of an EmptyRuleSetPolicy are:
# allow  -- packets are accepted
# block  -- packets are rejected
# passthrough -- packets are passed through to pre-existing firewall rules
#
# Default EmptyRuleSetPolicies are set as follows:
# EmptyRuleSetPolicy authenticated-users passthrough
# EmptyRuleSetPolicy preauthenticated-users block
# EmptyRuleSetPolicy users-to-router block
# EmptyRuleSetPolicy trusted-users allow
# EmptyRuleSetPolicy trusted-users-to-router allow
###########################################################################################

# Option: GatewayAddress
#
# Deprecated
#
# Default: Discovered from GatewayInterface
#
# It need not and probably should not be specified.
# If set here, it must be set to the IP address of the router on
# the GatewayInterface.
#
# Setting may result in failure of openNDS to start automatically at boot time
# Setting incorrectly will result in failure of openNDS.
#
###########################################################################################

# Option: StatusPage
# Default: status.html
#
# The page the client is show if the client is already authenticated but navigates to the captive portal.
#
# StatusPage status.html
###########################################################################################

# Option: splashpage
# Default: /etc/opennds/splash.html
#
# The html page used for templated splash page generation (if FAS/PreAuth is not enabled)
#
# splash.html displays a simplistic click to continue button.
#
# splash_sitewide.html displays a client login page asking for username and password.
#
# The BinAuth script binauth_sitewide.sh must be enabled for splash_sitewide to verify the
# entered credentials from the userlist.dat database file.
# The following two lines enable splash_sitewide templated authentication:
# splashpage splash_sitewide.html'
# binauth /usr/lib/opennds/binauth_sitewide.sh
###########################################################################################


# Option: RedirectURL
# Default: Deprecated
#
# NOTE: RedirectURL has been removed from version 7.0.0 onwards.
#	As most CPD implementations immediately close the "splash" page
#	as soon as NDS authenticates, RedirectURL would not be shown.
#
#	This functionality, ie displaying a particular web page as a final "Landing Page"
#	is reliably achieved using FAS.
#
###########################################################################################


# Option: GatewayPort
# Default: 2050
#
# openNDS's own http server uses GatewayAddress as its IP address.
# The port it listens to at that IP can be set here; default is 2050.
#
# GatewayPort 2050
###########################################################################################

# Option: MaxClients
# Default: 20
#
# Set MaxClients to the maximum number of users allowed to 
# connect at any time.  (Does not include users on the TrustedMACList,
# who do not authenticate.)
#
  MaxClients 250
###########################################################################################

# Option: SessionTimeout
# Default: 0
#
# Set the default session length in minutes. A value of 0 is for
# sessions without an end.
# SessionTimeout 1200
###########################################################################################

# Option: PreAuthIdleTimeout
# Default: 10
#
# Set PreAuthIdleTimeout to the desired number of minutes before
# an pre-authenticated user is automatically removed from the client list.
# PreAuthIdleTimeout 20
###########################################################################################

# Option: AuthIdleTimeout
# Default: 120
#
# Set AuthIdleTimeout to the desired number of minutes before
# an authenticated user is automatically 'deauthenticated'
# and removed from the client list.
# AuthIdleTimeout 90
###########################################################################################

# Option: CheckInterval
# Default: 30
#
# Interval in seconds, the status of all clients is checked.
# CheckInterval 60
###########################################################################################

# Option: MACMechanism
# Default: block
#
# Either block or allow.
# If 'block', MAC addresses on BlockedMACList are blocked from
# authenticating, and all others are allowed.
# If 'allow', MAC addresses on AllowedMACList are allowed to
# authenticate, and all other (non-trusted) MAC's are blocked.
#
# MACMechanism block
###########################################################################################

# Option: BlockedMACList
# Default: none
#
# Comma-separated list of MAC addresses who will be completely blocked
# from the GatewayInterface. Ignored if MACMechanism is allow.
# N.B.: weak security, since MAC addresses are easy to spoof.
#
# BlockedMACList 00:00:DE:AD:BE:EF,00:00:C0:1D:F0:0D
###########################################################################################

# Option: AllowedMACList
# Default: none
#
# Comma-separated list of MAC addresses who will not be completely
# blocked from the GatewayInterface. Ignored if MACMechanism is block.
# N.B.: weak security, since MAC addresses are easy to spoof.
#
# AllowedMACList 00:00:12:34:56:78
###########################################################################################

# Option: TrustedMACList
# Default: none
#
# Comma-separated list of MAC addresses who are not subject to
# authentication, and are not restricted by any FirewallRuleSet.
# N.B.: weak security, since MAC addresses are easy to spoof.
#
# TrustedMACList 00:00:CA:FE:BA:BE, 00:00:C0:01:D0:0D
###########################################################################################

# Quotas and Rates
# Note: upload means to the Internet, download means from the Internet
# Defaults 0
# Integer values only
#
# If the client average data rate exceeds the value set here, the client will be forced out
# Values are in kb/s
# If set to 0, there is no limit
#
# Quotas and rates can also be set by FAS via Authmon Daemon, by BinAuth, and by ndsctl auth.
# Values set by these methods, will be override values set in this config file.
#
uploadrate 0
downloadrate 0
###########################################################################################

# The client data rate is calculated using a moving average.
# This allows clients to burst at maximum possible rate, only blocking if the moving average
# exceeds the specified upload or download rate.
# The moving average window size is equal to ratecheckwindow times checkinterval (seconds)
# Default 2
ratecheckwindow 2
###########################################################################################

# If the client data quota exceeds the value set here, the client will be forced out
# Values are in kB
# If set to 0, there is no limit
#
uploadquota 0
downloadquota 0
###########################################################################################

# Option: GatewayIPRange
# Default: 0.0.0.0/0
#
# By setting this parameter, you can specify a range of IP addresses
# on the GatewayInterface that will be responded to and managed by
# openNDS.  Addresses outside this range do not have their packets
# touched by openNDS at all.
# Defaults to 0.0.0.0/0, that is, all addresses.
#
# GatewayIPRange 0.0.0.0/0
###########################################################################################

# Option: DebugLevel
# Default: 1
# 0 : Silent (only LOG_ERR and LOG_EMERG messages will be seen, otherwise there will be no logging.)
# 1 : LOG_ERR, LOG_EMERG, LOG_WARNING and LOG_NOTICE (this is the default level).
# 2 : debuglevel 1 + LOG_INFO
# 3 : debuglevel 2 + LOG_DEBUG
# DebugLevel 1
###########################################################################################

# Option: fasport
# Default: None
#
# Enable Forwarding Authentication Service (FAS)
# If set redirection is changed from splash.html to a FAS (provided by the system administrator)
# The value is the IP port number of the FAS
# Note: if FAS is running locally (ie fasremoteip is NOT set), port 80 cannot be used
#
# Typical remote Hosted Example:
# fasport 80
#
# Typical Locally Hosted Example:
# fasport 2080
###########################################################################################

# Option: fasremotefqdn
# Default: Not set
# If set, this is the remote fully qualified domain name (FQDN) of the FAS.
# The protocol must NOT be prepended to the FQDN (ie http:// or https://)
# To prevent CPD or browser security errors NDS prepends http:// before redirection.
# If set, DNS MUST resolve fasremotefqdn to be the same ip address as fasremoteip.
# Typical Remote Shared Hosting Example:
# fasremotefqdn onboard-wifi.net
###########################################################################################

# Option: fasremoteip
# Default: GatewayAddress (the IP of NDS)
#
# If set, this is the remote ip address of the FAS.
#
# Typical Locally Hosted example (ie fasremoteip not set):
# fasremoteip 46.32.240.41
###########################################################################################

# Option: faspath
# Default: /
#
# This is the path from the FAS Web Root to the FAS login page
# (not the file system root).
#
# Typical Shared Hosting example:
# faspath '/onboard-wifi.net/nodog/fas.php'
#
# Typical Locally Hosted example (ie fasremoteip not set):
# faspath /nodog/fas.php
###########################################################################################

# Option: faskey
# Default: not set
# A key phrase for NDS to encrypt the query string sent to FAS
# Can be any combination of A-Z, a-z and 0-9, up to 32 characters with no white space
#option faskey 1234567890

# Option: fas_secure_enabled
# Default: 1

# ****If set to "0"****
# The FAS is enforced by NDS to use http protocol.
# The client token is sent to the FAS in clear text in the query string of the redirect along with authaction and redir.

# ****If set to "1"****
# The FAS is enforced by NDS to use http protocol.
# When the sha256sum command is available AND faskey is set, the client token will be hashed and sent to the FAS,
# identified as "hid" in the query string.
# The gatewayaddress is also sent on the query string, allowing the FAS to construct the authaction parameter.
# FAS must return the sha256sum of the concatenation of the original hid and faskey to be used by NDS for client authentication.
# This is returned in the normal way in the query string identified as “tok”.
# NDS will automatically detect whether hid mode is active or the raw token is being returned.
#
# Should sha256sum not be available or faskey is not set, then it is the responsibility of the FAS to request the token from NDSCTL.

# ****If set to "2"****
# The FAS is enforced by NDS to use http protocol.
#
# The parameters clientip, clientmac, gatewayname, client token, gatewayaddress, authdir, originurl and clientif
# are encrypted using faskey and passed to FAS in the query string.
#
# The query string will also contain a randomly generated initialization vector to be used by the FAS for decryption.
#
# The cipher used is "AES-256-CBC".
#
# The "php-cli" package and the "php-openssl" module must both be installed for fas_secure level 2 and 3.
#
# openNDS does not depend on this package and module, but will exit gracefully
# if this package and module are not installed when this level is set.
#
# The FAS must use the query string passed initialisation vector and the pre shared fas_key to decrypt the query string.
# An example FAS level 2 php script (fas-aes.php) is included in the /etc/opennds directory and also supplied in the source code.

# ****If set to "3"****
# The FAS is enforced by NDS to use https protocol.
#
# Level 3 is the same as level 2 except the use of https protocol is enforced for FAS.
#
# In addition, the "authmon" daemon is loaded.
# This allows the external FAS, after client verification, to effectively traverse inbound firewalls and address translation
# to achieve NDS authentication without generating browser security warnings or errors.
# An example FAS level 3 php script (fas-aes-https.php) is included in the /etc/opennds directory and also supplied in the source code.
#
# Note: Option faskey must be set if fas secure is set to levels 2 and 3 but is optional for level 1.
#fas_secure_enabled '0'
###########################################################################################

# PreAuth
# PreAuth support allows FAS to call a local program or script with html served by the built in NDS web server
# If the option is set, it points to a program/script that is called by the NDS FAS handler
# All other FAS settings will be overidden.
# Initially FAS appends its query string to faspath.
# The Preauth program will output html code that will be served to the client by NDS
# Using html GET the Preauth program may call:
# /openNDS_preauth/ to ask the client for more information
# or
# /openNDS_auth/ to authenticate the client
#
# The Preauth program should append at least the client ip to the query string
# (using html input type hidden) for all calls to /opennds_preauth/
# It must also obtain the client token (using ndsctl), for NDS authentication when calling /opennds_auth/
#
#preauth /path/to/myscript/myscript.sh
###########################################################################################

# Enable BinAuth Support.
# Default disabled
#
# If set, a BinAuth program or script is triggered by several possible methods
# and is called with several arguments on both authentication and deauthentication:
#
# $<BinAuth> <method> <arg1> <arg2> .... <argN>
#
# The Binauth script will issue an exit code:
# 0 Authentication allowed
# 1 Authentication denied
#
# Possible methods
#
# Authentication:
# "auth_client": Request for authentication received from the captive portal splash page.
# "client_auth": Acknowledgement that Client was authenticated via this script.
# "ndsctl_auth": Client was authenticated by ndsctl auth command.
#
# Deauthentication:
# "client_deauth": Client deauthenticated by the client via captive portal splash page.
# "idle_deauth": Client was deauthenticated because of inactivity.
# "timeout_deauth": Client was deauthenticated because the session timed out.
# "ndsctl_deauth": Client was deauthenticated by ndsctl deauth command.
# "uprate_deauth": Client was deauthenticated because its average upload rate exceeded the allowed value
# "downrate_deauth": Client was deauthenticated because its average download rate exceeded the allowed value
# "upquota_deauth": Client was deauthenticated because its upload quota exceeded the allowed value
# "downquota_deauth": Client was deauthenticated because its download quota exceeded the allowed value
# "shutdown_deauth": Client was deauthenticated by openNDS terminating.
#
# A fully functional BinAuth script is pre-installed and provides local logging
# of client activity if enabled by uncommenting the following line:
#binauth /usr/lib/opennds/binauth_log.sh
###########################################################################################

# openNDS uses specific HEXADECIMAL values to mark packets used by iptables as a bitwise mask.
# This mask can conflict with the requirements of other packages such as mwan3, sqm etc
# Any values set here are interpreted as in hex format.
#
# Option: fw_mark_authenticated
# Default: 30000 (0011|0000|0000|0000|0000 binary)
#
# Option: fw_mark_trusted
# Default: 20000 (0010|0000|0000|0000|0000 binary)
#
# Option: fw_mark_blocked
# Default: 10000 (0001|0000|0000|0000|0000 binary)
###########################################################################################