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.tuxfamily.org
  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.tuxfamily.org for a FAQ, a mailing
  68     list, and a user manual.  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
  78
  79 III. Install
  80 --------------------------------------------------------------------------------
  81
  82     1. Type "sudo make install"
  83        (or "sudo make install sysconfdir=/usr/local/etc/wifi-radar")
  84
  85
  86 IV. HOWTO: Optional PAM Configuration
  87 --------------------------------------------------------------------------------
  88
  89     These instructions allow you to run wifi-radar as a normal user
  90     without using sudo.  Thanks to Flipp Bunts <flipp.bunts@gmail.com>
  91     for this HOWTO.
  92
  93     HOWTO get wifi-radar custom launcher to use PAM authentication in
  94     Gnome:
  95         1. get wifi-radar and untar
  96         2. put wifi-radar.svg in /usr/share/pixmaps
  97         3. put wifi-radar.py in /usr/local/bin
  98         4. ln -s /usr/bin/consolehelper /usr/local/bin/wifi-radar
  99         5. vi /etc/security/console.apps/wifi-radar
 100                 USER=root
 101                 PROGRAM=/usr/local/bin/wifi-radar.py
 102                 SESSION=true
 103         6. vi /etc/pam.d/wifi-radar
 104                 #%PAM-1.0
 105                 auth       sufficient   pam_rootok.so
 106                 auth       sufficient   pam_timestamp.so
 107                 auth       required     pam_stack.so service=system-auth
 108                 session    required     pam_permit.so
 109                 session    optional     pam_xauth.so
 110                 session    optional     pam_timestamp.so
 111                 account    required     pam_permit.so
 112         7. check the permissions
 113                 # ls -lh /etc/security/console.apps/wifi-radar /etc/pam.d/wifi-radar
 114                 -rw-r--r--  1 root root  /etc/pam.d/wifi-radar
 115                 -rw-r--r--  1 root root  /etc/security/console.apps/wifi-radar
 116         8. add launcher
 117                 a. right click on panel
 118                 b. select 'add to panel'
 119                 c. click on 'custom application launcher'
 120                 d. options for 'create launcher'
 121                 name : wifi-radar
 122                 command : /usr/local/bin/wifi-radar
 123                 icon : /usr/share/pixmap/wifi-radar.svg
 124         9. click on the icon, enter the root password, away you go
 125
 126
 127 V. HOWTO: Environment Variables Set For Connect and Disconnect Scripts
 128 --------------------------------------------------------------------------------
 129
 130     The following environment variables are set for the pre- and post-
 131     scipts for connect and disconnect operations (i.e. all four user scripts):
 132
 133         1. WIFIRADAR_IF is the network interface which is dis/connecting
 134
 135     The following variables are set in the shell environment in
 136     which the post-connect and pre-disconnect scripts are executed.
 137
 138         1. WIFIRADAR_IP is the current IP address
 139         2. WIFIRADAR_ESSID is the current ESSID
 140         3. WIFIRADAR_BSSID is the current BSSID
 141
 142
 143 VI. HOWTO: Interpolated Strings in the Configuration File
 144 --------------------------------------------------------------------------------
 145
 146     It is possible to use configuration file options in the value of other
 147     options. An example:
 148
 149         [DEFAULT]
 150         interface = wlan1
 151
 152         [DHCP]
 153         pidfile = /etc/dhcpc/dhcpcd-%(interface)s.pid
 154
 155     means that WiFi Radar will use the file /etc/dhcpc/dhcpcd-wlan1.pid for
 156     the DHCP PID file.
 157
 158     These interpolated strings can be safely entered into preferences dialog text
 159     areas.
 160
 161
 162 Have fun!
 163
 164
 165