Add New Page: You are not allowed to add pages Select section/namespace. New page title.
 

Commotion Router code documentation

This page documents Commotion Router pre-v1.0 and is likely outdated as of 5/2014

Requirements for Installation (from stock Debian Wheezy)

  • Git
  • Subversion
  • libncurses5-dev
  • zlib1g-dev
  • flex

File Structure

See “the commotion-openwrt repo”:https://github.com/opentechinstitute/commotion-openwrt for the OpenWRT package files

Firstboot Workflow

  1. uci-defaults files execute, applying any post-install patches and fixes. They are then deleted.
  2. Meshconfig script runs, which:
    1. Loads network defaults from meshconfig profile specified in /etc/config/system, or from default meshconfig profile if unspecified, and saves them in /etc/config/mesh.
    2. Generates meshid from the MAC address of first wireless interface. - Sets hostname based on meshid, or based on location if set in /etc/config/system
    3. Removes default wireless file, and calls built in 'wifi detect' script in order to generate new one, detecting radios and radio capabilities and writing them into /etc/config/wireless. This forestalls the /etc/init.d/network script from doing the same thing.
    4. Removes interfaces from generated /etc/config/wireless.
    5. Synchronously parses /etc/config/network and /etc/config/wireless, and generates a wireless interface with appropriate settings from each /etc/config/network stanza, trying to distribute them amongst radio devices. These are set with a default SSID ('CommotionSetup-*'), otherwise wireless intialization won't continue. Actual SSID and channel settings aren't set at this point.
  3. Continuing boot process, /etc/init.d/network calls the coldplug_interface_* function in /lib/network/commotion.sh for each interface, which sets channel, SSID, and other parameters for each interface.
  4. setup_interface_* functions in /lib/network/commotion.sh are called, which set addresses and other IP-layer configuration parameters. As these are run, a 'reset 0' option is set in each stanza, to keep them from needlessly reconfiguring on each boot.
  5. As the IP-layer setup is called, pre- and post- up hotplug calls are made, running scripts in /etc/hotplug.d/services/ for each auto-configured service.

Code Documentation

Important files

"/lib/network/commotion.sh":https://github.com/opentechinstitute/commotion-openwrt/blob/master/commotionfeed/commotionbase/files/lib/network/commotion.sh

Primary script library for Commotion-OpenWRT. All functions here are either called by the OpenWRT network configuration hooks, or are internal functions used by those hooks.

Main Functions

"setup_interface_meshif":https://github.com/opentechinstitute/commotion-openwrt/blob/master/commotionfeed/commotionbase/files/lib/network/commotion.sh#L314

PARAMETERS: 2; interface and config name

RETURNS: Nothing

DESCRIPTION: The function called by OpenWRT for proto 'meshif' interfaces. It calls any other functions necessary in order to generate network addresses and configurations for the mesh interface, based on the configuration contained in /etc/config/mesh.

== “setup_interface_apif”:https://github.com/opentechinstitute/commotion-openwrt/blob/master/commotionfeed/commotionbase/files/lib/network/commotion.sh#L394 ==

PARAMETERS: 2; interface and config name

RETURNS: Nothing

DESCRIPTION: The function called by OpenWRT for proto 'apif' interfaces. It calls any other functions necessary in order to generate network addresses and configurations for any AP interfaces, based on the configuration contained in /etc/config/mesh. It also makes sure that it's in the appropriate subnet based on whether or not this interface is set as 'secure'.

"setup_interface_plugif":https://github.com/opentechinstitute/commotion-openwrt/blob/master/commotionfeed/commotionbase/files/lib/network/commotion.sh#L487

*PARAMETERS:* 2; interface and config name

*RETURNS:* Nothing

*DESCRIPTION:* The function called by OpenWRT for proto 'plugif' interfaces. It calls any other functions necessary in order to generate network addresses and configurations for any dynamically pluggable wired interfaces, based on the configuration contained in /etc/config/mesh. Unlike the hooks for the other two protocol handlers, this function does not attempt to statically set anything in /etc/config/network == “coldplug_interface_meshif”:https://github.com/opentechinstitute/commotion-openwrt/blob/master/commotionfeed/commotionbase/files/lib/network/commotion.sh#L368 ==

*PARAMETERS:* 1; name of the interface

*RETURNS:* Nothing

*DESCRIPTION:* The function called by OpenWRT for proto 'meshif' interfaces. It is called early in the boot process in order to initialize the wireless interfaces before the 'setup' call sets the IP information.

== “coldplug_interface_apif”:https://github.com/opentechinstitute/commotion-openwrt/blob/master/commotionfeed/commotionbase/files/lib/network/commotion.sh#L454 ==

*PARAMETERS:* 1; name of the interface

*RETURNS:* Nothing

*DESCRIPTION:* The function called by OpenWRT for proto 'apif' interfaces. It is called early in the boot process in order to initialize the wireless interfaces before the 'setup' call sets the IP information.

== “stop_interface_meshif”:https://github.com/opentechinstitute/commotion-openwrt/blob/master/commotionfeed/commotionbase/files/lib/network/commotion.sh#L380 ==

*PARAMETERS:* 1; config name of the interface

*RETURNS:* Nothing

*DESCRIPTION:* The function called by OpenWRT for proto 'meshif' interfaces. It is called when an interface is brought down, and primarily exists just to run the 'postdown' hotplug hook.

"stop_interface_apif":https://github.com/opentechinstitute/commotion-openwrt/blob/master/commotionfeed/commotionbase/files/lib/network/commotion.sh#L473

