Managing HotSpot Clients With FreeRadius

Dashamir Hoxha <dashohoxha@gmail.com>

Copyright (C) 2008 Dashamir Hoxha. Permission is granted to copy, distrib te and!or modi"y this doc ment nder the terms o" the #$% &ree Doc mentation 'icense, (ersion ).) or any *ater +ersion p b*ished by the &ree ,o"t-are &o ndation. -ith no /n+ariant ,ections, -ith no &ront0Co+er 1exts, and -ith no 2ac30Co+er 1exts. 4 copy o" the *icense is inc* ded in the section entit*ed 5#$% &ree Doc mentation 'icense.5

Abstract: This paper describes how to set up a HotSpot service, using FreeRadius for AAA. Client accounts in radius are managed with HotSpot Manager. Mi roTi , ChilliSpot, CoovaChilli and CoovaA! can be used as hotspot servers "access points#.

1. HotSpot Manager
$.$. %ntroduction
HotSpot Manager is a web application that can be used to manage the users of a networ of HotSpot access points. The HotSpot access points are &in S's (RT)*+& wireless routers, with CoovaA! firmware "which provides HotSpot service via coova,chilli#. The authentication of the internet users "clients# is done in a radius server "freeRadius#. The application supports more than one domain "networ #. -ach domain can have one or more .ASes "access points / wireless routers / HotSpot nodes#. The number of access points for each domain is not limited. -ach domain can have one or more managers that are created b' the administrator "superuser# of the application. The manager of a domain can create, modif' and delete the internet users of the domain. The internet user of a domain can get hotspot access to internet through each of the domain access points ".ASes#, but cannot login through the access points of the other domains. The domain manager assigns a certain internet service to the user, which defines the bandwidth of the user, the e0piration time of the service, etc. The services are created and defined b' the application administrator, which also ma es available some of the services to each domain. +rouping and managing access points and internet users into domains can be useful for hierarchical management of the networ . For e0ample an organi1ation "or office, or business# can manage itself the connection to internet of its own staff. The application also allows to limit the number of access points and clients of each domain. Also each domain can have its own customi1ed login page.

$.2. Features
Features that are currentl implemented: Support for multiple domains. -ach domain can have an' number of .ASes. -ach domain can have its own customi1ed login page. Support for several services.

 An admin can have one or more domains and one domain can have one or more admins. Actions of the users can be audited easil'. 3ptional integration with Radius Manager. Features that ma be implemented in the !uture: More fle0ible t'pes of services "including traffic limits, online time, etc.# Automatic chec for the limits of the clients and automatic interruption of the service in case that the limits are reached. Automatic notification to the clients and admins when the internet usage approaches the limits. 4sage statistics about clients, domains etc. Clients should be able to see their status and statistics. +oogle map with the locations of the .ASes "HotSpot,s#. 3nline registration of the clients and the possibilit' to pa' b' credit card, pa'pal etc. Authentication of the users/clients b' digital certificates "instead of username/password#. Scratch card generation5 !a'ment recording and billing functions5

$.6. Radius Manager

The application is also integrated with Radius Manager, which is an application for managing the database of freeRadius, services, clients, etc. "it has even some simple billing functionalit'#. 4nfortunatel', Radius Manager is not free software "open source#. So, the integration with Radius Manager is optional and HotSpot Manager can also wor standalone "it does not depend on it#. The benefits of integrating with Radius Manager are these7 For each client "internet user# 'ou can see in Radius Manager some usage statistics7 is it online or not, histor' of connection/disconnection times, the download/upload traffic that it has done each time, etc. Radius Manager has some cron 8obs that chec periodicall' e0piration times of the clients, approaching download/upload limits etc. %t can also send notification emails to the clients, disconnect them automaticall', etc. The same radius can be used for other services as well, e.g. !!!o-, using Mi roTi as a .AS, etc. The scratch card generator, billing functions etc. of Radius Manager can be useful as well. However, HotSpot Manager may support some of these functions in the future releases...

$.*. %nstallation
9ownload it from http7//sourceforge.net/pro8ects/netaccess/files/hsmanager/:.)/hsmanager, :.).tar.g1/download, and e0tract it7
bash6 tar x"7 hsmanager00.8.tar.g7 bash6 m+ hsmanager00.8 hsmanager

Alternativel', get the code of the application from subversion at SourceForge7

bash6 cd !+ar!---! bash6 s+n co https9!!netaccess.s+n.so rce"orge.net!s+nroot!netaccess!: hotspot0manager!tr n3 hsmanager bash6 cd hsmanager! bash6 s+n co https9!!php-ebapp.s+n.so rce"orge.net!s+nroot!php-ebapp!-eb;app!tr n3 : -eb;app

Then, modif' hsmanager.c"g accordingl' and run sudo ."install.sh . The parameters in hsmanager.c"g are these7 Connecting to the database of the application7
<<< parameters "or connecting <<< to the database o" the app*ication appdb;host=*oca*host appdb;name=hsmanager appdb;admin ser=root appdb;adminpass= appdb; ser=hsmng appdb;pass=hsmngpass appdb;a**o-ed;hosts=>*oca*host>

The adminuser user should be able to create databases and users and to grant permissions to them. The user is the database user that is used b' the application to access the database. The parameter allowed_hosts contains the host"s# where the application is installed "relative to the database host; for e0ample it can be <$=2.$>?.$::.@<. Connecting to the database of radius7
<<< parameters "or connecting <<< to the database o" radi s raddb;host=*oca*host raddb;name=radi s raddb;admin ser=root raddb;adminpass= raddb;api ser=hsmng) raddb;apipass=hsmngpass raddb;a**o-ed;hosts=>*oca*host>

The adminuser user should be able to create databases and users and to grant permissions to them. The user is the database user that is used b' the application to access the database. The parameter

allowed_hosts contains the host"s# where the application is installed "relative to the database host; for e0ample it can be <$=2.$>?.$::.@<.

#ote: The database where the data of the application are stored is different from the
database of radius, this is wh' there are two different sets of configurations.

$mportant: %f appdbAhost is the same as raddbAhost "both databases are located in

the same server#, then appdbAuser and raddbAapiuser should be different. 3therwise there will problems, because the application uses persistent connections, and the php persistent connections are the same when both host and user "and password# are the same. !arameters about radius7
<<< radi s con"ig ration rad;pre"ix=! sr!*oca* integrate;-ith;rm=tr e

The parameter rad_prefix can be empt', ! sr!*oca* , etc. The parameter integrate_with_rm can be true or false . %f 'ou have not alread' installed Radius Manager , then ma e if false .
<<< radi s tab*es <nas=nas <radacct=radacct <radchec3=radchec3 <radgro pchec3=radgro <radgro prep*y=radgro <radippoo*=radippoo* <radposta th=radposta <radrep*y=radrep*y <rad sergro p= sergro

pchec3 prep*y th p

These are not functional 'et. !arameters about the HotSpot configuration of the .ASes7
<<< hotspot con"ig ration hs;con"ig;dir=! sr!*oca*!hotspot!con"ig hs;radi s;ser+er)=)?2.)@8.28.)) hs;radi s;ser+er2=)?2.)@8.28.))

The parameter hs_config_dir is the director' where the CoovaChilli configuration parameters are saved "for each domain#.

$.). Administration
First login as superuser. Superuser has access to all the modules of the application. Then go to the module of Services and create some. Right now, onl' upload and download rates are saved in the radius database; the other features are not wor ing 'et.

 .e0t, go the module of Domains and create some domains. Here, it is possible to select which services will be available to the clients of the domain "at least one service should be selected#. The number of .ASes and the number of clients of the domain can be limited as well "if the' are 1ero, then there is no limitation#.

