Welcome to netjsonconfig-airos’s documentation!

The AirOs backend allows to generate AirOS v8.3 compatible configurations. This work is a plugin to the netjsonconfig tool that you can install to generate configuration files for AirOS v8.3 .

Using netjsonconfig you can generate configuration files for many devices from different vendors starting from the same configuration syntax, NetJSON.

To get started using NetJSON and netjsonconfig please read their documentation but it should boil down to do

pip install netjsonconfig

Once you have installed netjsonconfig you will be able to install this package, as it is not published on pypi you will need to install it from a tarball or directly from the git repository. There is virtually no practical difference between the two options.

# this will install it using a tarball
pip install https://github.com/edoput/netjsonconfig-airos/tarball/master
# this will install it using git
pip install -e git+git://github.com/edoput/netjsonconfig-airos#egg=netjsonconfig-airos

If everything went correctly you will see that the airos backend is now available as an option in the help text for netjsonconfig.

netjsonconfig
usage: netjsonconfig [-h] [--config CONFIG] [--templates [TEMPLATES [TEMPLATES ...]]] [--native NATIVE]
                  --backend {openwrt,openwisp,openvpn,airos} # <--- ready to help your with airos!
                  --method {render,generate,write,validate,json}
                  [--args [ARGS [ARGS ...]]] [--verbose] [--version]
netjsonconfig: error: the following arguments are required: --method/-m --backend/-b

Converters with defaults

NetJSON does not map explicitly to various section of the AirOS device configuration. For those section we have provided default values that should work both in bridge and router mode.

The list of “defaulted” converters follows:

  • Discovery
  • Dhcpc
    • dhcpc.devname defaults to br0
  • Dyndns
  • Httpd
  • Igmpproxy
  • Iptables
    • iptables.sys.mgmt.devname defaults to br0
  • Netconf
    • the first interface with a gateway specified is the management interface in bridge mode
    • the first interface with a gateway specified is the wan interface in router mode
  • Pwdog
  • Radio
    • most of the configuration for the radio interface is taken from a PowerBeam PBE-5AC-400
  • Syslog
  • System
  • Telnetd
  • Tshaper
  • Unms
  • Update
  • Upnpd

General settings

From the general property we can configure the contact and the location for a device using the contact and location properties.

The following snippet specify both contact and location:

{
    "type": "DeviceConfiguration",
    "general": {
        "contact": "user@example.com",
        "location": "Up on the roof"
    }
}

Network interface

From the interfaces key we can configure the device network interfaces.

AirOS supports the following types of interfaces

  • network interfaces: may be of type ethernet
  • wirelesss interfaces: must be of type wireless
  • bridge interfaces: must be of type bridge

A network interface can be designed to be the management interfaces by setting the role key to mlan on the address chosen.

As an example here is a snippet that set the vlan eth0.2 to be the management interface on the address 192.168.1.20

{
    "interfaces": [
        {
            "name": "eth0.2",
            "type": "ethernet",
            "addresses": [
                {
                    "address": "192.168.1.20",
                    "family": "ipv4",
                    "role": "mlan",
                    "mask": 24,
                    "proto": "static"
                }
            ]
        }
    ]
}

Ethernet

The ethernet interface can be configured to allow auto-negotiation and flow control with the properties autoneg and flowcontrol

As an example here is a snippet that enables both auto-negotiation and flow control

 {
     "interfaces": [
         {
             "type": "ethernet",
             "name": "eth0",
             "autoneg": true,
             "flowcontrol": true
        }
    ]
}

Role

Interfaces can be assigned a role to mimic the web interfaces features.

As an example setting the role property of an address to mlan will add the role mlan to the interface configuration and set it as the management interface.

Warning

Not setting a management interface will lock you out from the web interface

Here is the snippet to set the role to mlan

{
    "interfaces": [
        {
            "type": "ethernet",
            "name": "eth0",
            "addresses": [
                {
                    "family": "ipv4",
                    "proto": "static",
                    "address": "192.168.1.1",
                    "role": "mlan"
                }
            ]
        }
    ]
}

This is the list of roles available for a device in bridge mode:

  • mlan for the management interface

This is the list of roles available for a device in router mode:

  • wan for the wan interface
  • lan for the lan interface

GUI

As an extension to NetJSON you can use the gui key to set the language of the interface

The default values for this key are reported below

