doc/install/auth-server

Wifidog Portal installation

Work in progress. More to come : informations, details, tips, debug, screenshots, allouette !

The term Auth-server and portal are used in this guide and mean the same thing.


Requirements

PHP5

  • A working web server with PHP5. Apache httpd server is recommended. Using a virtual host is also a good idea.
  • Needed Extentions : pgsql, dom and mbstring
  • Optional Extentions : xml, gettext, mcrypt, mhash and xmlrpc
  • PEAR Extentions : radius, Auth_RADIUS and Crypt_CHAP
  • Additional PHP library : Smarty, MagpieRSS and Phlickr

It is highly recommended to install optional extentions to activate all features of the portal. If you are not sure which extentions are installed, install.php will detect all of them and display usefull informations to help you. The additional PHP library will be automatiqualy downloaded and installed by install.php (if you want them).

Important Note: The auth server needs more than the default 8Mb of memory that PHP usually assigns. You need to increase this value to 32 or 64 Mb in php.ini. If you don't, install may be successfull, but you'll run into out of memory issues later.

PostgreSQL

A properly configure PostgreSQL server. The install.php script does not apply any special security methods to the Posgresql database server. It is the system administrator's job to grant the right permissions databases access.

Quick Install

  1. Retreive Wifidog Auth-Server sources from CVS (see Download)
  2. In your favorite web browser open  http://server.com/wifidog/install.php and follow instructions to the end.
  3. Set language in config.php
  4. Log in as admin and fill network information, create hotspots and content.

Download the sources

Please go the Download page and follow instructions to retreive the portal sources.

install.php

Introduction

Also install.php is not doing all it might do to help an easy installation (missing language and radius configuration). But it will quickly give you a working portal and you will be able to login as an administrator and customize your network, hotspot, content, users, etc.

Firstly, you need to open install.php in your browser. If you try another portal page and the auth-server was not previously configured, your browser will be redirected automaticaly to install.php (detected by smarty missing files).

http://www.ilesansfil.org/dist/pascal/images/install/01-welcome.png

Follow the instructions on the page to create the wifidog user and database. The command use are at the command line. You can use another way to do this (like  phpPgAdmin)

The first time you open install.php, the script will generate a random password in the file /tmp/dog_cookie.txt. This is only a small security control to disallow remote user to do bad things with fresh auth-server install. The file will will only be the random password, no username are needed.

Version

TODO text

http://www.ilesansfil.org/dist/pascal/images/install/02-version.png

Permission

This page detect missing files or missing write permissions. It will give you tips by generating command line to execute to solve these issue (mkdir and chmod command). The command are only generated to help the user and are not the only issue to solve permissions errors.

The navigation buttons (Back and Next) will be available only if the permissions are ok. Hit the Refresh button to update the page status after you did your changes.

http://www.ilesansfil.org/dist/pascal/images/install/03-permission.png

Smarty

Smarty is needed by the auth-server, you are not allowed to skip this installation ... click Next

http://www.ilesansfil.org/dist/pascal/images/install/04-smarty.png

MagpieRSS

Depending on your needs, MagpieRSS can be installed or not. It's recommended to install it to activate all features of the portal.

http://www.ilesansfil.org/dist/pascal/images/install/05-magpie.png

Phlickr

Depending on your needs, Phlickr can be installed or not. It's recommended to install it to activate all features of the portal.

Database access

A common database error that "hangs" the install.php script is covered at the following link: (near the bottom)

http://dev.wifidog.org/wiki/doc/auth-server/commonErrors

TODO : screenshot + text

  • Fill in informations
  • Test connection

Database initialisation

TODO : screenshot + text

  • Create DB schema
  • Fill in initial DB data
  • Upgrade schema if needed

Options

TODO : screenshot + text

Admin account

TODO : screenshot + text

By clicking Next you will be redirected to your Wifidog portal page.

Debugging

Cleanup

Cleanup needs to be run to "log out" users that haven't otherwise logged out:

either set CONF_USE_CRON_FOR_DB_CLEANUP to false in your config.php, or put this one line script in /etc/cron.hourly

cd <wifidog-auth base directory where config.php is> && su apache -c 'php -f cron/cleanup.php'

or, in crontab

0,5,10,15,20,25,30,35,40,45,50,55 * * * * cd <wifidog-auth base dir where config.php is> && su apache -c 'php -f cron/cleanup.php' > /dev/null 2>&1

or, depending on your cron..

0,5,10,15,20,25,30,35,40,45,50,55 * * * * apache cd <wifidog-auth base dir where config.php is> && php -f cron/cleanup.php > /dev/null 2>&1

you may have to edit this line in cron/cleanup.php from

require_once('../include/common.php');

(that errors for me) to

require_once(dirname(__FILE__).'/../include/common.php');

door number one is definitely the easier one, but i don't like it that every user query that comes in runs cleanup.

the redirect to dev null is cause cleanup.php moans about $_SERVER not being set, and you'll get an email from cron every 5 minutes about that.

Node down time reporting

This is optional. If you want to enable this fonctionnality you need to call it in a crontab, this way:

*/1 * * * * (cd /var/www/wifidog-auth-prod/wifidog/cron/; /usr/local/bin/php -Cq ./page.php 2>/dev/null)

That's calling it every minute. I'm sure we could put the path to the interpreter (/usr/local/bin/php -Cq) at the top of page.php and make it executable for better clarity, and also skip the "cd" (to fix that, we'd need to chdir() into the directory to the script at the top of the program), but such is life, we use it like that for now :)

In case you don't know what it does, it'll email the technical officers after 5,10,15,etc. minutes of downtime. The values at which it'll email are unfortunately hardcoded in the script.


TODO

Information to Add on :

  • Installation debugging (install.php)
  • Postgresql access configuration
  • Google Map
  • DB backup
  • DB optimization
  • PHP tuning ?
  • MySQL ?
  • Auth-server Admin quick configuration (Network name, support email, etc)
  • PHP config file (php.ini) recommended settings