Then, go to the module of Users and create some users of the application. These are the users that are permitted to access the application, not the internet users "the internet users are called clients#. For each user set proper access rights7 which modules and which domains he can access. A t'pical domain administrator has access onl' to one domain "his own domain#, and to the modules7 .ASes, Clients and &ogs. A user can administrate more than one domain "add them in separate lines#, and one domain can have more than one admin. (hen a user logs into the application, his access rights will be restricted so that he can see and modif' onl' the data that he is allowed to. For e0ample, he will be able to see and modif' onl' the .ASes, clients and logs of his domains.

 %n order to register .ASes and clients, now 'ou can logout from the application "b' closing all the windows of the browser# and then login as a normal user "domain administrator#. Adding .ASes and clients can also be done b' the superuser, since he has access ever'where.

(hile adding .ASes "HotSpot servers/routers# the important fields are the MAC and %!, which are used to allow the .AS to connect to radius and to identif' to which domain it belongs. The other fields "+atewa', 9.S etc.# are 8ust informational "ma'be later the' can be used to configure the .AS automaticall'#. For the clients, the most important fields, besides Username and assword, are the Service and the !xpiration "ime. The other limits "Download #imit etc.# are not functional 'et.

 Then 'ou can go to the module of #ogs and see the activit' that is done in the application b' 'ou and the other users. The logs can be filtered b' time, event etc, so that 'ou can find easil' what 'ou are loo ing for. The logs that are displa'ed are restricted b' the domains to which the user has access.

The module Settings is meant for the users to update their own data and for the domain admins to see the data of their domains and to update some of them.

The module Misc right now has 8ust one important submodule, which is used to bac up/restore the

data of the database. %n the future releases it ma' contain other things as well.

$.>. 9iagrams

%. FreeRAD$&S
2.$. %nstalling
% installed FreeRA9%4S on Fedora. First % installed the pac ages freeradius and freeradius$mys%l 7
bash< y m insta** "reeradi s "reeradi s0mysA*

Then % enabled the service radiusd and started it7

bash< !sbin!ch3con"ig 00*ist radi sd bash< !sbin!ch3con"ig radi sd on bash< !sbin!ch3con"ig 00*ist radi sd bash< !sbin!ser+ice radi sd start

Since freeradius uses the ports 1'1% and 1'1( "see e.g. the file !etc!ser+ices #, % had to open these ports in the firewall, both for tcp and udp . %n order to do this, % edited the file !etc!syscon"ig!iptab*es and added there these lines7
04 04 04 04 BH0&ire-a**0)0/$P%1 BH0&ire-a**0)0/$P%1 BH0&ire-a**0)0/$P%1 BH0&ire-a**0)0/$P%1 0m state 00state $CD 0m tcp 0p tcp 00dport )8)2 0E 4CCCP1 0m dp 0p dp 00dport )8)2 0E 4CCCP1 0m state 00state $CD 0m tcp 0p tcp 00dport )8)F 0E 4CCCP1 0m dp 0p dp 00dport )8)F 0E 4CCCP1

To appl' these modifications in firewall, % restarted the service iptables7

bash< !sbin!ser+ice iptab*es restart

)ip: To chec that the ports $?$2 and $?$6 are open in the firewall, we can use one of these
commands7
bash< !sbin!ser+ice iptab*es stat s G grep )8)2 bash< !sbin!iptab*es0sa+e G grep )8)2

2.2. Testing
Bust to test that FreeRA9%4S is correctl' installed and wor s, we can ma e a simple configuration using the standard te0t files, li e this7 -dit the file !etc!raddb!c*ients.con" . At the section client &'(.).).& modif' the value of secret , for e0ample ma e it local& . The entr' client &'(.).).& * . . . + will allow the localhost to use the radius service. -dit the file !etc!raddb! sers . 4ncomment there the test user ste+e "or create another user with similar details#. %t should loo li e this7
ste+e C*eartext0Pass-ord 9= 5testing5 ,er+ice01ype = &ramed0%ser,

&ramed0Protoco* = PPP, &ramed0/P04ddress = )H2.)@.F.FF, &ramed0/P0$etmas3 = 288.288.288.0, &ramed0Bo ting = 2roadcast0'isten, &ramed0&i*ter0/d = 5std.ppp5, &ramed0I1% = )800, &ramed0Compression = (an0Jacobsen01CP0/P

-dit !etc!raddb!radi sd.con" and ma e sure that authori1ation using files is enabled. "%t should be enabled b' default, so in general 'ou don<t need to modif' an'thing.# .ow we can use the command radtest to reCuest access for user steve with password testing 7
bash< bash< bash< bash< bash< radtest radtest radtest radtest radtest --help ste+e testing )2H.0.0.) )0 *oca*) ste+e testing *oca*host )0 *oca*) ste+e testingK )2H.0.0.) )0 *oca*) ste+e testing )2H.0.0.) )0 *oca*)K

%n the first and second tests 'ou should get the answer <Access,Accept<. %n the last two tests 'ou should get the answer <Access,Re8ect<.

)ip: %n order to get more details about what happens in the server, run radiusd in debug
mode. First stop the service7 "sbin"ser*ice radiusd stop , then run it li e this7 "usr"sbin"radiusd +x or "usr"sbin"radiusd +, .

#ote: %f 'ou have (indows, 'ou ma' also wish to use .Trad!ing "downloadable from
MasterSoft # instead of radtest. %f 'ou do this, or test from an' other machine, remember to put 'our !C "or the other machine# in 'our .AS list in the file !etc!raddb!c*ients.con" .

2.6. 4sing M'SD&

.ow that radius is installed and we have tested that it wor s correctl', we can create a m'sCl database for it and configure radius to use this database. First let<s create a new database and a new database user7
bash6 mysA* 0p 0 root mysA*> CBC41C D41424,C radi sdb. mysA*> #B4$1 4'' L$ radi sdb.M 1L rad serN*oca*host /DC$1/&/CD 2O 5radpass5. mysA*> exit.

.ow lets create the tables of the database b' running the SD& script file that is in the director' "reeradi s!doc!examp*es!7
bash6 mysA* 0p 0 root 0D radi sdb < ! sr!share!doc!"reeradi s0 ).).H!examp*es!mysA*.sA*

(e should modif' now !etc!raddb!sA*.con" b' setting there the database, the username and the password that are needed to connect to the m'sCl server7

< Connect in"o ser+er = 5*oca*host5 *ogin = 5rad ser5 pass-ord = 5radpass5 < Database tab*e con"ig ration radi s;db = 5radi sdb5

#ote: For testing/debug purposes, change s%ltrace to yes. Then, freeradius will dump
all SD& commands to the debug output.

#ote: Eou ma' also need to modif' the line about s%l_user_name in this file.
-dit the file !etc!raddb!radi sd.con" and ma e there these modifications7 4ncomment the line sa'ing <sCl< in the authori,e*+ section and comment the line sa'ing <files<. Also uncomment the line sa'ing <sCl< to the accounting*+ section to tell FreeRA9%4S to store accounting records in SD& as well. This file should then loo something li e this7
a thorise P preprocess chap mschap s ""ix eap < "i*es sA* pap Q acco nting P < De *ea+e 5detai*5 enab*ed to ;additiona**y; *og acco nting to !+ar!*og!radi s!radacct detai* sA* Q

2.*. Testing M'SD&

-nter some data in the database7
bash6 mysA* 0 rad ser 0p radpassmysA*> %,C radi sdb. mysA*> ,HLD 142'C,. mysA*> /$,CB1 /$1L sergro p (%ser$ame, #ro p$ame) 00> (4'%C, (5radi stest5, 5testgro p5). mysA*> ,C'CC1 M &BLI sergro p. mysA*> /$,CB1 /$1L radchec3 (%ser$ame, 4ttrib te, (a* e) 00> (4'%C, (5radi stest5, 5Pass-ord5, 5testpass-ord5). mysA*> ,C'CC1 M &BLI radchec3. mysA*> /$,CB1 /$1L radgro prep*y (#ro p$ame, 4ttrib te, op, (a* e) 00> (4'%C, (5testgro p5,5&ramed0Compression5,5==5,5(an0Jacobsen01CP0/P5). mysA*> /$,CB1 /$1L radgro prep*y (#ro p$ame, 4ttrib te, op, (a* e) 00> (4'%C, (5testgro p5,5&ramed0Protoco*5,5==5,5PPP5).

mysA*> 00> mysA3> 00> mysA*>

/$,CB1 (4'%C, /$,CB1 (4'%C, A it.

/$1L radgro prep*y (#ro p$ame, 4ttrib te, op, (a* e) (5testgro p5,5&ramed0I1%5,5==5,5)8005). /$1L radgro prep*y (#ro p$ame, 4ttrib te, op, (a* e) (5testgro p5,5,er+ice01ype5,5==5,5&ramed0%ser5).

Then stop the service "sbin"ser*ice radiusd stop and run radiusd in debug mode7 "usr"sbin"radiusd +x or "usr"sbin"radiusd +, . .ow chec access for the user radiustest with password testpassword 7
bash< radtest radi stest testpass-ord *oca*host )0 *oca*) ,ending 4ccess0BeA est o" id 22R to )2H.0.0.) port )8)2 %ser0$ame = 5radi stest5 %ser0Pass-ord = 5testpass-ord5 $4,0/P04ddress = 288.288.288.288 $4,0Port = )0 rad;rec+9 4ccess04ccept pac3et "rom host )2H.0.0.)9)8)2, id=22R, *ength=RR &ramed0Compression = (an0Jacobson01CP0/P &ramed0Protoco* = PPP &ramed0I1% = )800 ,er+ice01ype = &ramed0%ser