*PARAMETERS:* 1; config name of the interface

*RETURNS:* Nothing

*DESCRIPTION:* The function called by OpenWRT for proto 'apif' interfaces. It is called when an interface is brought down, and primarily exists just to run the 'postdown' hotplug hook.

== “stop_interface_plugif”:https://github.com/opentechinstitute/commotion-openwrt/blob/master/commotionfeed/commotionbase/files/lib/network/commotion.sh#L561 ==

*PARAMETERS:* 1; config name of the interface

*RETURNS:* Nothing

*DESCRIPTION:* The function called by OpenWRT for proto 'plugif' interfaces. It is called when an interface is brought down, and unlike the other two 'stop' protocol handlers, actually does stuff. Since the plugif interfaces have their configuration generated from scratch every time, this function removes all relevent IP information and reloads the firewall.

=== Helper Function ===

== setup_meshif_wireless ==

*PARAMETERS:* 1; config name of the interface

*RETURNS:* Nothing

*DESCRIPTION:* This function is called by the coldplug function, and sets wireless parameters such as SSID and channel for the mesh interface based on information in /etc/config/mesh. It also sets encryption on the backhaul interface if this interface includes the 'secure 1' option in /etc/config/network.

== setup_apif_wireless ==

*PARAMETERS:* 1; config name of the interface

*RETURNS:* Nothing

*DESCRIPTION:* This function is called by the coldplug function, and sets wireless parameters such as SSID and channel for the AP interface based on information in /etc/config/mesh. It also sets encryption on the AP interface if this interface includes the 'secure 1' option in /etc/config/network.

== set_fwzone ==

*PARAMETERS:* 2; config name of the interface and firewall zone to set it to.

*RETURNS:* Nothing

*DESCRIPTION:* This function is called by the setup_interface function, and is a helper to set the firewall zone for an interface.

== unset_fwzone ==

*PARAMETERS:* 1; config name of the interface

*RETURNS:* Nothing

*DESCRIPTION:* This function is called by the stop_interface function, and is a helper to remove an interface from all firewall zones.

== /etc/init.d/meshconfig ==

This script runs early on at boot, and both helps with correctly initializing the wireless configuration and sets configuration information for things that are not dependent on a particular network interface coming up or down (for example, the hostname).

=== Functions ===

== apply_mesh_defaults ==

*PARAMETERS:* 2; name of community network and the role of this node

*RETURNS:* Nothing

*DESCRIPTION:* This function is called on boot if /etc/config/mesh is empty, and attempts to load the configuration profile (really a script) for the community network and role specified in /etc/config/system (or barring that, /etc/meshconfig/default/default).

apply_wireless_defaults

*PARAMETERS:* None

*RETURNS:* Nothing

*DESCRIPTION:* This function is called on boot if a default /etc/config/wireless is detected. It proceeds to parse the /etc/config/network and /etc/config/wireless files, and make sure that there's exactly one wifi-iface stanza in /etc/config/wireless for each interface stanza in /etc/config/network == apply_hostname_defaults ==

*PARAMETERS:* None

*RETURNS:* Nothing

*DESCRIPTION:* This function is called on boot if a default hostname in /etc/config/system is detected. It then sets the hostname based on the network name and location if set, and the network name and nodeid if not.

apply_analytics_defaults

*PARAMETERS:* None

*RETURNS:* Nothing

*DESCRIPTION:* This function is called on boot if an unconfigured /etc/config/luci_statistics file is detected. It then configures collectd based on the information in /etc/config/mesh. It then sets a commotion_config stanza in the luci_statistics file, to indicated on future boots that it has been configured.

== apply_vpn_defaults ==

*PARAMETERS:* None

*RETURNS:* Nothing

*DESCRIPTION:* This function is called on boot if an unconfigured /etc/config/n2n file is detected. It then configures n2n based on the information in /etc/config/mesh. It then sets a commotion_config stanza in the n2n file, to indicated on future boots that it has been configured.

== boot ==

*PARAMETERS:* None

*RETURNS:* Nothing

*DESCRIPTION:* System function called on boot, includes the logic for determining if the functions above need to be run.

=== Non-boot Functions ===

== upgrade ==

*PARAMETERS:* None

*RETURNS:* Nothing

*DESCRIPTION:* Called from cron function, attempts to run remote-update if enabled. == cron ==

*PARAMETERS:* None

*RETURNS:* Nothing

*DESCRIPTION:* Called from cron, checks to make sure dnsmasq and olsrd are running, also runs upgrade function.

*/setup.sh*

Requires:Subversion

Type: Shell Script

  • clones “backfire” branch of OpenWRT from subversion directory
  • open the newly cloned openwrt folder
  • examines the folder for the .config and feeds.conf files and if not there copies the premade commotion versions of these files from the commotion directory into the new openwrt directory
  • examines the folder for the files folder and if not there creates a files folder and copies the default-files/ folder and all its contents into the newly created files folder
  • checks the feeds.conf file to see if it says commotion, if not, it adds commotion package to the feed.conf file.
  • Runs the openwrt scripts/feeds update
  • Installs the commotionbase to openwrt
  • Echos to the user the next steps to install
*/config*

type:OpenWRT configuration file

  • make configuration file customized for commotions openWRT install
  • to add a package delete the # in front and change the “is not set” to a =y
    • “# CONFIG_PACKAGE_some-name is not set” = “CONFIG_PACKAGE_some-name=y”