.. default-role:: literal Autonet documentation ===================== .. contents:: Contents :local: What is autonet ? ----------------- Autonet is a quick and dirty alternative to `Network Manager`_. It is a wrapper around `wpa_supplicant`_ to automate the process of connecting to your favorite networks, while trying to be robust and customizable. .. _Network Manager: http://projects.gnome.org/NetworkManager/ .. _wpa_supplicant: http://hostap.epitest.fi/wpa_supplicant/ Why not Network Manager ? ------------------------- I tried Network Manager in 2008. At the time, I found that it had too many dependencies, and I found it hard to install on my Fluxbox_ desktop. Last but not least, I did not find any command-line interface to Network Manager, which I didn't like because that leaves me too dependent on a working X environment. There were also other details, like being forced to use the gnome keyring to remember passwords. Maybe some of those problems have been fixed by now, maybe I just didn't do things the right way, but the fact is that I thought networking should be easier and I wrote autonet. I am now sharing it with everybody looking for an alternative to Network Manager. .. _Fluxbox: http://www.fluxbox.org/ Goals ----- I wanted to use a simple configuration file system for everything, including my passwords. This is a security risk, but is the only way if you want to have everything automated. I wanted the system to work with my favorite networks. That meant * Automatically try to connect using DHCP when an ethernet cable is plugged-in, favoring it over any wireless connection. * Automatically connect to my home WEP wireless network * Automatically connect to my university wireless networks: * Automatically connect to the WPA network * If that fails, connect to the unsecured network and use the VPN client vpnc_ * Automatically connect to some wireless hotspots: * Some wireless hotspot can only be accessed if I use the vpn to connect through my university. Furthermore, I wanted the system to re-connect as soon as connectivity is lost. I also wanted to be able to run custom connection/deconnection scripts. .. _vpnc: http://www.unix-ag.uni-kl.de/~massar/vpnc/ Overview -------- Autonet is started at boot by a simple rc script. It immediately tries to connect to wired or wireless networks and stay running in the background no matter what. Once connected to a network, autonet will test if still connected at regular intervals, and disconnect and re-connect if not connected anymore. For each possible network, a connect, disconnect and connection test command must be specified. Autonet will use those to do its job. Packaging --------- Autonet is packaged in the `autonet` package. My configuration is in `autonet-config`. A more in depth explaination ---------------------------- Autonet works with objects called interface. An interface is something that can be brought up or down using the ``ifconfig`` command. For example, ``eth0`` is usually the name for the first ethernet interface, whereas ``wlan0`` is usually the name for the first wireless interface. Usually a laptop will only have those two, but autonet can work with any number of interface. With some interface, like ``eth0``, one cannot normally choose a network on which to connect to, whereas for others, like ``wlan0``, one has to choose some network and connect to it. Autonet makes the distinction between the two, calling them wired and wireless respectively. Autonet maintains a list of preferred wired and wireless interface. If more than one interface can be used to connect to the internet, it will use the one whose position is the highest in that list. Autonet will always prefer wired interface to wireless ones. Autonoet tries to connect immediately if an ethernet cable is plugged in. In case the wireless interface can be used, autonet will start ``wpa_supplicant`` and wait for it to send a signal saying it managed to connect to one of the user's favorite network. Autonet will then do the rest. Everytime an interface is brougt up or down, some custom scripts are run. Autonet tools ------------- For a user, there is not much that can be done to interact with autonet. The only things that can be done is to check its status, using the ``autonet-status`` command. If you need more information on what it is doing, you can try looking at autonet's log file, using:: $ tail -f /var/log/autonet.log If you want to connect to a wireless network that is not in your favorite list, you can use ``wpa_gui``, or any other tool communicating with ``wpa_supplicant``, and connect to the network you need. Autonet will then automatically do the rest and you should be able to get an IP. Configuring autonet ------------------- First of all, you should make sure that the autonet rc script is started at boot. Furthermore, if you want to use a wired interface you should also make sure ``ifplugd`` is started. Autonet keeps all its configuration files in a ``/etc/autonet`` directory, that should have been created at installation time. You should create several files there: * ``autonet.conf``, a global file containing very general settings * ``$interfacename.conf``, the interface-specific configuration file * ``$interfacename.$networkname.conf``, a network-specific configuration file, it case you are not satisfied by the default in ``$interfacename.conf``. `$networkname` is the name indicated in the network's `id_str` field in the `wpa_supplicant` configuration file. * ``wpa_supplicant-$interfacename.conf``, the ``wpa_supplicant`` configuration file for the ``$interfacename`` interface You can also put other files, like scripts you would like to use with autonet. The format of the ``.conf`` files is always the same: the shell-style format, i.e one variable declaration per line using the format ``VARIABLE_NAME= VARIABLE_VALUE``, lines starting with ``#`` are ignored (comments). For example, a short configuration file would be:: # Just a test MY_TEST_VARIABLE=1 The global configuration file ############################# This is where you give your interface preferrence list, and the scripts you would like to run when an interface is brought up or down. Here is the complete list of variables. LOG_FILE ******** Specify the path to autonet's log file CONNECTION_TEST_INTERVAL ************************ Number of seconds between each connectivity test FIRST_CONNECTION_TEST_INTERVAL ****************************** Number of seconds between the connection to a network, and the first connectivity test RECONNECT_INTERVAL ****************** Number of seconds to wait between disconnection and reconnection PREFERRED_WIRELESS ****************** An array listing your favorite wireless interfaces, preferred one first. The list should be written between parentheses, and the items should be separated by spaces. For example:: PREFERED_WIRELESS=(ra0 wlan0 eth1) If you do not want to use any wireless interface, put in ``()`` PREFERRED_WIRED *************** An array listing your favorite wired interface. It has the same format as `PREFERRED_WIRELESS`_ WIRELESS_WHEN_UNPLUGGED *********************** Set this to ``true`` is you want to automatically connect to a wireless network if no wired interface is available. Set this to ``false`` otherwise. WIRELESS_PREUP ************** Command that is run before bringing up a wireless interface. ``WIRED_PREUP`` is the wired equivalent. WIRELESS_POSTUP *************** Command that is run after bringing up a wireless interface. ``WIRED_POSTUP`` is the wired equivalent. WIRELESS_PREDOWN **************** Command that is run before bringing down a wireless interface. ``WIRED_PREDOWN`` is the wired equivalent. WIRELESS_POSTDOWN ***************** Command that is run after bringing down a wireless interface. ``WIRED_POSTDOWN`` is the wired equivalent. The interface configuration file ################################ A file should exist for each interface given in `PREFERRED_WIRELESS`_ and `PREFERRED_WIRED`_ . The file specifies the default connection, test, and disconnection commands that are to be used when connecting to a network. Those commands can be overriden in the `network configuration file`_. Here is the full list of variables CONNECT_COMMAND *************** Specifies the command to run to connect to the network. The command will be passed one argument: the name of the interface we are connecting to. Once this command is run, the network connectivity test must pass. ``dhcpcd`` is a good default value for this variable. TEST_COMMAND ************ Specifies the command to run as connectivity test. The command should return a zero status if we are connected to the network and a non-zero status otherwise. Some tests are already available in ``/usr/lib/autonet``, like ``test-googleping``, that just pings www.google.com, or ``test-paypalwget``, that tries to download `https://www.paypal.com/`, so that we can check we are not redirected to some stupid ISP welcome page for example. DISCONNECT_COMMAND ****************** The command to use to disconnect from the network. The command will be passed one argument: the named of the interface we are connecting to. ``dhcpcd -k`` is a good default value for this variable. NONET_CONNECT ************* Set this to ``true`` if you want to try running the connection commands even though ``wpa_supplicant`` did not connect to any network. Set this to ``false`` otherwise. This should usually be set to ``true`` for wired interfaces, and to ``false`` for wireless ones. .. _network configuration file: `The network configuration file`_ The network configuration file ############################## This can contain the same variables as the ones in the `interface configuration file`_. They will be used instead when this specific network is available. For example, if you need to start a VPN client for a given network, you might want to use some special connection and disconnection command. .. _interface configuration file: `The interface configuration file`_ The wpa_supplicant configuration file ##################################### There should be one file for each interface that is specified in ``autonet.conf``. This file is parsed by ``wpa_supplicant`` when it is started, and should have the format of a ``wpa_supplicant`` configuration file, use ``man wpa_configuration.conf`` for more information. For each network, the ``id_str`` variable will be used by autonet to identify the network in the output of ``autonet-status``.