docs/README

   1 WiFi Radar
   2 --------------------------------------------------------------------------------
   3
   4     Maintained by Sean Robinson <seankrobinson@gmail.com>
   5
   6     Created by Ahmad Baitalmal <ahmad@baitalmal.com>
   7     Previously maintained by Brian Elliott Finley <brian@thefinleys.com>
   8
   9     http://wifi-radar.berlios.de/
  10
  11     WiFi Radar is released under the GPL license.
  12
  13
  14 Quick Usage
  15 --------------------------------------------------------------------------------
  16
  17     To show the GUI and manage profiles:
  18
  19         sudo wifi-radar
  20
  21
  22 Nifty Config Tip for Ubuntu and Debian Based Distributions
  23 --------------------------------------------------------------------------------
  24
  25     After initial configuration of your preferred wifi networks by
  26     runing the wifi-radar GUI, you can automatically invoke wifi-radar
  27     as part of your systems standard ifup/ifdown proceedures.
  28
  29     Find a stanza in /etc/network/interfaces for your wifi device (or
  30     create one), and modify it so that it looks like this example:
  31
  32     auto eth1
  33     iface eth1 inet static
  34         address 0.0.0.1
  35         netmask 255.255.255.0
  36         post-up wifi-radar -d
  37
  38     When you or your system does an "ifup eth1", this stanza will set a
  39     temporary static IP address (that should not conflict with
  40     anything), then invoke wifi-radar in daemon mode which will connect
  41     to a preferred wifi network and configure your interface
  42     accordingly, with an IP address appropriate for that network.
  43
  44
  45
  46 I. Here are Some Important Bits:
  47 --------------------------------------------------------------------------------
  48
  49     * The config file defaults to /etc/wifi-radar/wifi-radar.conf.  The
  50       location of this file can be changed at install time with
  51       something like:
  52
  53         "make install sysconfdir=/etc/wifi-radar"
  54
  55     * If the conf file does not exist, it will be created at run-time, so you must
  56       always invoke wifi-radar as root or with sudo.
  57
  58     * You can change everything else from the conf file which is simply
  59       a .ini style file.
  60
  61     If you have questions, check the WiFi Radar web site at
  62     http://wifi-radar.berlios.de/ for a FAQ, a mailing list, and a web forum.
  63     Any of which may have your answer.
  64
  65
  66 II. Dependencies
  67 --------------------------------------------------------------------------------
  68
  69     * Python
  70     * pygtk2
  71     * Wireless Tools for Linux (iwconfig, iwlist)
  72     * SpeechD (optional)
  73
  74
  75 III. Install
  76 --------------------------------------------------------------------------------
  77
  78     1. Type "sudo make install"
  79        (or "sudo make install sysconfdir=/etc/wifi-radar")
  80
  81
  82 IV. HOWTO: Optional PAM Configuration
  83 --------------------------------------------------------------------------------
  84
  85     These instructions allow you to run wifi-radar as a normal user
  86     without using sudo.  Thanks to Flipp Bunts <flipp.bunts@gmail.com>
  87     for this HOWTO.
  88
  89     HOWTO get wifi-radar custom launcher to use PAM authentication in
  90     Gnome:
  91         1. get wifi-radar and untar
  92         2. put wifi-radar.svg in /usr/share/pixmaps
  93         3. put wifi-radar.py in /usr/local/bin
  94         4. ln -s /usr/bin/consolehelper /usr/local/bin/wifi-radar
  95         5. vi /etc/security/console.apps/wifi-radar
  96                 USER=root
  97                 PROGRAM=/usr/local/bin/wifi-radar.py
  98                 SESSION=true
  99         6. vi /etc/pam.d/wifi-radar
 100                 #%PAM-1.0
 101                 auth       sufficient   pam_rootok.so
 102                 auth       sufficient   pam_timestamp.so
 103                 auth       required     pam_stack.so service=system-auth
 104                 session    required     pam_permit.so
 105                 session    optional     pam_xauth.so
 106                 session    optional     pam_timestamp.so
 107                 account    required     pam_permit.so
 108         7. check the permissions
 109                 # ls -lh /etc/security/console.apps/wifi-radar /etc/pam.d/wifi-radar
 110                 -rw-r--r--  1 root root  /etc/pam.d/wifi-radar
 111                 -rw-r--r--  1 root root  /etc/security/console.apps/wifi-radar
 112         8. add launcher
 113                 a. right click on panel
 114                 b. select 'add to panel'
 115                 c. click on 'custom application launcher'
 116                 d. options for 'create launcher'
 117                 name : wifi-radar
 118                 command : /usr/local/bin/wifi-radar
 119                 icon : /usr/share/pixmap/wifi-radar.svg
 120         9. click on the icon, enter the root password, away you go
 121
 122
 123 V. HOWTO: Environment Variables Set For Connect and Disconnect Scripts
 124 --------------------------------------------------------------------------------
 125
 126     The following environment variables are set for the pre- and post-
 127     scipts for connect and disconnect operations (i.e. all four user scripts):
 128
 129         1. WIFIRADAR_IF is the network interface which is dis/connecting
 130
 131     The following variables are set in the shell environment in
 132     which the post-connect and pre-disconnect scripts are executed.
 133
 134         1. WIFIRADAR_IP is the current IP address
 135         2. WIFIRADAR_ESSID is the current ESSID
 136         3. WIFIRADAR_BSSID is the current BSSID
 137
 138
 139 VI. HOWTO: Interpolated Strings in the Configuration File
 140 --------------------------------------------------------------------------------
 141
 142     It is possible to use configuration file options in the value of other
 143     options. An example:
 144
 145         [DEFAULT]
 146         interface = wlan1
 147
 148         [DHCP]
 149         pidfile = /etc/dhcpc/dhcpcd-%(interface)s.pid
 150
 151     means that WiFi Radar will use the file /etc/dhcpc/dhcpcd-wlan1.pid for
 152     the DHCP PID file.
 153
 154     These interpolated strings can be safely entered into preferences dialog text
 155     areas.
 156
 157
 158 Have fun!
 159
 160
 161