(. S-. A/$
This SD& A!% helps to access the database of the freeRadius "or Radius Manager# from the HotSpot Manager "which manages the services and users#. it is a librar' of M'SD& procedures, which can be used to access and modif' the database. %t encapsulates "hides# the comple0it' of the database from the outside programmer. The programmer doesn<t have to now what tables or fields are there in the database, but 8ust needs to now the procedures/functions that are available in the A!%, their parameters, return values, etc. %t also ma es simpler the code of the program, because instead of using complicated SD& Cueries, it 8ust needs to call a procedure with the appropriate parameters.

6.$. Radius SD& A!%

proced re ser;sa+e(p; sername p;pass-ord p;ser+ice p;domain +archar(@R), +archar(28F), +archar(@R), +archar(28F) )

Ta es the parameters7 username, password, service. %n case that such a user e0ist, it is deleted first, and then new records about the user are inserted.
> ca** 00 > ca** 00 radi s. ser;sa+e(> ser0)>,>pass-0)>,>test0)>,>domain0)>). create the ser > ser0)> -hich has access at >domain0)> radi s. ser;sa+e(> ser0)>,>xy7>,>test0)>,>domain0)>). change the pass-ord o" > ser0)>

" nction

ser;chec3(p; sername +archar(@R)) ret rns +archar(@R)

4sed to chec whether a user alread' e0ists in radiusdb "in the table radchec #. %f there is such a user, then it returns its username.
> se*ect radi s. ser;chec3(> ser0)>) as S0000000000S G sername G S0000000000S G ser0) G S0000000000S > se*ect radi s. ser;chec3(> ser02>) as S0000000000S G sername G S0000000000S G G S0000000000S sername.

sername.

proced re

ser;get(p; sername +archar(@R), p;ser+ice +archar(@R) )

Returns the data of a given user. !arameters are username and service patterns. Matching is done with &%F-. The records that are returned have the fields7 username, service
> ca** ser;get(> ser0)>, >T>). 00 get the data o" > ser0)> > ca** ser;get(>T>, >ser+ice0)>). 00 get the data o" a** the sers that ha+e the ser+ice >ser+ice0)> > ca** ser;get(>T>, >T>). 00 get the data o" a** the sers

proced re

ser;de*(p; sername +archar(@R))

9elete the given user.

> ca** radi s. ser;de*(> ser02>). 00 de*ete ser > ser02>

proced re ser+ice;sa+e(p;ser+ice;name +archar(@R), p;do-n*oad;rate int())), p; p*oad;rate int())))

Save "add or update# a service. Ta es the parameters7 serviceAname, downloadArate, uploadArate. 9ownload and upload rates are integers in Fbps. %f a service with such a name alread' e0ists, it is deleted first.
> ca** 00 > ca** 00 > ca** 00 radi s.ser+ice;sa+e(>test0)>, 28@, )28). create the ser+ice test0) -ith 28@Ubps do-n*oad and )28Ubps radi s.ser+ice;sa+e(>test02>, 8)2, )28). add another ser+ice radi s.ser+ice;sa+e(>test02>, 8)2, 28@). change the p*oad rate o" the ser+ice test02 p*oad

 proced re ser+ice;get(p;ser+ice;name +archar(@R))

Return a list of services that match the given parameter. Matching is done with &%F-. The result that is returned contains the fields7 service, dwmload rate, upload rate, where the rates are integers of Fbps.
> ca** radi s.ser+ice;get(>test0)>). 00 get the data o" the ser+ice >test0)> > ca** radi s.ser+ice;get(>T>). 00 get the data o" a** the ser+ices S0000000000S000000000000000S0000000000000S G ser+ice G do-n*oad;rate G p*oad;rate G S0000000000S000000000000000S0000000000000S G test0) G 28@ G )28 G G test02 G 8)2 G 28@ G S0000000000S000000000000000S0000000000000S

proced re ser+ice;de*(p;ser+ice +archar(@R))

9elete the service with the given name.

> ca** radi s.ser+ice;de*(>test02>). 00 de*ete the ser+ice that is named >test02>

proced re change;ser+ice;name(p;o*d;ser+ice +archar(@R) p;ne-;ser+ice +archar(@R))

Changes the name of a service, so that all the clients that were using the old service now use the new service.
> ca** radi s.change;ser+ice;name(>test02>, >test2>). 00 change the name o" the ser+ice >test02> to >test2>

6.2. RM SD& A!%

proced re rm; ser;sa+e(p; sername p;pass-ord p;ser+ice;id p;expiration;date p;" **name p;emai* +archar(F2), +archar(F2), int())), date, +archar(F0), +archar(80))

Save a user in the table rmAusers of the Radius Manager. Ta es these parameters7 username, password, serviceAid, e0pirationAdate, fullname, email

%n case that such a user e0ist, it is deleted first, and then new records about the user are inserted.
proced re rm; ser;de*(p; sername +archar(F2))

9elete the given user.

proced re rm; ser;get(p; sername +archar(F2))

Returns the data of a given user. +ets the username of the user as a parameter "t'pe7 varchar"62##, and returns one or more records with the data of the users who match the data of the username. Matching is done with &%F-. %t ma' return nothing if such a user does not e0ist. The record that is returned has these fields7 username, srvname, e0piration, enabled
proced re rm;nas;insert(p;ip p;name p;secret p;description +archar()28), +archar()28), +archar(@0), +archar(200))

Add a new record in the table <nas<.

proced re rm;nas; pdate(p;ip p;name p;secret p;description +archar()28), +archar()28), +archar(@0), +archar(200))

4pdate a record in the table <nas<.

proced re rm;nas;de*ete(p;ip +archar()28))

9elete a record in the table <nas<.

" nction rm;nas;chec3(p;ip +archar()28)) ret rns +archar()28)

4sed to chec whether an %! is alread' registered in the nas table. %f it is registered, then it returns the %!, otherwise returns <not,found<.
> se*ect radi s.rm;nas;chec3(>)?2.)@8.0.)0>) as ip. S00000000000000S G ip G S00000000000000S G )?2.)@8.0.)0 G S00000000000000S > se*ect radi s.rm;nas;chec3(>)?2.)@8.0.))>) as ip. S00000000000S G ip G S00000000000S G not0"o nd G S00000000000S

0. HotSpot Ser*ers
There are different wa's for implementing a HotSpot server. Here % am going to describe how to configure a HotSpot service in Mi roTi , how to install and configure ChilliSpot and CoovaChilli on a linu0 server, and how to install and configure CoovaA! on a wireless router.

