[airos] updated docs for airos backend and intermediate representation

edoput · edoput · commit 2d6c41374a58 · 2017-07-25T11:29:01.000+02:00
[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
diff --git 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 <http://netjson.org/rfc.html#rfc.section.5.4.2.1>` empty defaults to no encryption at all.
diff --git 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.
