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