*.$. Mi roTi
+eneral networ configuration7
<<< an address on the o tside (D4$) inter"ace o" the mi3roti3 ! ip address add address=)?2.)@8.F8.)00!2R inter"ace=ether) <<< add a gate-ay < ! ip ro te add gate-ay=)?2.)@8.F8.) <<< set the D$, ser+ers ! ip dns set primary0dns=)?2.)@8.F8.)) secondary0dns=R.2.2.2

Radius configuration7
<<< add another address "or connecting to the radi s ser+er ! ip address add address=)?2.)@8.28.)2)!2R inter"ace=ether2 <<< add radi s ser+ers "or any PPP ser+ice on mi3roti3 ! radi s add ser+ice=hotspot address=)?2.)@8.28.)0) secret=radi ssecret timeo t=2000ms ! radi s incoming set accept=yes

Setup masCuerading7
<<< set p $41 on the o tside inter"ace o" the mi3roti3 ! ip "ire-a** nat add chain=srcnat o t0inter"ace=ether) action=masA erade <<< disab*e masA erading "or the radi s '4$ ()?2.)@8.28.0!2R) ! ip "ire-a** nat add chain=srcnat o t0inter"ace=ether) : src0address=)?2.)@8.28.0!2R action=ret rn ! ip "ire-a** nat print ! ip "ire-a** nat mo+e ) 0

Add a pool7
<<< add a poo* ! ip poo* add name=poo*0 ranges=)?2.)@8.)0.0!)@

Add a hotspot server profile7

! ip hotspot pro"i*e add name=5pro")5 hotspot0address=)?2.)@8.)0.) dns0name=5hotspot).a*5 htm*0directory=hotspot se0radi s=yes radi s0 acco nting=yes

 Add a hotspot server7

! ip hotspot add name=5ser+er)5 inter"ace=ether2 address0poo*=poo*) pro"i*e=pro")

Add a user profile7

! ip hotspot ser pro"i*e add name=5 serpro"i*e)5 address0poo*=poo*) transparent0proxy=no

Add a user7
! ip hotspot ser add ser+er=ser+er) name=5 ser)5 pass-ord=5pass-)5 pro"i*e= serpro"i*e)

Modif' the hotspot login pages.

*.$.$. Referencies
http7//www.mi roti .com/testdocs/ros/2.=/ip/hotspot.php http7//www.mi roti .com/testdocs/ros/2.=/guide/aaaAhotspot.php

*.2. ChilliSpot

*.2.$. %ntroduction
ChilliSpot is used as an access point controller in a wireless &A.. A t'pical networ architecture is shown in the figure below. A wireless client can establish a wireless connection to an access point, but in order to reach the -0ternal .etwor it first has to authenticate with Chilli.

Three different networ s are involved in the architecture7 !xternal -etwor. . The e0ternal networ is t'picall' the %nternet or a corporate intranet. Access to the

e0ternal networ is guarded b' Chilli which onl' allows traffic from authenticated wireless clients to pass. /nternal -etwor. . The internal networ is connecting the access points with Chilli. %t is used for forwarding -thernet frames between Chilli and the wireless clients as well as for %! management traffic to and from the access points. 0ireless -etwor. 7 The wireless clients are connected to the wireless networ , and the access points serve as bridges between the internal networ and the wireless networ . This enables forwarding of -thernet frames between Chilli and the wireless clients. %n the e0ample above the wireless networ is allocated the address range $=2.$>?.$?2.:/2*. %n order to function properl' Chilli depends on a few e0ternal servers7 D-S Server . (hen accessing the e0ternal networ the wireless clients rel' on one or several 9.S servers for resolving domain names to %! addresses. The wireless clients are informed of the 9.S server %! addresses b' the Chilli. Gefore 'ou start the installation of ChilliSpot 'ou need to determine the %! address of at least one 9.S server which can be used b' the wireless clients. %f 'ou don<t specif' a 9.S server Chilli will use the 9.S server which is reported b' the underl'ing operating s'stem. U1M Server . (hen a user logs on he is redirected to an authentication web server which Cueries the user for her username and password. %f a separate uam server is not available it is possible to install one on the Chilli server. Radius Server . 4ser credentials are stored in one or several radius servers. (henever a wireless client attempts to connect to the networ Chilli will contact a radius server in order to validate the user credentials. %f a separate radius server is not available it is possible to install one on the Chilli server. +enerall' the access points should be configured with open authentication and no encr'ption. Authentication is handled b' Chilli. For better securit', the access points should be configured for (ireless !rotected Access.

*.2.2. %nstalling and Configuring

9ownload from http7//www.chillispot.info/download.html the latest R!M pac age and install it with the command7
rpm 0%h+ chi**ispot0).).0.iF8@.rpm

9uring installation of ChilliSpot a configuration file was copied to !etc!chi**i.con" . Eou need to edit this file. A description of each option is given in the man page " man chilli #. As a start 'ou can leave most of the parameters as the' are. %f 'ou use an e0ternal radius server 'ou need to modif' the parameters7 radiusserver& , radiusserver' , radiussecret . %f 'ou are not using an e0ternal radius server 'ou can leave these parameters as the' are, as we will install a radius server later during the installation. %f 'ou use an e0ternal 4AM server 'ou need to modif' the parameter uamserver . %f 'ou are

not using an e0ternal 4AM server 'ou can leave this parameters as it is, as we will install an 4AM server later during the installation. %n order to automate startup of chilli issue the command7
ch3con"ig chi**i on

ChilliSpot will start ne0t time 'ou reboot the s'stem, or 'ou can start it directl' b' issuing the command
ser+ice chi**i start

*.2.6. Firewall Setup

%t is important to protect ChilliSpot from unauthori1ed traffic. .o single firewall ruleset can satisf' all networ configurations, and generall' 'ou should write 'our own set of rules. As a starting point 'ou can use the script located in7 ! sr!share!doc!chi**ispot0).).0!"ire-a**.iptab*es . Eou can edit this file to suit 'our own configuration or simpl' use it without modification. 3nce 'ou have edited the file install it b' issuing the following commands7
ser+ice iptab*es stop ! sr!share!doc!chi**ispot0).).0!"ire-a**.iptab*es ser+ice iptab*es sa+e

This will first clear the current firewall rules, install the new rules and finall' save the rules so that the' will be restored whenever the s'stem is rebooted. %n order for ChilliSpot to forward networ pac ets, %! forwarding must be turned on in the ernel. Eou need to change this line in !etc!sysct*.con" 7
net.ip+R.ip;"or-ard = )

The changes ta e effect when 'ou reboot the s'stem, or 'ou can activate them directl' b' issuing the command
!sbin!sysct* 0p

*.2.*. 4AM Authentication (eb Server

(e will now configure Apache to reCuest username and password from the wireless clients7 9uring installation of ChilliSpot a cgi script was placed in ! sr!share!doc!chi**ispot0 ).).0!hotspot*ogin.cgi . Cop' this script to !+ar!---!cgi0 bin!hotspot*ogin.cgi on the web server. (e need to tell Chilli about the location of the authentication server. This is done b' uncommenting and editing the following line in !etc!chi**i.con" 7

amser+er https9!!)?2.)@8.)82.)!cgi0bin!hotspot*ogin.cgi

(e need to restart chilli in order for the configuration changes to ta e effect7

ser+ice chi**i restart

*.2.). Configuring FreeRA9%4S

(e will now configure FreeRA9%4S to authenticate the HotSpot users. %nsert users in the radius database. -dit raddb!c*ients.con" in order to configure the %! address and shared secret of chilli. The secret must match the radiussecret parameter in !etc!chi**i.con". Tell Chilli about the location of the radius server. This is done b' uncommenting and editing the following lines in !etc!chi**i.con" 7
radi sser+er) )2H.0.0.) radi sser+er2 )2H.0.0.) radi ssecret testing)2F

Restart chilli in order for the configuration changes to ta e effect7 ser*ice chilli restart.

