--> About Airconfig:

Airconfig will eventually be a simple MacOSX-esque GUI (for X11) for
configuring your wireless network.

Currently it will only work on Linux, but hopefully support for other
platforms will not be too difficult, as Airconfig uses HAL for device
enumeration, interface up/down, and DHCP start/stop, and wpa_supplicant for
just about all interaction with the wireless device (regardless of the
security method, or lack thereof, employed by the the network).

Airconfig is not complete, but is just starting to become usable.  It is
nowhere near ready for production use, but can be fun to play with.


--> What works:

* Enumerating interfaces and automatically picking wireless interfaces to
  manage.
* Scanning for wireless networks and displaying a list.
* Prompting for a network passphrase/key when a network is selected, based
  on what the network supports.
* Connecting to a network.  This doesn't work all the time and isn't yet
  tolerant of weird failures or driver quirks.
* Connecting to networks with hidden SSIDs (this is not well-tested yet and
  may have problems).
* Saving keys and other information about preferred networks.
* Showing the list of preferred networks.
* Bringing the interface up and down.
* Manually adding, removing, disabling, and editing preferred networks.


--> What doesn't work:

* Reordering the preferred networks list isn't implemented yet.
* Signal quality data is a bit sketchy.  Linux wireless drivers in general
  are to blame for part of this, but Airconfig could probably be a bit
  smarter about figuring out what the card is reporting.
* Airconfig doesn't yet automatically connect to your preferred networks, or
  go down the list trying preferred networks until it finds one that works.
  You have to manually select the network from the list in the menu to
  connect to it.

--> Requirements:

* Glib 2.8.0+
* Gtk+ 2.10.0+
* libexo 0.3.x
* D-Bus 1.0.0+
* dbus-glib 0.72+
* HAL 0.5.7.0+
* ghal 0.1.0+ (avail in SVN only; see http://svn.xfce.org/svn/kelnos/ghal/trunk)
* wpa_supplicant 0.5.7+
* dhclient, dhcpcd 3.0+ (NOT 2.x), or pump
* xfce4-dev-tools (only for building from SVN)

I'll try to relax the glib/gtk+ required versions at some point, if
possible.  Ditto for D-Bus.  But no promises.  wpa_supplicant 0.5.7 is the
first version sporting the new D-Bus control interface (that works, anyway);
nothing earlier will work.

I don't think any distribution enables the wpa_supplicant D-Bus interface
by default; and many probably don't even compile support for it, so you may
need to build it yourself.  You'll need to start wpa_supplicant as root, as a
daemon, and pass it '-u' to tell it to start its D-Bus control interface.  This
command line works for me:

wpa_supplicant -B -P /var/run/wpa_supplicant.pid -u

Make sure there aren't other instances of wpa_supplicant running that may
have been started by your system.

wpa_supplicant also needs its D-Bus configuration file installed to
/etc/dbus-1/system.d/, and usually the system bus daemon will need to be
restarted after doing so.  The wpa_supplicant package contains the config file,
but distributions may not install it.  I've included init scripts for Gentoo
to start and stop wpa_supplicant; if you create init scripts for other distros,
please submit them for inclusion so others may benefit from your work.


--> Security Implications:

All operations that require root access are done via D-Bus services.  Bringing
the interface up or down and starting or stopping DHCP is done using HAL, and
doing network scans, setting up keys, and initiating association, etc. is done
using the wpa_supplicant D-Bus control interface.

The policy in place assumes that the user physically logged in to the console
(i.e., not a user logged in via SSH or through other remote means) is allowed
to do anything he or she wants with the network interfaces.  This policy is
set up through HAL and D-Bus configuration files.  Without this security model,
Airconfig cannot function: there are no provisions for entering root passwords
or using 'sudo'.  If you believe this model is a threat to your system's
security, please do not use Airconfig.


--> Compilation/Installation:

The usual:

./autogen.sh
make
make install

You should also restart the D-Bus system bus daemon and HAL daemon after
installing.

That should get you going, though making and maintaining network connections
is a bit hit-or-miss at this point in time.


--> A Note About HAL:

As of this writing, HAL 0.5.9rc1 does not contain proper support for
automatically updating properties on network interfaces (specifically, the
'net.interface_up' property).  A few brief discussions I've had on the HAL
development mailing list seems to indicate that the developers are not
interested in including this functionality with the official HAL distribution.
I've written a HAL 'addon' that gets installed with Airconfig that takes care
of monitoring network interfaces and updating its own namespaced HAL properties
as needed.  You may need to restart both the D-Bus and HAL daemons after
installing Airconfig, but, otherwise, it should all work automatically.


--> Running:

Simply running 'airconfig' will do the job; there are no command-line options
at present.  If you are running an X11R5-capable session manager, you can have
Airconfig automatically restart itself the next time you log in by saving your
session when you log out.

If you're getting errors on startup, make sure to check the following things:

1.  The D-Bus system daemon is running.
2.  The HAL daemon is running.
3.  My HAL addon is installed and working: check your process list for one or
    more instances of the 'hald-addon-airconfig-net' process.  (There should
    be one instance per network interface.)
4.  The wpa_supplicant D-Bus configuration file is installed to the D-Bus
    system bus config location (usually /etc/dbus-1/system.d/).
5.  The wpa_supplicant daemon is running, and its D-Bus control interface is
    enabled: see the above 'Requirements' section for more information.
6.  If Airconfig claims you have no wireless interfaces, check 'lshal' output
    to see if there are any devices with the 'net.80211' capability.  If not,
    HAL does not recognise your interface as being a wireless interface.
    You'll need to fix that (somehow) before Airconfig will work.


--> Contact:

See http://spuriousinterrupt.org/projects/airconfig for more information.
Bugs may be reported at
http://bugzilla.xfce.org/enter_bug.cgi?format=guided&product=Airconfig

Please do not email me directly with problems.  I get too much email in
general to be able to keep track of specific problem reports.  Please use
Bugzilla if you think you've really found a bug.