OpenWRT Packages/Implementation

This page describes how specific features are implemented in the new node firmware.

System config

OpenWRT stores its config in /etc/config/ in UCI format. SOWN packages also store config in this location and format wherever possible.

Config for daemons is usually converted to a config file, or to command line arguments, by the OpenWRT /etc/init.d/ scripts. These config files usually end up in /var/run/ which is mapped to a directory in /tmp/.

System config updating

System config updating is performed by individual scripts in /etc/sown/configure_scripts/available.

UCI config updating

Scripts generally call update_config to check for new versions of a UCI config file.

NB: the magic parameters __PACKAGE__ and __VERSION__ are replaced with the package name and version at package build time for easier maintenance.

update_config returns 0 if there was an update to the config file, and 1 on error or no update.

NB: Un-parsable config files will be reverted by update_config and result in an error code.

Scripts then use this return code to determine when to restart services.

Non-UCI config updating

Under the hood update_config calls download_package_uri to download files. The caller of download_package_uri is responsible for handling the file retrieved.

download_package_uri will return 0 on success, 1 on HTTP 304 Not Modified and 1 on error. download_package_uri can be passed extra curl config lines which can be used to specify last-modified times, or etag hashes.

The credentials update script uses this to download an archive containing the client public and private keys, and the /etc/passwd file.

Server-side code

HTTP requests to auth are to URLs of the following form:

https://sown-auth.ecs.soton.ac.uk/pkg/config/backfire/<package_name>/<version_number>/<request_name>

The prefix https://sown-auth.ecs.soton.ac.uk/pkg/config/backfire/ is read from the /etc/config/sown_core config file.

On Auth, package config generation functions live in kohana/application/classes/package/config/backfire/.

Requests for these first pass through the request controller in kohana/application/classes/controller/package/config/backfire.php which handles request version numbers, client identity and request permission logic.

The URL is mapped through a rewrite in pkg/.htaccess and the package_config route in kohana/application/bootstrap.php.

Automatic system config updating

Enabled config updating scripts are symlinked in /etc/sown/configure_scripts/enabled.

These scripts are invoked by /usr/sbin/update_sown_config, which is invoked by crontab when auth is reachable.

Crontabs

Available crontabs are found in /etc/sown/crontabs/available/.

Currently enabled crontabs are symlinked in /tmp/sown/crontabs/current, this directory is populated at boot from /etc/sown/crontabs/at_boot/ by /etc/init.d/sown_boot.

The rationale for this is that dynamic changes to the crontab will not require changes to the flash memory.

The sown functions file (/etc/sown/functions.sh) contains three functions for managing the crontabs.

enable_crontab and disable_crontab

Updates the symlinks in /tmp/sown/crontabs/current. Returns 0 on a change, 1 otherwise.

update_crontabs

Installs a new crontab if changes from the running crontab are detected.

This may be used most effectively for single crontab changes as follows:

enable_crontab my_crontab && update_crontabs

For multiple changes, either do the overall change detection manually, or do this:

enable_crontab my_crontab1
enable_crontab my_crontab2
update_crontabs

update_crontabs will MD5 the crontabs anyway, so it may be considered safe.

Server status check

The server status checker lives in /usr/sbin/server_status_check. It pings the sown core servers on their different IP addresses to determine the state of the network.

Currently it is designed to trigger the following event scripts:

• auth_ecs_reachable
• auth_ecs_unreachable
• sown_network_reachable
• sown_network_unreachable

Events

Event scripts live in /etc/sown/events/.

Tunnel

The sown tunnel is maintained by the /usr/sbin/maintain_sown_tunnel script. The maintainer script is started periodically by crontab, and by hotplug as soon as eth0 comes up (see /etc/hotplug.d/90_tunnel).

If it is already running, the script will not start a second instance.

The maintainer waits until the VPN server is reachable before starting OpenVPN. If sufficient servers are reachable, the script will not start OpenVPN.

Openvpn triggers the following event scripts:

• tunnel_up
• tunnel_down

Logging

Logging is implemented through syslog-ng.

The OpenWRT syslog package design is not very well engineered, so syslog-ng cannot replace it fully out of the box. In the sown_core package postinst script we remove the busybox symlinks for syslogd and klogd, and add in a script to start syslog-ng. This ensures that OpenWRT starts syslog-ng as early as possible. The prerm package script reinstates the altered links.

The configuration options for a node to log to our VPN servers are currently commented out.

Circular log

For development there's a hacked-together circular logging script which logs 150-200 lines to /var/log/messages. This should be replaced by a better compiled binary utility if there is one available.

Unimplemented Ideas

when
	auth becomes reachable
then
	start offering eduroam

when
	auth becomes unreachable
and
	no clients are using eduroam
then
	switch eduroam to hidden

if
	eth0 comes up
and
	it's configured to a static IP
after
	X seconds
if 
	auth has never been reachable
then
	revert to DHCP