*.2.>. Referencies
http7//www.chillispot.info/download.html http7//www.chillispot.info/release.htmlHmo1Toc%d?>I??? http7//global.freifun .net/item/chillispotAhowto

*.6. CoovaChilli

*.6.$. %ntroduction
CoovaChilli is an open,source software access controller, based on the popular ChilliSpot pro8ect. %t is a feature rich software access controller that provides a captive portal 2 walled$garden environment and uses RA9%4S for access provisioning.

*.6.2. %nstalling
From a R!M pac age7
-get http9!!ap.coo+a.org!chi**i!coo+a0chi**i0).0.))0).iF8@.rpm s do rpm 0% coo+a0chi**i0).0.))0).iF8@.rpm

Guilding from source7

-get http9!!ap.coo+a.org!chi**i!coo+a0chi**i0).0.)).tar.g7 tar x7" coo+a0chi**i0).0.)).tar.g7 cd coo+a0chi**i0).0.)) .!con"ig re ma3e s do ma3e insta**

Guilding the last version from SJ.7

s+n chec3o t http9!!de+.coo+a.org!s+n!coo+a0chi**i! cd coo+a0chi**i sh bootstrap .!con"ig re ma3e s do ma3e insta**

G' default it will be installed on ! sr!*oca*! .

*.6.6. Configuration
+o to !etc!chi**i! "or ! sr!*oca*!etc!chi**i! # and ma e a cop' of de"a *ts to con"ig 7
cd !etc!chi**i! cp de"a *ts con"ig

Modif' !etc!chi**i!con"ig li e this7

<<< < 'oca* $et-or3 Con"ig rations

< H,;D4$/&=eth0 < D4$ /nter"ace to-ard the /nternet H,;'4$/&=eth) < , bscriber /nter"ace "or c*ient de+ices H,;$C1DLBU=)0.).0.0 < Hot,pot $et-or3 (m st inc* de H,;%4I'/,1C$) H,;$C1I4,U=288.288.288.0 < Hot,pot $et-or3 $etmas3 H,;%4I'/,1C$=)0.).0.) < Hot,pot /P 4ddress (on s bscriber net-or3) H,;%4IPLB1=F??0 < Hot,pot Port (on s bscriber net-or3) <<< < Hot,pot settings "or simp*e Capti+e Porta* < H,;%4I,CCBC1= H,;B4D/%,=)?2.)@8.28.)0) H,;B4D/%,2=)?2.)@8.28.)02 H,;B4D,CCBC1=test H,;$4,/P=)?2.)@8.F8.R@ < 1o exp*icit*y set $4,0/P04ddress

< 1he ser+er to be sed in combination -ith H,;%4I&LBI41 to < create the "ina* chi**i > amser+er> r* con"ig ration. H,;%4I,CB(CB=)?2.)@8.28.)00 < %se H,;%4I&LBI41 to de"ine the act a* capti+e porta* r*. < ,he** +ariab*e rep*acement ta3es p*ace -hen e+a* ated, so here < H,;%4I,CB(CB is escaped and *ater rep*aced by the pre0de"ined < H,;%4I,CB(CB to "orm the act a* 500 amser+er5 option in chi**i. H,;%4I&LBI41=http9!!:6H,;%4I,CB(CB! am! < ,ame principa* goes "or H,;%4IHLICP4#C. H,;%4IHLICP4#C=http9!!:6H,;%4I'/,1C$9:6H,;%4IPLB1!---!coo+a.htm* H,;'LC;$4IC=5Hot,pot)5 < D/,Pr 'ocation $ame and sed in porta*

Caution: Ge sure to leave empt' HSA4AMS-CR-T, since we are going to use the
BS3. interface , otherwise the users will fail to login . Start the chilli service7
ch3con"ig chi**i on ch3con"ig 00*ist chi**i ser+ice chi**i start ser+ice chi**i stat s

(hen the service is started, it will automaticall' create the configuration files hs.con", *oca*.con" and main.con" from con"ig . (hen the con"ig is modified, the chilli service must be restarted as well. %n the config file we have defined the uamserver li e this7
H,;%4I,CB(CB=)?2.)@8.28.)00 H,;%4I&LBI41=http9!!:6H,;%4I,CB(CB! am!

This is a webserver different from the server where coova,chilli is installed. %n this server we have to create an index.htm* file7

m3dir 0p !+ar!---!htm*! am! cd !+ar!---!htm*! am! -get http9!!coo+a.org! am! -get http9!!coo+a.org!Es!chi**i.Es

Then, we should edit index.htm* to use chi**i.Es from local. (e can also modif' index.htm* as we li e.

#ote: The authentication page http7//$=2.$>?.2).$::/uam/inde0.html can actuall' be

an' page, enough that it contains the line7
<script id=>chi**iEs> src=>chi**i.Es>><!script>

For more details see An' page a login page .

*.6.*. Referencies
CoovaChilli CoovaChilli 9ocumentation CoovaChilli 9evelopment CoovaChilli HowTo CoovaAAA Captive !ortal CoovaChilli Forum An' page a login page CoovaChilli BS3. %nterface

*.*. CoovaA!

*.*.$. %ntroduction
CoovaA! Firmware is a linu0 s'stem that can be installed in a wireless router. %n this s'stem are included several pac ages/tools that e0tend and enhance the features of the router. CoovaA! is an 3pen(RT,based firmware designed especiall' for HotSpots. %t comes with the CoovaChilli access controller built,in and ma es it easil' configurable. CoovaA! is perfect for 8ust about an' HotSpot application , from (!A -nterprise "with RA9%4S accounting# to Free (iFi with Terms of Service ac nowledgment to commercial HotSpot captive portal applications. The configuration of the router is managed through a web,interface, but it is also possible to login via ssh into the router. The wireless routers that are supported b' CoovaA! are7 &in s's (RT)*+&, &in s's (RT)*+, &in s's (RT)*+S, &in s's (RT)*+S v*, etc.

The e' features of CoovaA! are7 3pen,source, based on 3pen(rt Advanced (eb,based Configuration -as' HotSpot Configuration K Status CoovaChilli Access Controller -mbedded Captive !ortal Faceboo HotSpot Captive !ortal %ntegrated CoovaChilli with (!A 3pen%9 Authentication Centrali1ed CoovaChilli Configuration (iFi9og Access Controller !!T! J!. Client and Server 3penJ!. Client Traffic Shaping (9S HotSpot For more details loo at the CoovaA! homepage.

*.*.2. %nstalling
The installation is described ver' well in the page CoovaA! Firmware %nstallation http7//coova.org/wi i/inde0.php/%nstallationAHelp.

*.*.6. Configuration
At System 2 Settings 7
,ystem ,ettings Host $ame boot;-ait 'ang age ,ystem 4dministration D4$ ,,H 4ccess D4$ Deb 4ccess Hot,pot ,,H 4ccess 9 'in3,ys 9 Cnab*ed 9 Cng*ish 9 Cnab*ed 9 H11P, Ln*y 9 Cnab*ed

Hot,pot '4$ Deb 4ccess 9 H11P, Ln*y

At -etwor. 2 DH3 7
DHCP ,ettings '4$ DHCP ,er+ices 9 Cnab*ed ,tarting 4ddress 9 )?2.)@8.).)00 $ mber o" 4ddresses 9 )80

At -etwor. 2 01- 7
D4$ Con"ig ration Connection 1ype 9 ,tatic /P /P ,ettings /P 4ddress 9 )?2.)@8.28.F) $etmas3 9 288.288.288.0 De"a *t #ate-ay 9 )?2.)@8.28.) D$, ,er+ers )?2.)@8.28.)0) R.2.2.2

At -etwor. 0ireless 7
Dire*ess Con"ig ration Dire*ess /nter"ace 9 C,,/D 2roadcast 9 C,,/D 9 Channe* 9 Iode 9 Cncryption ,ettings Cncryption 1ype Cnab*ed ,hoDi&i )) 4ccess Point

9 Disab*ed

At -etwor. 2 1dvanced 0ireless 7

,ettings /so*ate D'4$ c*ients 9 Cnab*ed

At HotSpot 2 3onfiguration 7
Hot,pot Con"ig rations Hot,pot 1ype 9 Chi**i,pot %4I Hot,pot Iode 9 '4$ V Dire*ess Chi**i,pot Con"ig rations 4 to Con"ig ration 9 Deb %B' Deb Con"ig %B' 9 http9!!)?2.)@8.28.)00!hotspot!con"ig!

At HotSpot 2 #ocation 7
Hotspot 'ocation

'ocation $ame 'ocation 4ddress $et-or3 $ame Co ntry /,L Code

9 9 9 9

'ocation 4ddress $et-or3 4'

*.*.*. Radius Configuration

%n the interface HotSpot 2 3onfiguration we have these settings7
Hot,pot Con"ig rations Hot,pot 1ype 9 Chi**i,pot %4I Hot,pot Iode 9 '4$ V Dire*ess Chi**i,pot Con"ig rations 4 to Con"ig ration 9 Deb %B' Deb Con"ig %B' 9 http9!!)?2.)@8.28.)0)!hscon"ig!

The configuration of ChilliSpot "coova,chilli# is retrieved from the server $=2.$>?.2).$:$ b' http. The configuration file index.htm* in this server has this content7
amser+er http9!!---.examp*e.net!hs! radi sser+er) )?2.)@8.28.)0) radi sser+er2 )?2.)@8.28.)02 radi ssecret secretpassradi snasid Hot,pot ama**o-ed ---.examp*e.net

