23/05/13

PepperSpot - OpenSource IPv4/IPv6 captive portal | Doc / UserDocumentation

Doc /

UserDocumentation

PepperSpot - The Next Generation Captive Portal

PepperSpot is a Captive Portal which allow an authenticated user to access a service network, in most case Internet. PepperSpot is destinated to be used by wireless clients. PepperSpot is a fork of the well-known captive portal ChilliSpot. The particularity of PepperSpot is that it can provide IPv6 access to Wi-Fi clients. This document describes the installation of PepperSpot and of all his dependencies.

1) System Requirement
PepperSpot has to communicate with other services which are: A web server to allow the client redirection and login page; An authentication server which support radius protocol, to proceed authentication and accounting; A routing service. Most likely, the Radius and routing service are shared on different servers, but could be installed on the same box too. Depending to the mode, the box inwhich will be installed PepperSpot needs to be configured for IPv4 or IPv6.

1.1) Kernel
PepperSpot is known to run on Linux kernel > 2.6.24.

1.2) IPv6
1.2.1) Activate IPv6
First of all, be sure that IPv6 is activated on your kernel. If IPv6 is compiled as a module, type:
#m o d p r o b ei p v 6

1.2.2) Stateless autoconfiguration

It is recommended to use stateless autoconfiguration for IPv6 clients. Radvd is able to advertise Router Advertisement with Prefix and DNS informations (RDNSS option). Install it on the computer that host the captive portal, either with distribution package: On Debian,
#a p t g e ti n s t a l lr a d v d

or download source from http://www.litech.org/radvd/ This is an example of the /etc/radvd.conf configuration file:
i n t e r f a c ea t h 0 { A d v S e n d A d v e r to n ; A d v I n t e r v a l O p to n ; M i n R t r A d v I n t e r v a l2 ; M a x R t r A d v I n t e r v a l6 ; p r e f i x2 0 0 1 : d b 8 : 1 : : / 6 4 { A d v O n L i n ko n ; A d v A u t o n o m o u so n ; A d v R o u t e r A d d ro n ; } ; R D N S S2 0 0 1 : d b 8 : 2 : : 1 { A d v R D N S S P r e f e r e n c e8 ; A d v R D N S S O p e no f f ; A d v R D N S S L i f e t i m e3 0 ; } ; } ;

Replace interface , prefix and RDNSS (DNS server information) lines with your own values, and launch radvd with:
#r a d v dC/ e t c / r a d v d . c o n f

1.2.3) Addressing and Routing

A captive portal have to route packets of an authenticated user towards Internet. So the system must have IPv6 forwarding enabled. You can turn it on with:
#e c h o" 1 ">/ p r o c / s y s / n e t / i p v 6 / c o n f / a l l / f o r w a r d i n g

pepperspot.sourceforge.net/index.php?n=Doc.UserDocumentation

To keep this configuration persistent, you can uncomment the following line in /etc/sysctl.conf file:

1/7

23/05/13

PepperSpot - OpenSource IPv4/IPv6 captive portal | Doc / UserDocumentation

To keep this configuration persistent, you can uncomment the following line in /etc/sysctl.conf file:
n e t . i p v 6 . c o n f . a l l . f o r w a r d i n g = 1

IPv6 forwarding will disable the IPv6 autoconfiguration, so network configuration (assign addresses and routes) can be set statically or dynamically with routing daemons. For the last ones procedure look at section 2. If you want to use the static addressing and routing procedure, assuming that eth0 is the interface connected to the IPv6 network to Internet, type the following command and replace with your own value. Assign address on wired interface:
#i p6a d d ra d d2 0 0 1 : d b 8 : 1 : : 1 2 3 4 / 6 4d e ve t h 0

Add the default route configuration (replace with you route address value):
#r o u t eAi n e t 6a d dd e f a u l tg wf e 8 0 : : 1 : 2 : 3 : 4d e ve t h 0

You can turn this configuration persistent insert the network configuration in your /etc/network/intefaces file this way:
a u t oe t h 0 i f a c ee t h 0i n e t 6s t a t i c a d d r e s s2 0 0 1 : d b 8 : 1 : : 1 2 3 4 n e t m a s k6 4 g a t e w a yf e 8 0 : : 1 : 2 : 3 : 4 p r e u pm o d p r o b ei p v 6 #t ob es u r et h a ti p v 6i se n a b l e db e f o r ew et u r nu pt h ei n t e r f a c e

