Wifisetup main page



This is the manual for wifisetup. It can be found in /usr/local/share/doc/wifisetup/readme


Q: What is wifisetup?
A: Wifisetup is a script to configure your wifi card for various networks. it
   was written to consolidate the various tools necessary to manually configure
   a wifi card to connect to a network.


Wifisetup is meant to be modular. You can place various scripts to run to help
configuring a wifi network in /usr/local/lib/wifisetup/modules. The name of the
script is the module name used in configuration files. When a module is called,
it is passed the name of the network as the first parameter, and the user's
home directory (where to find the config file) as the second parameter. These
modules can be binaries or scripts, as long as they're executable. At it's base,
wifisetup can configure networks with static and dhcp addresses, and any other
functionality that the iwconfig program provides. Wifisetup is packaged with a
wpa module capable of authenticating against wpa-protected networks. This module
requires wpa_supplicant to be installed.


Wifisetup works by configuring various networks and giving them canonical
names such as "work" "school" or "home". These configuration files are
stored in the users' home directory under the folder ".wifisetup".
The directory structure that wifisetup expects is:


There should be ~/.wifisetup/module/ folders for every installed
module. For example: "~/.wifisetup/module/wpa". There are three different types
of files, under their appropriate directories in ~/.wifisetup. "config" files
are required. Every network needs one of these at a minimum. "script" files are
executed after the connection is made (for instance, to mount a network file
system).  Finally, "module" config files are passed to the module scripts.

Every file for a network configuration has the same name, and each file is
placed in it's particular directory. For instance, for a configuration for a
network where the cannonical name is for "foo", it's posible files are (under
~/.wifisetup) config/foo, script/foo, module//foo. This is how
all of the config files for particular networks are linked together.

There are examples of network setups in /usr/local/share/doc/wifisetup. Every
option in a config file is in the format of option="value". Options with a "*"
are always required, options with a "+" are conditionally required.

"config" file options:

iface: *
        Examples: "wlan0" "eth1" or similar
        This is the interface to configure. It is always required.

ssid: *
        This is the network name to associate with. This is required. The
        configuration may work under certain conditions without the ssid
        provided, but is almost always required.

iw_options: +
        Example: "mode managed essid foo channel 11 enc off"
        Conditionally required: either this or options for a module necessary
                to associate with an AP (access point)
        These are the options passed directly to iwconfig (minus the interface).
        Refer to the iwconfig manual for help. This is required for unencrypted
        networks or WEP encrypted networks. In theory the wpa module can also be
        used for WEP networks, but iwconfig is the preferred method as of now.

proto: *
        Possible Options: "dhcp" or "static"
        This defines the type of IP addressing to use. If your device should be
        automatically configured via dhcp, then specify so here. Otherwise
        specify static here.

if_options: +
        Example: " netmask"
        Conditionally required: This is required if "static" is specified as the
        These options are passed directly to ifconfig (minus the interface name)
        Refer to the ifconfig manual for help.

gateway: +
        Example: ""
        Conditionally required: This is required if "static" is specified as the
        This is set up as the default gateway.

dns1: +
        Example: ""
        Conditinally required: This is required if "static" is specified as the
        This is dumped into /etc/resolv.conf to resolve domain names.

module: +
        Example: "wpa"
        Conditonally required: This is required if iw_options is not to be
                used/specified. This specifies the module to execute.