================= OpenWISP Firmware

.. image:: http://img.shields.io/github/release/openwisp/OpenWISP-Firmware.svg :target: https://github.com/openwisp/OpenWISP-Firmware/releases

.. image:: https://travis-ci.org/openwisp/OpenWISP-Firmware.svg?branch=master :target: https://travis-ci.org/openwisp/OpenWISP-Firmware

This is legacy software

If you are looking for a wifi controller <http://openwisp.org/whatis.html>_ solution to manage your OpenWRT/LEDE based networks, check out the more recent OpenWISP 2 Controller <https://github.com/openwisp/ansible-openwisp2>_ and the openwisp-config <https://github.com/openwisp/openwisp-config>_ OpenWRT/LEDE daemon.

Description

OpenWISP Firmware (shortly OWF) is an openwrt package that provides a daemon that periodically retrieves the configuration of the following components from an OpenWISP Manager (OWM) server:

• wifi (currently only for madwifi-ng and ath9k)
• networking
• layer 2 traffic shaping
• openvpn (layer 2, tap)
• cronjobs

OpenWISP Firmware also provides a web GUI for:

• configuring basic network parameters
• configuring basic OpenWISP server settings
• performing a set of test to spot and resolve most common problems that may prevent Open WISP firmware to work correctly

See the OWM wiki for more details.

Compiling OWF

In order to have a fully working OWF you have to compile it yourself.

OWF package supports an overlay configuration file that you should provide at compile time, this overlay allows you to include custom configuration. See below for more information on this file.

We strongly suggest to build OpenWRT on a GNU/Linux environment, you can find other pre-requisites here: http://wiki.openwrt.org/doc/howto/build.

If you have a properly configured machine follow these steps inside the OpenWRT root directory::

cp feeds.conf.default feeds.conf echo "src-git openwisp https://github.com/openwisp/OpenWISP-Firmware.git" >> feeds.conf ./scripts/feeds update ./scripts/feeds install openwisp-fw mkdir files # (see below) make menuconfig # (choose your arch and include openwisp-fw package and submodule if appropriate) make -j 1 V=s

The full version of OWF will support UMTS and mesh capability, but will require better hardware and much more space on flash/disk, we recommends an appropriate hardware under this condition.

Our firmware should ideally run on any OpenWRT-compatible device, but we have tested mainly atheros, x86, ar71xx platforms.

Stable version features:

• wifi support (Both drivers works alone or togheter)
• 3G support
• interface failover script

Overlay Configuration

The overlay configuration file is a directory that OpenWRT extracts inside the target rootfs and can potentially overwrite any other config file or add new files in the filesytem of the resulting firmware images.

Here's an example of the overlay configuration directory structure that should be provided to be fully compliant with OWM and OWF v1.x::

etc ├── config │   └── owispmanager ├── openvpn │   ├── ca.crt │   ├── client.crt │   └── ta.key └── shadow

This is an exmaple of the contents of etc/config/owispmanager::

config 'server' 'home' option 'address' 'my_OWM_server' option 'port' '' option 'status' 'configured' option 'inner_server' '' option 'inner_server_port' ''

config 'server' 'local' option 'hide_server_page' '1' option 'setup_wpa_psk' 'owf_safemode_wpakey' option 'setup_wifi_dev' '' option 'setup_httpd_port' '' option 'setup_ssid' '' option 'setup_ip' '' option 'setup_netmask' '' option 'setup_range_ip_start' '' option 'setup_range_ip_end' '' option 'hide_umts_page' '1' option 'hide_mesh_page' '1' option 'hide_ethernet_page' '0'

The etc/openvpn/ directory will contain the RSA certificates to establish a successfull connection with your own openvpn server (aka setup vpn) while /etc/shadow will provide a default password for the root user, here the file content for password "pass"::

root:$1$SwrPpeIH$8MMk3YQiVXl5uQzRgTIvU/:16386:0:99999:7::: daemon::0:0:99999:7::: ftp::0:0:99999:7::: network::0:0:99999:7::: nobody::0:0:99999:7:::

The overlay configuration MUST be provided in a directory named files/ in the OpenWRT/LEDE source.

For an example of directory structure see tests/dummy_config <https://github.com/openwisp/OpenWISP-Firmware/tree/master/tests/dummy_config>_ and refer to .travis.yml <https://github.com/openwisp/OpenWISP-Firmware/blob/master/.travis.yml>_ to setup the correct build enviroment.

Beware: if you update your overlay configuration please ensure to clean and recompile the openwisp package. This can be done using the following command inside openwrt build dir::

make package/openwisp-fw/clean

Developing the firmware

If you'd like to work locally on firmare improvement you should use a local OpenWisp Firmware repo clone and a local OpenWrt repo clone. In this configuration you should use the following commands for feed configuration::

echo "src-link openwisp /path/to/local/git/repo/" >> feeds.conf mkdir files # put your overlay configuration here ./scripts/feeds update

Compile Openwrt for multiple architectures

Here follows an example script to compile OWF for different arch targets::

#!/bin/bash

git clone https://github.com/openwrt/openwrt.git cd openwrt

#configure feeds cp feeds.conf.default feeds.conf echo "src-git openwisp https://github.com/openwisp/OpenWISP-Firmware.git" >> feeds.conf mkdir files # put your overlay configuration here ./scripts/feeds update ./scripts/feeds install openwisp-fw

#config target for arch in ar71xx atheros x86; do echo "CONFIG_TARGET_$arch=y" > .config; echo "CONFIG_PACKAGE_openwisp-fw=y" >> .config make defconfig; make package/openwisp-fw/clean; make -j 1 V=s; done

Copyright

Copyright (C) 2012-2016 OpenWISP.org

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.