Note that you do not have to configure address on interface connected to the Access Point box (or the wireless interface if you use ones).

1.3) IPv4
The IPv4 configuration is more or less the same than IPv6, except that you don't need the advertise the client for network configuration. PepperSpot integrates a DHCP module to attribute an IPv4 address to remote clients. You can disable this module in the PepperSpot configuration if the wireless link already have a DHCP server, or if clients configuration is set statically. You need nevertheless to configure the interface linked to the IPv4 network. In the same way, enable the IPv4 forwarding by:
#e c h o" 1 ">/ p r o c / s y s / n e t / i p v 4 / c o n f / a l l / f o r w a r d i n g

or set the following line in /etc/sysctl.conf:

n e t . i p v 4 . i p _ f o r w a r d = 1

Configure the interface address and route (Replace with your parameters):
#i pa d d ra d d1 9 2 . 1 6 8 . 0 . 1 / 2 4d e ve t h 1 #r o u t ea d dd e f a u l tg w1 9 2 . 1 6 8 . 0 . 2 5 4d e ve t h 1

You can put that in your /etc/network/interfaces file:

a u t oe t h 1 i f a c ee t h 1i n e ts t a t i c a d d r e s s1 9 2 . 1 6 8 . 0 . 1 n e t m a s k2 4 g a t e w a y1 9 2 . 1 6 8 . 0 . 2 5 4

1.4) Netfilter Support

PepperSpot will use some Netfilter's rules to proceed the communication between the client and Internet. So the system must support Netfilter. If it's not the case, modify the configuration of your kernel: For IPv4, you need to enable the Nat, Mangle and tracking support; For IPv6, you only need the basic support. Install iptables, either with distribution package: On debian,
#a p t g e ti n s t a l li p t a b l e s

or download the last version on http://www.netfilter.org/

1.5) Other required package

You need the libc6 developpement package in order to compile PepperSpot, Install it either with distribution package: On Debian,
#a p t g e ti n s t a l ll i b c 6 d e v

or download it on http://www.gnu.org/software/libc/

1.6) Notes
pepperspot.sourceforge.net/index.php?n=Doc.UserDocumentation
All services (Radius, web server, PepperSpot, ...) can be installed on systems which provide Wi-Fi access (Master mode). It can be an embedded device, or a system from

2/7

23/05/13

PepperSpot - OpenSource IPv4/IPv6 captive portal | Doc / UserDocumentation

All services (Radius, web server, PepperSpot, ...) can be installed on systems which provide Wi-Fi access (Master mode). It can be an embedded device, or a system from scratch configured as an Access Point. For this case, your Wi-Fi card must support the Master mode. For example if you use wireless interface with madwifi driver, here is an initialisation script:
# ! / b i n / b a s h #S e t t i n ga t h 0i nM a s t e rm o d e #R e p l a c eP e p p e r S p o tb yy o u rS S I D w l a n c o n f i ga t h 0d e s t r o y w l a n c o n f i ga t h 0c r e a t ew l a n d e vw i f i 0w l a n m o d ea p i w c o n f i ga t h 0e s s i d" P e p p e r S p o t " i f c o n f i ga t h 0u p

2) Install and configure Quagga routing suite

The Quagga routing suite implements some IPv4 and IPv6 routing protocols. This section describes the installation of the RIPng protocol to allow IPv6 routing. We assume that you have a delegated IPv6 prefix, and that you need to route the communication for this prefix. If it's not the case, you can skip this section. You firstly need to install Quagga package: On debian:
#a p t g e ti n s t a l lq u a g g a

