wicd/README

THEORY OF OPERATION:

Wicd is designed to give the user as much control over the behavior of network connections
as possible.  Every network, both wired and wireless, has its own profile, with its own
configuration options and connection behavior.  Wicd will try to automatically connect
only to the networks the user specifies it should try, with a preference first to a wired
network, then to wireless.

For wired connections, users have several options for determining what network settings to
use.  Wicd allows creation of an unlimited amount of wired profiles, which each have
their own unique settings.  The user can choose to automatically connect to a selected
default profile, choose a profile from a pop-up window every time wicd connects, or
have wicd automatically choose the last profile used to manually connect.

For wireless networks, users can select any number of wireless networks to automatically
connect to, from which wicd will choose the one with the highest signal strength to try
to connect.

If the user chooses, wicd will try to automatically reconnect when wicd detects a
connection is lost.  If the last known connection state is wired, wicd will try
to first reconnect to the wired network, and if it is not available, will try
any available wireless networks with automatic connection enabled.  If the last
known connection state is wireless, wicd will first try to reconnect to the
last network it was connected to (even if it not set to automatically connect
to that network normally), and should that fail will try both a wired connection
and any available wireless networks set to automatically connect.

Wicd uses built-in linux wireless-tools, such as ifconfig and iwconfig, to
get and configure network info.  There is some flexibility in its use of DHCP,
providing support for dhclient, dhcpcd, and pump.  Wicd uses wpa_supplicant
to handle all wireless encryption settings, and uses a template-based system
to create the configuration files wpa_supplicant uses.  These templates can
be editted and new templates can be created and imported into wicd by the user,
allowing connection to networks with uncommon encryption settings.



STRUCTURE:

There are two major parts to wicd; the daemon, which runs at the root level, and the
user-interface, which runs at the user level.  The two parts run as separate processes,
and make use of D-Bus to communicate.

The daemon is responsible for making and configuring connections, reading/writing 
configuration files and logs, and monitoring the connection status.  The daemon's job 
is split between two processes, daemon.py and monitor.py.  All the connection status 
monitoring, as well as the auto-reconnection logic, takes place in monitor.py.  
Everthing else is done by daemon.py.

The user-interface (stored in wicd.py), made up of a tray icon, main GUI window, and its child dialogs, 
gets configuration and network information from the daemon by either querying it, using 
the methods in the daemon's dbus interface, or by receiving signals emitted from the daemon 
over D-Bus.  Any configuration changes made in the UI are passed back to the daemon, which
actually applies the changes and writes them to configuration files.

Since the GUI just queries for connection and configuration information from the daemon
it is possible to run wicd without the GUI at all.  Additionally, the daemon is started by
wicd's init script as soon as Linux loads, and before any user logs in, making it possible to 
use with "headless" machines.