docs/README

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