You can also download the tarball at http://www.quagga.net/ The configuration of quagga is done by setting up some configuration files in the /etc/quagga directory, but the quagga suite integrates some cisco-like interfaces for each protocol to allow configuration on the fly and to view some routing information like routing table. Note that you can put IPv6 and IPv4 network configurations described before, in the routing protocol configuration. For each protocol you want, enable it in /etc/quagga/daemon. We need to enable zebra, because it's the main routing module needed to use other protocol and configure interfaces. In our case, we only need to add RIPng too:
#T h i sf i l et e l l st h eq u a g g ap a c k a g ew h i c hd a e m o n st os t a r t . # #E n t r i e sa r ei nt h ef o r m a t :< d a e m o n > = ( y e s | n o | p r i o r i t y ) # 0 ," n o " =d i s a b l e d # 1 ," y e s "=h i g h e s tp r i o r i t y # 2. .1 0 =l o w e rp r i o r i t i e s #R e a d/ u s r / s h a r e / d o c / q u a g g a / R E A D M E . D e b i a nf o rd e t a i l s . # #S a m p l ec o n f i g u r a t i o n sf o rt h e s ed a e m o n sc a nb ef o u n di n #/ u s r / s h a r e / d o c / q u a g g a / e x a m p l e s / . # #A T T E N T I O N : # #W h e na c t i v a t i o nad a e m o na tt h ef i r s tt i m e ,ac o n f i gf i l e ,e v e ni fi ti s #e m p t y ,h a st ob ep r e s e n t* a n d *b eo w n e db yt h eu s e ra n dg r o u p" q u a g g a " ,e l s e #t h ed a e m o nw i l ln o tb es t a r t e db y/ e t c / i n i t . d / q u a g g a .T h ep e r m i s s i o n ss h o u l d #b eu = r w , g = r , o = . #W h e nu s i n g" v t y s h "s u c hac o n f i gf i l ei sa l s on e e d e d .I ts h o u l db eo w n e db y #g r o u p" q u a g g a v t y "a n ds e tt ou g = r w , o =t h o u g h .C h e c k/ e t c / p a m . d / q u a g g a ,t o o . # z e b r a = y e s b g p d = n o o s p f d = n o o s p f 6 d = n o r i p d = n o r i p n g d = y e s i s i s d = n o

Now we have to create one configuration file for each daemon launched. /etc/quagga/zebra.conf file:
! !Z e b r ac o n f i g u r a t i o ns a v e df r o mv t y ! 2 0 0 8 / 0 4 / 1 01 2 : 1 8 : 5 8 ! h o s t n a m eM o b S p o t p a s s w o r d* * * * * * * * * * * e n a b l ep a s s w o r d* * * * * * * * * * * * * ! i n t e r f a c ea t h 0 i p v 6n ds u p p r e s s r a ! i n t e r f a c ee t h 0 i p v 6a d d r e s s2 0 0 1 : d b 8 : 1 : : 1 2 3 4 / 6 4 i p v 6n ds u p p r e s s r a ! i n t e r f a c ee t h 1 i pa d d r e s s1 9 2 . 1 6 8 . 0 . 1 / 2 4 i p v 6n ds u p p r e s s r a ! i n t e r f a c ee t h 2 i p v 6n ds u p p r e s s r a ! i n t e r f a c ee t h 3 i p v 6n ds u p p r e s s r a ! i n t e r f a c el o ! i n t e r f a c et u n 0

pepperspot.sourceforge.net/index.php?n=Doc.UserDocumentation

3/7

23/05/13
i n t e r f a c et u n 0 i p v 6n ds u p p r e s s r a ! i n t e r f a c ew i f i 0 i p v 6n ds u p p r e s s r a ! i p v 6f o r w a r d i n g ! ! l i n ev t y !

PepperSpot - OpenSource IPv4/IPv6 captive portal | Doc / UserDocumentation

In this file, we set up the static configuration of each interface linked to the service network (eth0 and eth1). /etc/quagga/ripngd.conf file:
!* -r i p* ! !R I P n g ds a m p l ec o n f i g u r a t i o nf i l e ! !$ I d :r i p n g d . c o n f . s a m p l e , v1 . 1 . 1 . 12 0 0 2 / 1 2 / 1 32 0 : 1 5 : 3 0p a u lE x p$ ! h o s t n a m eM o b S p o t p a s s w o r d* * * * * * * * * * * e n a b l ep a s s w o r d* * * * * * * * * * * * ! !d e b u gr i p n ge v e n t s !d e b u gr i p n gp a c k e t ! ! r o u t e rr i p n g n e t w o r ke t h 0 r e d i s t r i b u t ec o n n e c t e d r e d i s t r i b u t es t a t i c r o u t e2 0 0 1 : d b 8 : 1 : : / 6 4 ! l i n ev t y !

