From 2d6c41374a5846208e152c3251132af318d5490a Mon Sep 17 00:00:00 2001 From: Edoardo Putti Date: Tue, 25 Jul 2017 10:32:50 +0200 Subject: [PATCH] [airos] updated docs for airos backend and intermediate representation [airos] fixed problem with ellipsis not recognised in json example [airos] updated docs for ntp client and ntp servers [airos] fixed netjoson examples in documentation to be compliant to netjson [airos] fixed typo [airos] added terminal dot [airos] added snippet for the undecided about authentication encryption --- docs/source/backends/airos.rst | 67 +++++++++++++++++++++------ docs/source/backends/intermediate.rst | 57 +++++++++-------------- 2 files changed, 75 insertions(+), 49 deletions(-) diff --git a/docs/source/backends/airos.rst b/docs/source/backends/airos.rst index 0a16b0a76..3325cd29a 100644 --- a/docs/source/backends/airos.rst +++ b/docs/source/backends/airos.rst @@ -149,11 +149,12 @@ The default values for this key are as reported below Netmode ------- -AirOS v8.3 can operate in ``bridge`` and ``router`` mode (but defaults to ``bridge``) and this can be specified with the ``netmode`` property +AirOS v8.3 can operate in ``bridge`` and ``router`` mode (but defaults to ``bridge``) and this can be specified with the ``netmode`` property. .. code-block:: json { + "type": "DeviceConfiguration", "netmode": "bridge" } @@ -162,16 +163,35 @@ NTP servers This is an extension to the `NetJSON` specification. -By setting the key ``ntp_servers`` in your input you can provide a list of ntp servers to use. +By setting the key ``ntp`` property in your input you can provide the configuration for the ntp client running on the device. .. code-block:: json { "type": "DeviceConfiguration", - ... - "ntp_servers": [ - "0.ubnt.pool.ntp.org" - ] + "ntp": { + "enabled": true, + "server": [ + "0.ubnt.pool.ntp.org" + ] + } + } + +For the lazy one we provide these defaults + +.. code-block:: json + + { + "type": "DeviceConfiguration", + "ntp": { + "enabled": true, + "server": [ + "0.pool.ntp.org", + "1.pool.ntp.org", + "2.pool.ntp.org", + "3.pool.ntp.org" + ] + } } Users @@ -188,7 +208,7 @@ From the antenna configuration take the user section. users.1.name=ubnt users.1.password=$1$yRo1tmtC$EcdoRX.JnD4VaEYgghgWg1 -I 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``. +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. @@ -220,9 +240,11 @@ As an example here is a snippet that set the authentication protocol to WPA2 per { "name": "wlan0", "type": "wireless", - "encryption": { - "protocol": "wpa2_personal", - "key": "changeme" + "wireless": { + "encryption": { + "protocol": "wpa2_personal", + "key": "changeme" + } } } ] @@ -237,12 +259,31 @@ And another that set the authentication protocol to WPA2 enterprise, but this is { "name": "wlan0", "type": "wireless", - "encryption": { - "protocol": "wpa2_enterprise", - "key": "changeme" + "wireless": { + "encryption": { + "protocol": "wpa2_enterprise", + "key": "changeme" + } } } ] } +The ``encryption`` property **must** be specified otherwise you will experience a ``ValidationError``, if you are not sure on what you want +use this snippet to set to no encryption + +.. code-block:: json + + { + "interfaces": [ + { + "name": "wlan0", + "type": "wireless", + "wireless": { + "encryption": { + "protocol": "none" + } + } + } + } Leaving the `NetJSON Encryption object ` empty defaults to no encryption at all. diff --git a/docs/source/backends/intermediate.rst b/docs/source/backends/intermediate.rst index 142034826..35d262120 100644 --- a/docs/source/backends/intermediate.rst +++ b/docs/source/backends/intermediate.rst @@ -80,10 +80,11 @@ e.g. `vlan.1.devname=eth0` we store a list of dictionaries. { 'ipython' : True, } - ], - }, + ], + }, } - ]) + ] + ) And the resulting tree is: @@ -127,26 +128,10 @@ Flattening To avoid at all cost a recursive logic in the template we flatten the intermediate representation to something that has a *namespace* a *key* and a *value*. -This input NetJSON will be converted to a python :ref:`configuration_dictionary`: +The objective is to go from a python :ref:`configuration_dictionary` that we get from loading a NetJSON to the AirOS configuration. -.. code-block:: json +An input :ref:`configuration_dictionary` is just a python dictionary, e.g.: - //netjson - { - "type" : "DeviceConfiguration", - "interfaces" : [ - { - "name" : "eth0.1", - "type" : "ethernet", - "comment" : "management vlan" - }, - { - "name" : "eth0.2", - "type" : "ethernet", - "comment" : "traffic vlan" - } - ] - } .. code-block:: python @@ -157,11 +142,12 @@ This input NetJSON will be converted to a python :ref:`configuration_dictionary` 'name' : 'eth0.1', 'type' : 'ethernet', 'comment' : 'management vlan' + 'comment' : 'management' }, { 'name' : 'eth0.2', 'type' : 'ethernet', - 'comment' : 'traffic vlan' + 'comment' : 'traffic' } ] } @@ -191,21 +177,20 @@ resembles the target text, the output configuration. 'vlan', #options [ - { - # key : value - '1.devname' : 'eth0', - '1.id' : '1' - '1.status' : 'enabled', - '1.comment' : 'management' - }, - { - '2.devname' : 'eth0', - '2.id' : '2' - '2.status' : 'enabled', - '2.comment' : 'traffic' - } + { + # key : value + '1.devname' : 'eth0', + '1.id' : '1' + '1.status' : 'enabled', + '1.comment' : 'management' + }, + { + '2.devname' : 'eth0', + '2.id' : '2' + '2.status' : 'enabled', + '2.comment' : 'traffic' + } ] - ) And to do that we get rid of the multiple indentation levels by flattening the tree structure.