{
    "type": "DeviceConfiguration",
    "gui": {
        "language": "en_US",
    }
}

Netmode

AirOS v8.3 can operate in bridge and router mode (but defaults to bridge) and this can be specified with the netmode property.

{
    "type": "DeviceConfiguration",
    "netmode": "bridge"
}

NTP servers

This is an extension to the NetJSON specification.

By setting the key ntp property in your input you can provide the configuration for the ntp client running on the device.

{
    "type": "DeviceConfiguration",
    "ntp": {
        "enabled": true,
        "server": [
            "0.ubnt.pool.ntp.org"
        ]
    }
}

For the lazy one we provide these defaults

{
    "type": "DeviceConfiguration",
    "ntp": {
        "enabled": true,
        "server": [
            "0.pool.ntp.org",
            "1.pool.ntp.org",
            "2.pool.ntp.org",
            "3.pool.ntp.org"
        ]
    }
}

Radio

The following properties of a Radio Object are used during the conversion, the others have been set to safe defaults.

  • name

Ssh

We can specify the configuration for the ssh server on the antenna using the sshd property.

This snippet shows how to configure the ssh server with the default values.

{
    "type": "DeviceConfiguration",
    "sshd": {
        "port": 22,
        "enabled": true,
        "password_auth": true
    }
}

And this shows how to set the authorized ssh public keys

{
    "type": "DeviceConfiguration",
    "sshd": {
        "keys": [
            {
                "type": "ssh-rsa",
                "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDBEEhdDJIbHVHIXQQ8dzH3pfmIbZjlrcIV+YkZM//ezQtINTUbqolCXFsETVVwbCH6d8Pi1v1lCDgILbkOOivTIKUgG8/84yI4VLCH03CAd55IG7IFZe9e6ThT4/MryH8zXKGAq5rnQSW90ashZaOEH0wNTOhkZmQ/QhduJcarevH4iZPrq5eM/ClCXzkF0I/EWN89xKRrjMB09WmuYOT48n5Es08iJxwQ1gKfjk84Fy+hwMKVtOssfBGuYMBWByJwuvW5xCH3H6eVr1GhkBRrlTy6KAkc9kfAsSpkHIyeb/jAS2hr6kAh6cxapKENHxoAdJNvMEpdU11v6PMoOtIb edoput@hypnotoad",
                "comment": "my shh key",
                "enabled": true
            }
        ]
    }
}

Users

We can specify the user password as a blob divided into salt and hash.

From the antenna configuration take the user section.

users.status=enabled
users.1.status=enabled
users.1.name=ubnt
users.1.password=$1$yRo1tmtC$EcdoRX.JnD4VaEYgghgWg1

In the line users.1.password=$1$yRo1tmtC$EcdoRX.JnD4VaEYgghgWg1 there are both the salt and the password hash in the format $ algorithm $ salt $ hash, e.g in the previous block algorithm=1, salt=yRo1tmtC and hash=EcdoRX.JnD4VaEYgghgWg1.

To specify the password in NetJSON use the user property.

{
    "type": "DeviceConfiguration",
    "user": {
        "name": "ubnt",
        "passsword": "EcdoRX.JnD4VaEYgghgWg1",
        "salt": "yRo1tmtC"
    }
}

WPA2

AirOS v8.3 supports both WPA2 personal (PSK+CCMP) and WPA2 enterprise (EAP+CCMP) as an authentication protocol. The only ciphers available is CCMP.

As an antenna only has one wireless network available only the first wireless interface will be used during the generation.

As an example here is a snippet that set the authentication protocol to WPA2 personal

{
    "interfaces": [
        {
            "name": "wlan0",
            "type": "wireless",
            "wireless": {
                "mode": "station",
                "radio": "ath0",
                "ssid": "ap-ssid-example",
                "encryption": {
                    "protocol": "wpa2_personal",
                    "key": "changeme"
                }
            }
        }
    ]
}

And another that set the authentication protocol to WPA2 enterprise

{
    "interfaces": [
        {
            "name": "wlan0",
            "type": "wireless",
            "wireless": {
                "mode": "station",
                "radio": "ath0",
                "ssid": "ap-ssid-example",
                "encryption": {
                    "protocol": "wpa2_enterprise",
                    "identity": "my-identity",
                    "password": "changeme",
                }
            }
        }
    ]

Indices and tables