In this file, we configure the RIPng protocol, indicating that we are able to route packet for 2001:db8:1::/64 prefix on the eth0 interface. For the both files, the first section will define the password for the configuration interfaces (vty). The enable password line indicate that a password is required to get the right to reconfigure the daemon. Don't forget the line vty line to enable this configuration interface. For zebra configuration type:
#t e l n e t1 2 7 . 0 . 0 . 1z e b r a

For RIPng configuration:

#t e l n e t1 2 7 . 0 . 0 . 1r i p n g d

Note: After authentication (with the password line renseigned into configuration file), you will obtain a command line to configure the daemon. Type "?" to see available commands. To finish, restart quagga daemons:
#/ e t c / i n i t . d / q u a g g ar e s t a r t

Note: If you need to configure IPv4 routing, adapt this configuration to RIP daemon.

3) Apache configuration
PepperSpot needs to communicate with a Web Server installed on the same machine to allow clients to proceed authentication. The web server have to be configured for SSL, PHP and CGI. Here is the configuration for Apache2 web server: On debian, install it with:
#a p t g e ti n s t a l la p a c h e 2l i b a p a c h e 2 m o d p h p 5l i b s s l d e v

Generate a SSL certificate to guarantee the identity of the web server:

#m a k e s s l c e r t/ u s r / s h a r e / s s l c e r t / s s l e a y . c n f/ e t c / a p a c h e 2 / k e y . p e m

The second step is to load the Apache2-SSL module:

#a 2 e n m o ds s l

The web server need a virtual host to be reachable. Create the file /etc/apache2/sites-available/pepperspot with the following contents (Adapt to your needed configuration):
N a m e V i r t u a l H o s t* : 4 4 3 < V i r t u a l H o s t* : 4 4 3 > S e r v e r A d m i nw e b m a s t e r @ p e p p e r s p o t S S L E n g i n eo n S S L C e r t i f i c a t e F i l e/ e t c / a p a c h e 2 / k e y . p e m D o c u m e n t R o o t/ v a r / w w w / < D i r e c t o r y/ > O p t i o n sF o l l o w S y m L i n k s

pepperspot.sourceforge.net/index.php?n=Doc.UserDocumentation

4/7

23/05/13

PepperSpot - OpenSource IPv4/IPv6 captive portal | Doc / UserDocumentation

A l l o w O v e r r i d eN o n e < / D i r e c t o r y > < D i r e c t o r y/ v a r / w w w / > O p t i o n sI n d e x e sF o l l o w S y m L i n k sM u l t i V i e w s A l l o w O v e r r i d eN o n e O r d e ra l l o w , d e n y a l l o wf r o ma l l #T h i sd i r e c t i v ea l l o w su st oh a v ea p a c h e 2 ' sd e f a u l ts t a r tp a g e #i n/ a p a c h e 2 d e f a u l t / ,b u ts t i l lh a v e/g ot ot h er i g h tp l a c e R e d i r e c t M a t c h^ / $/ a p a c h e 2 d e f a u l t / < / D i r e c t o r y >

#C G I-W en e e dc g is u p p o r tt oc o m m u n i c a t ew i t hP e p p e r S p o t S c r i p t A l i a s/ c g i b i n // u s r / l i b / c g i b i n / < D i r e c t o r y" / u s r / l i b / c g i b i n " > A l l o w O v e r r i d eN o n e O p t i o n s+ E x e c C G IM u l t i V i e w s+ S y m L i n k s I f O w n e r M a t c h O r d e ra l l o w , d e n y A l l o wf r o ma l l < / D i r e c t o r y > < / V i r t u a l H o s t >

If you want to modify the name of the virtual host, don't forget that Apache needs to listen on both IPv6 and IPv4 address for dual stack mode, and on IPv4 or IPv6 interface regarding to the single mode you will choice. Add in /etc/apache2/ports.conf to allow HTTPS listening (if not already present):
< I f M o d u l em o d _ s s l . c > L i s t e n4 4 3 < / I f M o d u l e >

Finally, load the site:

#a 2 e n s i t ep e p p e r s p o t #/ e t c / i n i t . d / a p a c h e 2r e l o a d