%t contains the configuration of the radius server. The parameter uamserver contains the 4R& of the web page that will be used b' the clients to login to internet. %n case that the configuration is different for different routers, then the setting 0e4 3onfig UR# should be different, so that the' can load different configurations. This can be useful if we want to have a different radiusnasid for different routers and a different "personali1ed# login page.

*.*.). &ogin !age

The login page that is located at http7//www.e0ample.net/hs/ consists of an html and a 8avascript file, as described at CoovaChilli BS3. %nterface . The content of the file index.htm is this7
<htm*> <head> <W00 4 p re*y H1I' based capti+e porta* 00> <tit*e>coo+a hotspot<!tit*e> <sty*e><W00 body,td,a,p,hP "ont0"ami*y9aria*,sans0seri". Q body P sing the J,L$ inter"ace o" Coo+aChi**i

Q <IyChi**i P bac3gro nd9 r*(5coo+a.Epg5) right top no0repeat. margin9 a to. text0a*ign9 *e"t. padding9 )0px 0 F0px 0. Q <*ocation$ame P height9 80px. "ont0si7e9 )20T. "ont0-eight9 bo*d. Q <chi**iPage P border9 )px so*id orange. padding9 20px 20px 20px 20px. margin0top9 20px. Q <sign%pBo- P disp*ay9 in*ine. Q 00> <!sty*e> <!head> <body> <di+ id=5IyChi**i5> <di+ id=5no'ocation5 sty*e=5disp*ay9none.5> <p sty*e=5padding0top9 )00px.5><strong>Oo are not at a hotspot.<!strong> /" yo -ant to see a a samp*e *ogin page sing the <a hre"=5http9!!coo+a.org!-i3i!index.php!Coo+aChi**i!J,L$5>J,L$ inter"ace<!a> o" <a hre"=5http9!!coo+a.org!-i3i!index.php!Coo+aChi**i5>Coo+aChi**i<!a>, then <a hre"=5Ea+ascript9 -indo-.*ocation = >+ie-0so rce9> S -indo-.*ocation.hre".5>+ie- the so rce<!a> o" this page.<!p> <!di+> <h)>Homepage<!h)> <script id=>chi**iEs> src=>chi**i.Es>><!script> <!di+> <!body> <!htm*>

text0a*ign9 center. padding0top9 F0px. margin9 a to. -idth9 80T.

The content of the file chi**i.Es is this7

i" (na+igator.app(ersion.indexL"(5I,/C5)W=0)) doc ment.-rite(5<script type=>text!Ea+ascript> id=>chi**icontro**er>><!script>5). i" (W-indo-.A eryLbE) P -indo-.A eryLbE = ne- LbEect(). -indo-.*ocation.search.rep*ace(ne- BegCxp(5(XYZ=V[S)(=(XYV[M))Z5,5g5), " nction(60,6),62,6F) P A eryLbEX6)[ = 6F. Q). Q i" (A eryLbEX> amip>[ W= n ** VV A eryLbEX> amport>[ W= n **) P +ar script = doc ment.getC*ement2y/d(>chi**icontro**er>).

i" (script == n **) P script = doc ment.createC*ement(>script>). script.id = >chi**icontro**er>. script.type = >text!Ea+ascript>. script.src = >http9!!>SA eryLbEX> amip>[S>9>SA eryLbEX> amport>[ S>!---!chi**iEs.chi>. +ar head = doc ment.getC*ements2y1ag$ame(5head5)X0[. i" (head == n **) head = doc ment.body. head.appendChi*d(script).

Q script.src = >http9!!>SA eryLbEX> amip>[S>9>SA eryLbEX> amport>[ S>!---!chi**iEs.chi>. Q e*se P +ar no'ocation = doc ment.getC*ement2y/d(5no'ocation5). i" (no'ocation W= n ** VV no'ocation.sty*e) P no'ocation.sty*e.disp*ay = >in*ine>. Q

*.*.>. Duic Config

After a CoovaA! wireless router has been configured properl', its configuration can be bac up,ed in order to use it for Cuic reconfiguration of the device. The configuration can be downloaded and uploaded at the interface System 2 3onfig Management . The configuration bac up can also be used to configure Cuic l' a new router. %n this case, these configuration settings should be modified manuall'7 / 1ddress at -etwor. 2 01- has to be modified. HotSpot 2 #ocation can be modified. 0e4 3onfig UR# at HotSpot 2 3onfiguration can be modified optionall', in case that we want to provide a customi1ed login page, radius server, etc.

*.*.I. Referencies
CoovaA! Firmware CoovaA! Firmware %nstallation CoovaChilli BS3. %nterface CoovaA! Forum

1. 2#& Free Documentation .icense

Jersion $.2, .ovember 2::2
Copyright (C) 2000,200),2002 &ree ,o"t-are &o ndation, /nc.

8? 1emp*e P*ace, , ite FF0, 2oston, I4

02)))0)F0H, %,4

C+eryone is permitted to copy and distrib te +erbatim copies o" this *icense doc ment, b t changing it is not a**o-ed.

