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 <robinson@tuxfamily.org>
   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 I. Here are Some Important Bits:
  26 --------------------------------------------------------------------------------
  27
  28     * The config file defaults to /etc/wifi-radar/wifi-radar.conf.  The
  29       location of this file can be changed at install time with:
  30
  31         "make install sysconfdir=/usr/local/etc/wifi-radar"
  32
  33     * The configuration file format changed between v1.9.9 and v2.0.s01.
  34       The two formats are not compatible with each other.  If you are
  35       upgrading from v1.9.9, you will need to re-create your configuration.
  36
  37     * If the config file does not exist, it will be created at run-time,
  38       so you must always invoke wifi-radar as root or with sudo.
  39
  40     * You can change everything else from the config file which is simply
  41       a .ini-style file.
  42
  43     If you have questions, check the WiFi Radar web site at
  44     http://wifi-radar.tuxfamily.org for a FAQ, a mailing
  45     list, and a user manual.  Any of which may have your answer.
  46
  47
  48 II. Dependencies
  49 --------------------------------------------------------------------------------
  50
  51     * Python
  52     * PyGtk2
  53     * Wireless Tools for Linux (iwconfig, iwlist)
  54
  55
  56 III. Install
  57 --------------------------------------------------------------------------------
  58
  59     1. Type "sudo make install"
  60        (or "sudo make install sysconfdir=/usr/local/etc/wifi-radar")
  61
  62
  63 IV. HOWTO: Optional PAM Configuration
  64 --------------------------------------------------------------------------------
  65
  66     These instructions allow you to run wifi-radar as a normal user
  67     without using sudo.  Thanks to Flipp Bunts <flipp.bunts@gmail.com>
  68     for this HOWTO.
  69
  70     HOWTO get wifi-radar custom launcher to use PAM authentication in
  71     Gnome:
  72         1. get wifi-radar and untar
  73         2. put wifi-radar.svg in /usr/share/pixmaps
  74         3. put wifi-radar.py in /usr/local/bin
  75         4. ln -s /usr/bin/consolehelper /usr/local/bin/wifi-radar
  76         5. vi /etc/security/console.apps/wifi-radar
  77                 USER=root
  78                 PROGRAM=/usr/local/bin/wifi-radar.py
  79                 SESSION=true
  80         6. vi /etc/pam.d/wifi-radar
  81                 #%PAM-1.0
  82                 auth       sufficient   pam_rootok.so
  83                 auth       sufficient   pam_timestamp.so
  84                 auth       required     pam_stack.so service=system-auth
  85                 session    required     pam_permit.so
  86                 session    optional     pam_xauth.so
  87                 session    optional     pam_timestamp.so
  88                 account    required     pam_permit.so
  89         7. check the permissions
  90                 # ls -lh /etc/security/console.apps/wifi-radar /etc/pam.d/wifi-radar
  91                 -rw-r--r--  1 root root  /etc/pam.d/wifi-radar
  92                 -rw-r--r--  1 root root  /etc/security/console.apps/wifi-radar
  93         8. add launcher
  94                 a. right click on panel
  95                 b. select 'add to panel'
  96                 c. click on 'custom application launcher'
  97                 d. options for 'create launcher'
  98                 name : wifi-radar
  99                 command : /usr/local/bin/wifi-radar
 100                 icon : /usr/share/pixmap/wifi-radar.svg
 101         9. click on the icon, enter the root password, away you go
 102
 103
 104 V. HOWTO: Environment Variables Set For Connect and Disconnect Scripts
 105 --------------------------------------------------------------------------------
 106
 107     The following environment variables are set for the pre- and post-
 108     scipts for connect and disconnect operations (i.e. all four user scripts):
 109
 110         1. WIFIRADAR_IF is the network interface which is dis/connecting
 111
 112     The following variables are set in the shell environment in
 113     which the post-connect and pre-disconnect scripts are executed.
 114
 115         1. WIFIRADAR_IP is the current IP address
 116         2. WIFIRADAR_ESSID is the current ESSID
 117         3. WIFIRADAR_BSSID is the current BSSID
 118
 119
 120 VI. HOWTO: Interpolated Strings in the Configuration File
 121 --------------------------------------------------------------------------------
 122
 123     It is possible to use configuration file options in the value of other
 124     options. An example:
 125
 126         [DEFAULT]
 127         interface = wlan1
 128
 129         [DHCP]
 130         pidfile = /etc/dhcpc/dhcpcd-%(interface)s.pid
 131
 132     means that WiFi Radar will use the file /etc/dhcpc/dhcpcd-wlan1.pid for
 133     the DHCP PID file.
 134
 135     These interpolated strings can be safely entered into preferences dialog text
 136     areas.
 137
 138
 139 Have fun!