4) FreeRadius Configuration
PepperSpot is able to communicate with a Radius Server over IPv4 or IPv6 protocol, regarding to the radius server address configuration in /etc/pepper.conf. Here is the configuration of FreeRadius Server. To have IPv6 support, you need a version of FreeRadius >= 2.0. But if you only want to use IPv4 support, you can install an older version. To download FreeRadius: http://www.freeradius.org/ The FreeRadius configuration is complex, and the following describes only an elementary configuration to enable IPv6 support on FreeRadius, and an easy way to add some user accounts. If you want a better configuration, see the FreeRadius documentation.

4.1) IPv6 configuration

Modify the /etc/freeradius/radiusd.conf file to add the followings section:
#F o ra u t h e n t i c a t i o n l i s t e n{ t y p e=a u t h # i p a d d r=* i p v 6 a d d r=: : 1 p o r t=0 # i n t e r f a c e=e t h 0 # c l i e n t s=p e r _ s o c k e t _ c l i e n t s } #F o ra c c o u n t i n g l i s t e n{ t y p e=a c c t # i p a d d r=* i p v 6 a d d r=: : 1 p o r t=0 # i n t e r f a c e=e t h 0 # c l i e n t s=p e r _ s o c k e t _ c l i e n t s }

With this configuration, replace ::1 for the field ipv6addr by the address in which FreeRadius must listen. port = 0 means that default Radius ports are used. If you specify * for ipv6addr, FreeRadius will listen on each IPv6 address configured on the system. Now, you need to configure a FreeRadius client (called as NAS), typically the NAS is the captive portal. Open the /etc/freeradius/clients.conf file and add the following lines:
c l i e n t: : 1{ #h e r e: : 1i st h en a m eo ft h ec l i e n t .R e p l a c ew i t hy o u ro w nv a l u e i p v 6 a d d r =: : 1 s e c r e t =t e s t i n g 1 2 3 s h o r t n a m e =l o c a l h o s t n a s t y p e =o t h e r }

If PepperSpot and FreeRadius are on different box, ipv6addr must be replace by the address with which PepperSpot and FreeRadius communicate. Modify the shortname too. Restart FreeRadius:
#/ e t c / i n i t . d / f r e e r a d i u sr e s t a r t

pepperspot.sourceforge.net/index.php?n=Doc.UserDocumentation

5/7

23/05/13

PepperSpot - OpenSource IPv4/IPv6 captive portal | Doc / UserDocumentation

4.2) IPv4 configuration

For IPv4 configuration of FreeRadius, replace the ipv6addr field with ipaddr, and fill it with the IPv4 address wanted.

4.3) Accounts
Finally, we need to create accounts in /etc/freeradius/users:
t o t o p i n g 6 C l e a r t e x t P a s s w o r d: =" t o t o i l s a i t p a s " C l e a r t e x t P a s s w o r d: =" p o n g 6 "

Restart FreeRadius:
#/ e t c / i n i t . d / f r e e r a d i u sr e s t a r t

5) PepperSpot installation and configuration

5.1) Compilation and installation
Untar the PepperSpot source and compile it:
#t a rx j v fP e p p e r S p o t 1 . 0 . t a r . b z 2 #c dP e p p e r S p o t 1 . 0 / #. / c o n f i g u r e #m a k e #m a k ei n s t a l l

OR check the SVN source:

#s v nc oh t t p s : / / p e p p e r s p o t . s v n . s o u r c e f o r g e . n e t / s v n r o o t / p e p p e r s p o tp e p p e r s p o t #c dp e p p e r s p o t #a u t o r e c o n fi #. / c o n f i g u r e #m a k e #m a k ei n s t a l l

Note for Mac OS X users: Mac OS X has old /usr/include files, so to compile PepperSpot on this system, edit src/Makefile.am and add -D_DARWIN_C_SOURCE to the AM_CFLAGS instead off D_POSIX_C_SOURCE=200112L -D_XOPEN_SOURCE=600. You should have a line like this:

A M _ C F L A G S=D _ D A R W I N _ C _ S O U R C Ef n o b u i l t i nD S B I N D I R = ' " $ ( s b i n d i r ) " 'W a l lW e x t r ap e d a n t i cs t d = c 9 9W s t r i c t p r o t o t y p e sW r e d u n d a n t d e c l s

Copy some configuration files:

#c pd o c / p e p p e r . c o n f/ e t c / #c pd o c / h o t s p o t l o g i n . c g i/ u s r / l i b / c g i b i n / #c h m o d+ x/ u s r / l i b / c g i b i n / h o t s p o t l o g i n . c g i

For IPv4:
#c pd o c / p e p p e r . i p t a b l e s/ e t c / #c h m o d+ x/ e t c / p e p p e r . i p t a b l e s

For IPv6:
#c pd o c / p e p p e r . i p 6 t a b l e s/ e t c / #c h m o d+ x/ e t c / p e p p e r . i p 6 t a b l e s

5.2) iptables
Modify the /etc/pepper.iptables and/or /etc/pepper.ip6tables scripts and adapt $INTIF (interface connected to the access point or the wireless interface), $EXTIF4 (interface connected to the IPv4 LAN) and $EXTIF6 (interface connected to the IPv6 LAN) values regarding to your configuration. Note that for dual stack configuration $EXTIF4 and $EXTIF6 could have the same value.

5.3) Configuration
Depending to the mode, you must configure parameters in /etc/pepper.conf file. Change ipversion value to chose the mode, you can choose one of the followings: dual ipv4 ipv6 If you choose dual for ipversion, look at the both following sections.

5.3.1) IPv6
- Modify staticipv6 (the IPv6 address of the tun6 interface created by PepperSpot):
s t a t i c i p v 62 0 0 1 : d b 8 : 1 : : 1 2 3 4

- Modify uamserver6 (don't forget the brackets):

pepperspot.sourceforge.net/index.php?n=Doc.UserDocumentation

6/7

23/05/13

PepperSpot - OpenSource IPv4/IPv6 captive portal | Doc / UserDocumentation

u a m s e r v e r 6h t t p s : / / [ 2 0 0 1 : d b 8 : 1 : : 1 2 3 4 ] / c g i b i n / h o t s p o t l o g i n . c g i

The IPv6 address of the url must be the same as staticipv6 (brackets are mandatory when using IPv6 address) - Modify prefix :
p r e f i x2 0 0 1 : d b 8 : 1 : : / 6 4

Note: it have to be the prefix of staticipv6

5.3.2) IPv4
- Modify net (IPv4 network):
n e t1 9 2 . 1 6 8 . 0 . 1 / 2 4

- Modify uamserver:
u a m s e r v e rh t t p s : / / 1 9 2 . 1 6 8 . 0 . 1 / c g i b i n / h o t s p o t l o g i n . c g i

Note: the IPv4 address have to be the first address of the network.

5.4) Radius
The configuration file will indicate to pepperspot if the communication with the radius server is done over IPv4 or IPv6. If you chose an IPv6 for radiuslisten field, radiusserver1 and radiusserver2 must be IPv6 address. It's the same things if you choose an IPv4 address, fill radiusserver1 and radiusserver2 fileds with IPv4 adress. Configure the radius server as required. Exemple, for IPv6 communication between PepperSpot and FreeRadius, installed on a same system:
[ . . . ] r a d i u s l i s t e n: : 1 [ . . . ] r a d i u s s e r v e r 1: : 1 [ . . . ] r a d i u s s e r v e r 2: : 1 [ . . . ] r a d i u s s e c r e tt e s t i n g 1 2 3

radiussecret must have the same value than secret of the client section in the /etc/raddb/clients.conf file. By the same way, modify uamsecret with the value you want:
u a m s e c r e tt e s t i n g 2 3 4

and update $uamsecret in /usr/lib/cgi-bin/hotspotlogin.cgi with the same value. Others parameters of the /etc/pepper.conf file are describes on the man, for example radiusnasip, ...
#m a np e p p e r

6) Running PepperSpot
Before running PepperSpot, you have to be sure that all others services needed by PepperSpot are available and the box is configured. Execute iptables script(s) regarding to the running mode of PepperSpot. If you use PepperSpot with IPv4 support:
#/ e t c / p e p p e r . i p t a b l e s

If you use PepperSpot with IPv6 support:

#/ e t c / p e p p e r / i p 6 t a b l e s

You can now run PepperSpot, In debug mode:

#p e p p e rf d

In release mode:
#p e p p e r

Enjoy now with this powerful dual stack captive portal ;).
Page last modified on November 22, 2012, at 05:46 PM

pepperspot.sourceforge.net/index.php?n=Doc.UserDocumentation

7/7