$. !R-AMG&The purpose of this &icense is to ma e a manual, te0tboo , or other functional and useful document free in the sense of freedom7 to assure ever'one the effective freedom to cop' and redistribute it, with or without modif'ing it, either commerciall' or noncommerciall'. Secondaril', this &icense preserves for the author and publisher a wa' to get credit for their wor , while not being considered responsible for modifications made b' others. This &icense is a ind of Lcop'leftL, which means that derivative wor s of the document must themselves be free in the same sense. %t complements the +.4 +eneral !ublic &icense, which is a cop'left license designed for free software. (e have designed this &icense in order to use it for manuals for free software, because free software needs free documentation7 a free program should come with manuals providing the same freedoms that the software does. Gut this &icense is not limited to software manuals; it can be used for an' te0tual wor , regardless of sub8ect matter or whether it is published as a printed boo . (e recommend this &icense principall' for wor s whose purpose is instruction or reference. 2. A!!&%CAG%&%TE A.9 9-F%.%T%3.S This &icense applies to an' manual or other wor , in an' medium, that contains a notice placed b' the cop'right holder sa'ing it can be distributed under the terms of this &icense. Such a notice grants a world,wide, ro'alt',free license, unlimited in duration, to use that wor under the conditions stated herein. The L9ocumentL, below, refers to an' such manual or wor . An' member of the public is a licensee, and is addressed as L'ouL. Eou accept the license if 'ou cop', modif' or distribute the wor in a wa' reCuiring permission under cop'right law. A LModified JersionL of the 9ocument means an' wor containing the 9ocument or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A LSecondar' SectionL is a named appendi0 or a front,matter section of the 9ocument that deals e0clusivel' with the relationship of the publishers or authors of the 9ocument to the 9ocument<s overall sub8ect "or to related matters# and contains nothing that could fall directl' within that overall sub8ect. "Thus, if the 9ocument is in part a te0tboo of mathematics, a Secondar' Section ma' not e0plain an' mathematics.# The relationship could be a matter of historical connection with the sub8ect or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The L%nvariant SectionsL are certain Secondar' Sections whose titles are designated, as being those of %nvariant Sections, in the notice that sa's that the 9ocument is released under this &icense. %f a section does not fit the above definition of Secondar' then it is not allowed to be designated as %nvariant. The 9ocument ma' contain 1ero %nvariant Sections. %f the 9ocument does not identif' an' %nvariant Sections then there are none. The LCover Te0tsL are certain short passages of te0t that are listed, as Front,Cover Te0ts or Gac , Cover Te0ts, in the notice that sa's that the 9ocument is released under this &icense. A Front,Cover Te0t ma' be at most ) words, and a Gac ,Cover Te0t ma' be at most 2) words.

A LTransparentL cop' of the 9ocument means a machine,readable cop', represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardl' with generic te0t editors or "for images composed of pi0els# generic paint programs or "for drawings# some widel' available drawing editor, and that is suitable for input to te0t formatters or for automatic translation to a variet' of formats suitable for input to te0t formatters. A cop' made in an otherwise Transparent file format whose mar up, or absence of mar up, has been arranged to thwart or discourage subseCuent modification b' readers is not Transparent. An image format is not Transparent if used for an' substantial amount of te0t. A cop' that is not LTransparentL is called L3paCueL. -0amples of suitable formats for Transparent copies include plain ascii without mar up, Te0info input format, &aTeM input format, S+M& or MM& using a publicl' available 9T9, and standard, conforming simple HTM&, !ostScript or !9F designed for human modification. -0amples of transparent image formats include !.+, MCF and B!+. 3paCue formats include proprietar' formats that can be read and edited onl' b' proprietar' word processors, S+M& or MM& for which the 9T9 and/or processing tools are not generall' available, and the machine,generated HTM&, !ostScript or !9F produced b' some word processors for output purposes onl'. The LTitle !ageL means, for a printed boo , the title page itself, plus such following pages as are needed to hold, legibl', the material this &icense reCuires to appear in the title page. For wor s in formats which do not have an' title page as such, LTitle !ageL means the te0t near the most prominent appearance of the wor <s title, preceding the beginning of the bod' of the te0t. A section L-ntitled MENL means a named subunit of the 9ocument whose title either is precisel' MEN or contains MEN in parentheses following te0t that translates MEN in another language. "Here MEN stands for a specific section name mentioned below, such as LAc nowledgementsL, L9edicationsL, L-ndorsementsL, or LHistor'L.# To L!reserve the TitleL of such a section when 'ou modif' the 9ocument means that it remains a section L-ntitled MENL according to this definition. The 9ocument ma' include (arrant' 9isclaimers ne0t to the notice which states that this &icense applies to the 9ocument. These (arrant' 9isclaimers are considered to be included b' reference in this &icense, but onl' as regards disclaiming warranties7 an' other implication that these (arrant' 9isclaimers ma' have is void and has no effect on the meaning of this &icense. 6. J-RGAT%M C3!E%.+ Eou ma' cop' and distribute the 9ocument in an' medium, either commerciall' or noncommerciall', provided that this &icense, the cop'right notices, and the license notice sa'ing this &icense applies to the 9ocument are reproduced in all copies, and that 'ou add no other conditions whatsoever to those of this &icense. Eou ma' not use technical measures to obstruct or control the reading or further cop'ing of the copies 'ou ma e or distribute. However, 'ou ma' accept compensation in e0change for copies. %f 'ou distribute a large enough number of copies 'ou must also follow the conditions in section 6. Eou ma' also lend copies, under the same conditions stated above, and 'ou ma' publicl' displa' copies. *. C3!E%.+ %. D4A.T%TE %f 'ou publish printed copies "or copies in media that commonl' have printed covers# of the 9ocument, numbering more than $::, and the 9ocument<s license notice reCuires Cover Te0ts, 'ou must enclose the copies in covers that carr', clearl' and legibl', all these Cover Te0ts7 Front,Cover Te0ts on the front cover, and Gac ,Cover Te0ts on the bac cover. Goth covers must also clearl' and

legibl' identif' 'ou as the publisher of these copies. The front cover must present the full title with all words of the title eCuall' prominent and visible. Eou ma' add other material on the covers in addition. Cop'ing with changes limited to the covers, as long as the' preserve the title of the 9ocument and satisf' these conditions, can be treated as verbatim cop'ing in other respects. %f the reCuired te0ts for either cover are too voluminous to fit legibl', 'ou should put the first ones listed "as man' as fit reasonabl'# on the actual cover, and continue the rest onto ad8acent pages. %f 'ou publish or distribute 3paCue copies of the 9ocument numbering more than $::, 'ou must either include a machine,readable Transparent cop' along with each 3paCue cop', or state in or with each 3paCue cop' a computer,networ location from which the general networ ,using public has access to download using public,standard networ protocols a complete Transparent cop' of the 9ocument, free of added material. %f 'ou use the latter option, 'ou must ta e reasonabl' prudent steps, when 'ou begin distribution of 3paCue copies in Cuantit', to ensure that this Transparent cop' will remain thus accessible at the stated location until at least one 'ear after the last time 'ou distribute an 3paCue cop' "directl' or through 'our agents or retailers# of that edition to the public. %t is reCuested, but not reCuired, that 'ou contact the authors of the 9ocument well before redistributing an' large number of copies, to give them a chance to provide 'ou with an updated version of the 9ocument. ). M39%F%CAT%3.S Eou ma' cop' and distribute a Modified Jersion of the 9ocument under the conditions of sections 2 and 6 above, provided that 'ou release the Modified Jersion under precisel' this &icense, with the Modified Jersion filling the role of the 9ocument, thus licensing distribution and modification of the Modified Jersion to whoever possesses a cop' of it. %n addition, 'ou must do these things in the Modified Jersion7 A. 4se in the Title !age "and on the covers, if an'# a title distinct from that of the 9ocument, and from those of previous versions "which should, if there were an', be listed in the Histor' section of the 9ocument#. Eou ma' use the same title as a previous version if the original publisher of that version gives permission. G. &ist on the Title !age, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Jersion, together with at least five of the principal authors of the 9ocument "all of its principal authors, if it has fewer than five#, unless the' release 'ou from this reCuirement. C. State on the Title page the name of the publisher of the Modified Jersion, as the publisher. 9. !reserve all the cop'right notices of the 9ocument. -. Add an appropriate cop'right notice for 'our modifications ad8acent to the other cop'right notices. F. %nclude, immediatel' after the cop'right notices, a license notice giving the public permission to use the Modified Jersion under the terms of this &icense, in the form shown in the Addendum below. +. !reserve in that license notice the full lists of %nvariant Sections and reCuired Cover Te0ts given in the 9ocument<s license notice.

