AirOS Backend¶
The AirOs
backend allows to generate AirOS v8.3 compatible configurations.
Warning
This backend is in experimental stage: it may have bugs and it will receive backward incompatible updates during the first 6 months of development (starting from September 2017). Early feedback and contributions are very welcome and will help to stabilize the backend faster.
Initialization¶
-
AirOs.
__init__
(config=None, native=None, templates=None, context=None)¶ Parameters: - config –
dict
containing a valid NetJSON configuration dictionary - native –
str
or file object representing a native configuration that will be parsed and converted to a NetJSON configuration dictionary - templates –
list
containing NetJSON configuration dictionaries that will be used as a base for the main config - context –
dict
containing configuration variables
Raises: TypeError – raised if
config
is not of typedict
or iftemplates
is not of typelist
- config –
Initialization example:
from netjsonconfig import AirOs
router = AirOs({
"general": {
"hostname": "MasterAntenna"
}
})
If you are unsure about the meaning of the initalization parameters, read about the following basic concepts:
Render method¶
-
AirOs.
render
(files=True)¶ Converts the configuration dictionary into the corresponding configuration format
Parameters: files – whether to include “additional files” in the output or not; defaults to True
Returns: string with output
Generate method¶
Write method¶
JSON method¶
-
AirOs.
json
(validate=True, *args, **kwargs)¶ returns a string formatted as NetJSON DeviceConfiguration; performs validation before returning output;
*args
and*kwargs
will be passed tojson.dumps
;Returns: string
Extending the backend¶
Please see the Intermediate representation page for extending converters and adding functionalities to this backend
The configuration upgrade process¶
Please see the Tools page for information about the process and tools that upgrades the configuration on the device
Converters with defaults¶
NetSJON 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 tobr0
- Dyndns
- Httpd
- Igmpproxy
- Iptables
iptables.sys.mgmt.devname
defaults tobr0
- Netconf
- the first interface with a
gateway
specified is the management interface inbridge
mode - the first interface with a
gateway
specified is thewan
interface inrouter
mode
- the first interface with a
- Pwdog
- Radio
- most of the configuration for the radio interface is taken from a PowerBeam
PBE-5AC-400
- most of the configuration for the radio interface is taken from a PowerBeam
- 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 interfacelan
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",
}
}
}
]