SourceForge.net

    1 WiFiAdmin - A Web Interface For Wireless Tools
    2 ==============================================
    3 
    4 Authors:
    5 	Panousis Thanos <panousis@ceid.upatras.gr>
    6 	Dimopoulos Eythimios <dimopule@ceid.upatras.gr> 
    7 ReAuthors:
    8 	Vasilis <basos@users.sf.net>
    9 	Korki	<korki@users.sf.net>
   10 
   11 This program is free software; you can redistribute it and/or modify
   12 it under the terms of the GNU General Public License version 2 as
   13 published by the Free Software Foundation. See COPYING for more
   14 details.
   15 
   16 Wifiadmin is a free php graphical interface to mainly hostap, and
   17 wireless tools in general. Please submit errors
   18 found when running with other linux wireless drivers, that 
   19 support wireless extensions. We are trying so that wifiadmin
   20 is as self-configuring and distribution-independent as possible.
   21 Communication can be established by the mailing list (see http://wifiadmin.sf.net)
   22 
   23 
   24 Prerequisites
   25 =============
   26 
   27 
   28 * WEB SERVER with PHP : An http server with PHP support must also be running. You will also
   29   need the command line interface(CLI) for php. If 'which php' returns
   30   some path, CLI is present in your system.
   31 
   32   Wifiadmin can send emails, in order to confirm new accounts or remind user passwords
   33    You can disable this functionality ($C_send_emails conf variable) 
   34   According to the php manual:
   35    For the Mail functions to be available, PHP must have access to the sendmail binary
   36    on your system during compile time. If you use another mail program, such as qmail
   37    or postfix, be sure to use the appropriate sendmail wrappers that come with them.
   38    PHP will first look for sendmail in your PATH, and then in the following:
   39    /usr/bin:/usr/sbin:/usr/etc:/etc:/usr/ucblib:/usr/lib. It's highly recommended to
   40    have sendmail available from your PATH. Also, the user that compiled PHP must have
   41    permission to access the sendmail binary.
   42   This usually means that if a normal user of your system is able to send emails, then
   43    wifiadmin can do that too.
   44 
   45 *  A (supported) router. Currently a linux one.
   46 
   47 *  (optional but strongly encouraged) Mysql Working Server : WiFiAdmin has a 
   48 	community section, that holds information about conected clients usind a 
   49 	mysql database. You can disable mysql usage ($C_use_mysql conf variable),
   50 	which will disable the community section. Note that if you use mysql, 
   51 	usernames, passwords and user privileges will be saved 	in the database.
   52 
   53 * (optional) RRD-tool : A fairly recent version of RRD-tool must be installed on the system if
   54    you want offline graphics support. You can disable offline graphs ($C_gen_graphs conf var)
   55 
   56 
   57 INSTALLATION [The New automated way ]
   58 ============
   59 
   60 Grab the latest release from http://wifiadmin.sourceforge.net and procceed
   61 with the followning steps:
   62 
   63 1) Decompress in a directory reachable from your web server(htdocs),
   64   keeping in mind the directory structure.
   65 
   66 2) Optional : If you need fully automated proccess you need to  
   67   give write access to the webserver user , to the directory config
   68   For example, from wifiadmin root directory type (assuming apache runs 
   69   as www-data - see FIND APACHE USER below)
   70   # chown www-data: ./config or 
   71   # cd config ; touch routers.ini; chown www-data routers.ini ; touch config.php; chown www-data config.php
   72   If you prefer a safer setup don't grand write access. You will be promted 
   73   to manualy copy the config  file to its place during the installation proccess.
   74 
   75 
   76 3) Point you browser to your.domain/wifiadmin/ or your.ip/wifiadmin/
   77 	If you miss the config.php the installation proccess will be initialized and you will
   78 	be guided to the rest of the proccess.
   79 	Be prepared that some parts of the installation concerning the routers registrarion 
   80 	are done via shell scripts. You will need :
   81 		a) to know web server user for this (See FIND APACHE USER section bellow) as well as 
   82 		b) have shell access to the web server machine as the apache user (but MAY need 
   83 		root access if the apache user account is not setup correctrly)	and finaly 
   84 		c) to know root password of the router machine(s).
   85 	
   86 4) OPTIONAL: If you want offline graphs to be created (network usage,AP users, Signal,etc)  
   87 	see step 5 at the manual installation instractions bellow.
   88 	
   89  SECURITY NOTICE : Procceed to the installation proccess imediately after unpacking. 
   90 	At this early stage *anyone* who can view your webpage can perform the 
   91 	installation. After the proccess user accounds will be created and things 
   92 	will be more secure.
   93 
   94  SECURITY NOTICE: WIFIADMIN HAS A DEFAULT ADMIN PASSWORD. When finishing the installation 
   95   change the admin password as soon as possible, by logging in as user 'admin' with
   96   password 'wifiadmin'. Go to user management, choose 'admin', and  type a different 
   97   password. You can LOOSE complete network access to your box if you are careless enough...
   98 
   99 
  100 UPGRADING
  101 =========
  102 - From 0.1 and on: Just uppack the new version and keep the files under config dir. 
  103    Database update will me managed by the update proccess. Point to wifiadmin location 
  104    and you will be prompted..   Configuration File / Database / Routers update can now
  105    be handled automatically by wifiadmin
  106 - As of 0.1 create_graphs.php cron job is not neccessary.
  107 - If you are installing a version greater than 0.0.3 change your sudo configuration.
  108 
  109 
  110   SECURITY NOTICE : Point your browser to the wifiadmin location imediately after update. 
  111 		It could be possible that unpriviledged users may perform actions.
  112 
  113 
  114 FIND APACHE USER
  115 ================
  116  You can find out the user that apache runs with, by:
  117   #ps aux | grep http   or   
  118   #ps aux | grep apache 
  119   
  120 Notice : it might show lots of apache proccesses and one of the running as root. This is the "father" apache 
  121 	proccess and  should be ignored
  122   e.g
  123  #ps uax | grep apache
  124 root     17159  0.0  0.0  25632    84 ?        Ss   Jun15   0:16 /usr/sbin/apache2 -k start
  125 www-data 17164  0.0  1.6  29244  8424 ?        S    Jun15   0:55 /usr/sbin/apache2 -k start
  126 www-data 17165  0.0  1.8  30236  9412 ?        S    Jun15   0:28 /usr/sbin/apache2 -k start
  127 www-data 17411  0.0  1.3  26108  6860 ?        S    Jun15   0:43 /usr/sbin/apache2 -k start
  128 
  129 Or you should look for "User" directive in apache configuration file (e.g. /etc/apache2/apache2.conf)
  130 	e.g.
  131 	User www-data
  132 	Group www-data
  133 
  134 NOTES
  135 =====
  136 
  137 --- Users / Privileges
  138 Wifiadmin supports users with different priviledges. You can create
  139 different classes of users. A non-logged in user, defaults to the
  140 'guest' user. You can change the amount of information guest and every
  141 other user can access by assigning privileges. Most privileges
  142 are self explaining. But here are some notes :
  143 - "Edit Privileges" is synonym to the *admin* as he or she can change every
  144 other privilege. Be aware to who you are giving edit_privileges. By design,
  145 you cannot get locked out of the system by deleting the last user that has 
  146 an edit-privileges priviledge.
  147 - "View status Ext" gives more view only capabilities. Right now it offers 
  148 real time graphs as someone could preform a denial of service by modifying 
  149 some values in the graph scripts (asking for tons of graph data).
  150 
  151 -- Supported Drivers
  152 At linux any wireless extentions enabled driver should be working fairly good.
  153 But note that currently the known supported drivers for AP management are hostap 
  154 and madwifi.Also hostap is enjoying some special feautures with AP Access Control 
  155 as they are offered by this driver only. 
  156 If you have tested other drivers or want to contib AP specific code you can post 
  157 at the mailing list (see http://wifiadmin.sf.net)
  158 
  159 -- Supported Systems 
  160 Wifiadmin intents to become multi pratform (mainly for other *X systems which miss linux
  161 stuff like wireless extentions). Right now the abstaction API has been created for linux.
  162 And this is the only supported platform.
  163 If you have programming skills and would like to see your device supported you can contrib
  164 code. Communication can be established by the mailing list (see http://wifiadmin.sf.net)
  165 
  166 -- Locale independent
  167 Wifiadmin intents to learn foreign languages. If you want you can contrib a full translation
  168 of the language specific strings. All the content should be in one (big) file under lang directory.
  169 You can base your translation on en_GB.php (which is the default locale). 
  170 
  171 -- Reboot unaware settings
  172 Right now changes that are made to the device parameters are not saved in the system and thus 
  173 are lost on router reboot. Wifiadmin intents to change this behaivour at some point and 
  174 obtain some memmory. Contributions and ideas are welcome.
  175 
  176 --- Banning MACs
  177 You can ban a MAC, through the wireless status page.
  178 You can unban MACs, view and alter Access Control policies in wireless
  179 security page. Note that banning a MAC on an open-policy AP will result
  180 in a deny policy. 
  181 
  182 --- Manual Configuration
  183 Things can be manually configured in the config/config.php file. The 
  184 variables are marked by comments. Change them at your own risk. You can
  185 also point your browser to your.domain/wifiadmin/install.php?mode=config
  186 at any time. Instractions on how to change conf variables in a secure way
  187 thru the graphical gui will guide you.
  188 
  189 --- RRD
  190 Wifiadmin makes use of round robin dbs, and we take for granted that you have a
  191 recent version of rrd-tool. You can also disable graphs generation and to rrdtool
  192 will be needed then.
  193 
  194 
  195 Installation [ The Old Manual way]
  196 ============
  197 
  198 Grab the latest release from http://sourceforge.net and procceed
  199 with the followning steps:
  200 
  201 1) Decompress in a directory reachable from your web server(htdocs),
  202   keeping in mind the directory structure.
  203 
  204 2) If you disable mysql usage($C_use_mysql variable in the config/config.php
  205   file):
  206   
  207   Give write access to the user that you are running PHP, to the file
  208   config/passwd .For example, from wifiadmin root directory type
  209   'chown apache:/ config; chown apache:/ config/passwd', depending
  210   on your local configuration.
  211   
  212   If you enable mysql usage:
  213   
  214   Within the directory, you'll find a a file named "mysql.sql". 
  215   Contained in this file are the SQL statements necessary to create the 
  216   WiFiAdmin database. Log onto your database server under the root account (or 
  217   other account allowed to create databases), create a database for wifiadmin, and
  218   then run the contents of mysql.sql to create the tables and initial data.
  219   
  220   For example:
  221 
  222   mysqladmin -u [user] -p create [database-name]
  223   mysql -u [user] -p [database-name] < mysql.sql
  224   
  225   Or you can use phpMyAdmin to do the same.
  226   
  227   In either case, you have to edit the config/config.php file and edit the
  228   following variables:
  229   
  230   $C_USERS_DBHOST = "localhost";       host where mysql is running
  231   $C_USERS_DB = "wifiadmin";           [database-name]
  232   $C_USERS_DBUSER = "wifiadmin";	     [user] 
  233   $C_USERS_DBPASS = "wifiadmin";       the password of [user]
  234   
  235 3)  Setup the registered routers. Wifiadmin has the capability to manage many (remote)
  236     routers. Of course you can still manage the server machine. We call this procedure 
  237     "to register a router with the server".It may come handy when you try to have a 
  238     "bare" router (with no resudant services) and run your web server (where wifiadmin runs) 
  239     on a different machine.
  240 
  241     Now assume that we have router.domain.com as remote router (R) and apache server with 
  242         wifiadmin installed as server.otherdomain.com (S). Also "remoteuser" is the user that 
  243   	wifiadmin will connect to R and "apache_user" is the user name (e.g. www-data)	that 
  244 	apache runs as in S (see FIND APACHE USER section above). In order to work you need to 
  245 	perform the following :
  246 	a)   At step 4 give sudo access to remoteuser at R (instead of apache_user at S)
  247 	b) 	 Right now only ssh access is supported for remote routers. So set up your 
  248 		 router R to accept connections from apahce_user@server.otherdomain.com as 
  249 		 user remoteuser@router.domain.com without password. More on this at 
  250 		 SSH_NOPASSWD supplied text file
  251 	c)	Set up the ini routers file config/routers.ini. It should have the following format
  252 		[router_name]
  253 			url = router.domain.com
  254 			username = remoteuser
  255 			access_mode = ssh
  256 			system_flavor = linux
  257 			description = optional descriptive text
  258 
  259 	SECURITY NOTICE: Having in mind the strength of ssh the security risks are the same
  260 	as without ssh with the difference that they have to compomise your server S to gain 
  261 	sudo root access at router R but they can't break into the router directly.
  262 
  263 
  264 4) Change your sudo configuration.
  265   Wifiadmin needs superuser access to *specific* executables. For the moment,
  266   this is done by giving superuser access to the user apache runs with on the local machine
  267   or remoter user on remote routers, using the sudo mechanism (need to have sudo installed). 
  268   You can find out the user that apache runs with, by:
  269   
  270   ps aux | grep http   or   ps aux | grep apache
  271   
  272   You should use the visudo executable, or manually edit the file 'sudoers'.
  273   Add the following lines, replace www-data with the user apache runs with.
  274   
  275   # Cmnd alias specification
  276   Cmnd_Alias      WIFIADMIN = /sbin/iwconfig, /sbin/ifconfig, /sbin/iwlist,
  277   /sbin/iwpriv,  /sbin/route, /usr/bin/host, /usr/sbin/arp
  278 
  279   # User privilege specification
  280   www-data ALL=(ALL) NOPASSWD: WIFIADMIN
  281 
  282   Change the paths if iwconfig, ifconfig etc executables are located
  283   elsewhere in your system.
  284   
  285   *** You need to repeat the above procedure for every (remote) router ***
  286 
  287   SECURITY NOTICE:  This configuration, gives superuser priviledges for the specific commands 
  288   to the user your  web server runs with at local or *remote* machines. This might have 
  289   implications on system security. E.g. try to keep your web server and yout hole system secure. 
  290 
  291 5) OPTIONAL: If you want offline graphs to be created (network usage,AP users, Signal,etc)
  292 	you can use the crontab -e command as the apache user and add the following line at 
  293 	the end of your crontab 
  294 */4 * * * *  php /path/to/wifiadmin/create-update-rrds.php > /dev/null 2>&1	
  295 	
  296 	or you can add the following by manually editing the systemwide /etc/crontab if for any
  297 	reason you can not setup the apache user crontab (e.g. not permitted by your sysadmin)
  298 */4 * * * *  www-data php /path/to/wifiadmin/create-update-rrds.php > /dev/null 2>&1
  299 	where we assume that apache runs as www-data user. (See FIND APACHE USER above)
  300   
  301   This creates(once) and updates the rrd databases.  RRD updates happen every 4 minutes.
  302   Change the value to suit your needs. Mind space characters from copy-pasting into your crontab!!
  303   
  304   Also make sure $C_gen_graphs is set to true (in config/config.php). In other case set to false.
  305 	Default is disabled.
  306 	
  307   Finally make sure the rrd_database and graphs directory as specified at the config/config.php	
  308   are readable and writable by the webserver user.
  309 	
  310 
  311 6) Wifiadmin can send emails to confirm new user accounts, or remind user passwords.
  312   If $C_send_emails = true; in config.php file, wifiadmin will send emails.
  313   If you set $C_confirm_new_account = false; while $C_send_emails = true;, wifiamdin will
  314   send emails to remind passwords, but no email confirmation will be needed in order
  315   to set up an account.
  316 
  317    
  318 7) Fire up your favorite browser, and point to
  319   'http://target-hostname/wifiadmin/'
  320 
  321   SECURITY NOTICE: WIFIADMIN HAS A DEFAULT ADMIN PASSWORD. Change the admin
  322   password as soon as possible, by logging in as user 'admin' with
  323   password 'wifiadmin'. Go to user management, choose 'admin', and 
  324   type a different password. You can LOOSE complete network access
  325   to your box if you are careless enough...
  326 
  327 7) Enjoy :)
  328 
  329