H. %nclude an unaltered cop' of this &icense. %. !reserve the section -ntitled LHistor'L, !reserve its Title, and add to it an item stating at least the title, 'ear, new authors, and publisher of the Modified Jersion as given on the Title !age. %f there is no section -ntitled LHistor'L in the 9ocument, create one stating the title, 'ear, authors, and publisher of the 9ocument as given on its Title !age, then add an item describing the Modified Jersion as stated in the previous sentence. B. !reserve the networ location, if an', given in the 9ocument for public access to a Transparent cop' of the 9ocument, and li ewise the networ locations given in the 9ocument for previous versions it was based on. These ma' be placed in the LHistor'L section. Eou ma' omit a networ location for a wor that was published at least four 'ears before the 9ocument itself, or if the original publisher of the version it refers to gives permission. F. For an' section -ntitled LAc nowledgementsL or L9edicationsL, !reserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor ac nowledgements and/or dedications given therein. &. !reserve all the %nvariant Sections of the 9ocument, unaltered in their te0t and in their titles. Section numbers or the eCuivalent are not considered part of the section titles. M. 9elete an' section -ntitled L-ndorsementsL. Such a section ma' not be included in the Modified Jersion. .. 9o not retitle an' e0isting section to be -ntitled L-ndorsementsL or to conflict in title with an' %nvariant Section. 3. !reserve an' (arrant' 9isclaimers. %f the Modified Jersion includes new front,matter sections or appendices that Cualif' as Secondar' Sections and contain no material copied from the 9ocument, 'ou ma' at 'our option designate some or all of these sections as invariant. To do this, add their titles to the list of %nvariant Sections in the Modified Jersion<s license notice. These titles must be distinct from an' other section titles. Eou ma' add a section -ntitled L-ndorsementsL, provided it contains nothing but endorsements of 'our Modified Jersion b' various parties,,for e0ample, statements of peer review or that the te0t has been approved b' an organi1ation as the authoritative definition of a standard. Eou ma' add a passage of up to five words as a Front,Cover Te0t, and a passage of up to 2) words as a Gac ,Cover Te0t, to the end of the list of Cover Te0ts in the Modified Jersion. 3nl' one passage of Front,Cover Te0t and one of Gac ,Cover Te0t ma' be added b' "or through arrangements made b'# an' one entit'. %f the 9ocument alread' includes a cover te0t for the same cover, previousl' added b' 'ou or b' arrangement made b' the same entit' 'ou are acting on behalf of, 'ou ma' not add another; but 'ou ma' replace the old one, on e0plicit permission from the previous publisher that added the old one. The author"s# and publisher"s# of the 9ocument do not b' this &icense give permission to use their names for publicit' for or to assert or impl' endorsement of an' Modified Jersion. >. C3MG%.%.+ 93C4M-.TS Eou ma' combine the 9ocument with other documents released under this &icense, under the terms

defined in section * above for modified versions, provided that 'ou include in the combination all of the %nvariant Sections of all of the original documents, unmodified, and list them all as %nvariant Sections of 'our combined wor in its license notice, and that 'ou preserve all their (arrant' 9isclaimers. The combined wor need onl' contain one cop' of this &icense, and multiple identical %nvariant Sections ma' be replaced with a single cop'. %f there are multiple %nvariant Sections with the same name but different contents, ma e the title of each such section uniCue b' adding at the end of it, in parentheses, the name of the original author or publisher of that section if nown, or else a uniCue number. Ma e the same ad8ustment to the section titles in the list of %nvariant Sections in the license notice of the combined wor . %n the combination, 'ou must combine an' sections -ntitled LHistor'L in the various original documents, forming one section -ntitled LHistor'L; li ewise combine an' sections -ntitled LAc nowledgementsL, and an' sections -ntitled L9edicationsL. Eou must delete all sections -ntitled L-ndorsements.L I. C3&&-CT%3.S 3F 93C4M-.TS Eou ma' ma e a collection consisting of the 9ocument and other documents released under this &icense, and replace the individual copies of this &icense in the various documents with a single cop' that is included in the collection, provided that 'ou follow the rules of this &icense for verbatim cop'ing of each of the documents in all other respects. Eou ma' e0tract a single document from such a collection, and distribute it individuall' under this &icense, provided 'ou insert a cop' of this &icense into the e0tracted document, and follow this &icense in all other respects regarding verbatim cop'ing of that document. ?. A++R-+AT%3. (%TH %.9-!-.9-.T (3RFS A compilation of the 9ocument or its derivatives with other separate and independent documents or wor s, in or on a volume of a storage or distribution medium, is called an LaggregateL if the cop'right resulting from the compilation is not used to limit the legal rights of the compilation<s users be'ond what the individual wor s permit. (hen the 9ocument is included in an aggregate, this &icense does not appl' to the other wor s in the aggregate which are not themselves derivative wor s of the 9ocument. %f the Cover Te0t reCuirement of section 6 is applicable to these copies of the 9ocument, then if the 9ocument is less than one half of the entire aggregate, the 9ocument<s Cover Te0ts ma' be placed on covers that brac et the 9ocument within the aggregate, or the electronic eCuivalent of covers if the 9ocument is in electronic form. 3therwise the' must appear on printed covers that brac et the whole aggregate. =. TRA.S&AT%3. Translation is considered a ind of modification, so 'ou ma' distribute translations of the 9ocument under the terms of section *. Replacing %nvariant Sections with translations reCuires special permission from their cop'right holders, but 'ou ma' include translations of some or all %nvariant Sections in addition to the original versions of these %nvariant Sections. Eou ma' include a translation of this &icense, and all the license notices in the 9ocument, and an' (arrant' 9isclaimers, provided that 'ou also include the original -nglish version of this &icense and the original versions of those notices and disclaimers. %n case of a disagreement between the translation and the original version of this &icense or a notice or disclaimer, the original version will prevail.

%f a section in the 9ocument is -ntitled LAc nowledgementsL, L9edicationsL, or LHistor'L, the reCuirement "section *# to !reserve its Title "section $# will t'picall' reCuire changing the actual title. $:. T-RM%.AT%3. Eou ma' not cop', modif', sublicense, or distribute the 9ocument e0cept as e0pressl' provided for under this &icense. An' other attempt to cop', modif', sublicense or distribute the 9ocument is void, and will automaticall' terminate 'our rights under this &icense. However, parties who have received copies, or rights, from 'ou under this &icense will not have their licenses terminated so long as such parties remain in full compliance. $$. F4T4R- R-J%S%3.S 3F TH%S &%C-.SThe Free Software Foundation ma' publish new, revised versions of the +.4 Free 9ocumentation &icense from time to time. Such new versions will be similar in spirit to the present version, but ma' differ in detail to address new problems or concerns. See http7//www.gnu.org/cop'left/. -ach version of the &icense is given a distinguishing version number. %f the 9ocument specifies that a particular numbered version of this &icense Lor an' later versionL applies to it, 'ou have the option of following the terms and conditions either of that specified version or of an' later version that has been published "not as a draft# b' the Free Software Foundation. %f the 9ocument does not specif' a version number of this &icense, 'ou ma' choose an' version ever published "not as a draft# b' the Free Software Foundation.

).$. A99-.94M7 How to use this &icense for 'our documents

To use this &icense in a document 'ou have written, include a cop' of the &icense in the document and put the following cop'right and license notices 8ust after the title page7
Copyright (C) year yo r name. Permission is granted to copy, distrib te and!or modi"y this doc ment nder the terms o" the #$% &ree Doc mentation 'icense, (ersion ).2 or any *ater +ersion p b*ished by the &ree ,o"t-are &o ndation. -ith no /n+ariant ,ections, no &ront0Co+er 1exts, and no 2ac30Co+er 1exts. 4 copy o" the *icense is inc* ded in the section entit*ed \\#$% &ree Doc mentation 'icense>>.

%f 'ou have %nvariant Sections, Front,Cover Te0ts and Gac ,Cover Te0ts, replace the Lwith...Te0ts.L line with this7
-ith the /n+ariant ,ections being *ist their tit*es, -ith the &ront0Co+er 1exts being *ist, and -ith the 2ac30Co+er 1exts being *ist.

%f 'ou have %nvariant Sections without Cover Te0ts, or some other combination of the three, merge those two alternatives to suit the situation. %f 'our document contains nontrivial e0amples of program code, we recommend releasing these e0amples in parallel under 'our choice of free software license, such as the +.4 +eneral !ublic &icense, to permit their use in free software.