Commit d346baa4 authored by Aleš Mrázek's avatar Aleš Mrázek

sphinx documentation, adding comments to examples

parent cbad9615
......@@ -22,6 +22,7 @@ Data model and library for DNS resolvers:
* [cznic-resolver-common](https://gitlab.labs.nic.cz/labs/resolvers-yang/raw/master/yang-modules/cznic-resolver-common@2018-07-27.yang)
* [cznic-resolver-knot](https://gitlab.labs.nic.cz/labs/resolvers-yang/raw/master/yang-modules/cznic-resolver-knot@2018-07-27.yang)
## Getting Started
Requires **Python 3.5** or newer
......@@ -40,3 +41,15 @@ $ git clone https://gitlab.labs.nic.cz/labs/resolvers-yang.git
$ cd resolvers-yang
$ python3 setup.py install
```
## Create local documentation
Local [Sphinx](http://www.sphinx-doc.org/en/master/) documentation is located in `resolvers-yang/docs` directory.
```
$ cd docs/
$ make html
```
In `_build/html` open `index.html` in your web browser.
\ No newline at end of file
.. _`example Json`:
**************************
Example of Valid Json
**************************
.. code-block:: json
{
"cznic-resolver-common:dns-resolver": {
"server": {
"user-name": "jetconf",
"group-name": "wheel"
},
"network": {
"listen-interfaces": [
{
"name": "lo4",
"ip-address": "127.0.0.1"
},
{
"name": "lo6",
"ip-address": "::1"
},
{
"name": "eth0",
"ip-address": "198.51.100.1",
"port": 8853
}
],
"source-address": {
"ipv6": "2001:db8:0:2::1"
},
"client-transport": {
"l2-protocols": "ipv6"
},
"recursion-transport": {
"l2-protocols": "ipv4 ipv6"
}
},
"resolver": {
"stub-zones": [
{
"domain": "stub.example.com",
"nameserver": "192.0.2.1",
"port": 53
},
{
"domain": "stub.example.net",
"nameserver": "198.51.100.1"
}
],
"hints": {
"cznic-resolver-knot:hint": [
{
"name": "localhost",
"canonical": true,
"values": [
"127.0.0.1",
"::1"
]
},
{
"name": "loopback",
"values": [
"127.0.0.1"
]
}
],
"cznic-resolver-knot:hosts-file": "/etc/hosts",
"root-hint": [
{
"name": "a.root-servers.net",
"values": [
"198.41.0.4",
"2001:503:ba3e::2:30"
]
}
],
"root-zone-file": "/etc/resolver/root.hints"
},
"options": {
"glue-checking": "strict",
"qname-minimisation": true,
"reorder-rrset": true,
"query-loopback": true
}
},
"logging": {
"verbosity": 2
},
"dnssec": {
"trust-anchors": {
"key-files": [
{
"domain": ".",
"file": "/var/tmp/root.keys",
"read-only": false
}
]
},
"negative-trust-anchors": [
"bad.example.com",
"worse.example.com"
]
},
"cache": {
"max-size": 104857600,
"max-ttl": 172800,
"min-ttl": 0,
"cznic-resolver-knot:prefill": [
{
"origin": ".",
"url": "https://www.internic.net/domain/root.zone",
"ca-file": "/etc/pki/tls/certs/ca-bundle.crt"
}
]
},
"dns64": {
"prefix": "64:ff9b::/96"
}
}
}
.. _examples:
**************************
Examples
**************************
`Yangson <https://github.com/CZ-NIC/yangson>`_ and `Resolvers-YANG <https://gitlab.labs.nic.cz/labs/resolvers-yang>`_ packages are needed to be installed.
========================================
Generating resolvers configuration files
========================================
Generating unbound.conf and kresd.conf
===============================
Converting unbound.conf to Json
===============================
.. _examples:
*********
Examples
*********
All examples are located in ``examples/`` directory.
**Requirements:**
* Python 3.5+
* `resolvers-yang <https://gitlab.labs.nic.cz/labs/resolvers-yang>`_ library must be installed.
* `yangson <https://github.com/CZ-NIC/yangson>`_ library
Using Python virtual environment is recommended. Look at :ref:`installation`
================================
example-data.json
================================
``example-data.json`` is example of Json-encoded file, which is valid against `resolvers-yang` data model
If you edit this Json, you can validate it against data model using::
$ make validate
No output means that ``example-data.json`` is valid.
================================
generate_conf.py
================================
This script will generate ``unbound.conf`` and ``kresd.conf`` files in local files.
Run ``generate_conf.py`` script with path to Json file as parameter::
$ python generate_conf.py example-data.json
If generated ``unbound.conf`` is converted to JSON using ``unb_to_json.py`` script. The result do not have to be the same as input JSON for ``generate_conf.py`` script because the configuration designed to Knot Resolver is ignored for Unbound.
============================
unb_to_json.py
============================
This script will convert ``unbound.conf`` to valid ``unb-data.json``.
As example configuration file can be used ``unbound.conf`` created after running ``generate_conf.py``
Run ``unb_to_conf.py`` with path to ``unbound.conf`` as parameter::
$ python unb_to_json.py unbound.conf
No output means that the JSON data in created ``unb-data.json`` is valid.
If you generate another ``unbound.conf`` from this Json, it should be equal to ``unbound.conf``, which was used as input parameter to ``unb_to_json.py`` script.
\ No newline at end of file
......@@ -10,14 +10,15 @@ YANG data models, python3 library and tools for unified configuration of DNS res
* `Knot Resolver <https://www.knot-resolver.cz/>`_
* `Unbound <https://www.unbound.net/>`_
.. toctree::
:maxdepth: 2
:caption: Contents:
installation
library
model
example_usage
examples
references
Indices and tables
......
.. _installation:
**************************
Getting Started
**************************
......
......@@ -7,9 +7,7 @@ Library Usage
>>> import os
>>> os.chdir("..")
.. testcleanup::
os.chdir("../..")
For better understanding, look at the :ref:`examples` and `Yangson library <https://yangson.labs.nic.cz/quickstart.html#>`_
......@@ -19,7 +17,7 @@ For better understanding, look at the :ref:`examples` and `Yangson library <http
Using Yangson
=============
This library is used to prepare and validate data.
This `library <https://yangson.labs.nic.cz/quickstart.html#>`_ is used to load and validate data against data model.
Import necessary python modules.
......@@ -29,19 +27,19 @@ Import necessary python modules.
>>> from yangson.datamodel import DataModel
Initialize the YANG data model. It can be done easily
by reading YANG library data [RFC7895]_ from a file:
by reading YANG library data [RFC7895]_ from a file:
.. doctest::
>>> model = DataModel.from_file('yang-modules/yanglib.json', 'yang-modules')
>>> model = DataModel.from_file('yang-modules/yanglib.json')
Load data from json file
Load data from Json-encoded file
.. doctest::
>>> with open('examples/example-data.json') as infile:
... ri = load(infile)
>>> json_data = dm.from_raw(ri)
>>> json_data = model.from_raw(ri)
Validate data against the data model:
......@@ -50,11 +48,11 @@ Validate data against the data model:
>>> json_data.validate()
Now you can use Resolvers-YANG library with this data.
Now you can use Resolvers-YANG utilities.
===============
Library modules
===============
=================
Library utilities
=================
Generator
---------
......@@ -94,3 +92,6 @@ Import ``from_unbound`` function for converting Unbound configuration string to
.. testcleanup::
os.chdir("../..")
......@@ -13,13 +13,13 @@ All Modules are located in ``yang-modules/`` project directory.
* `cznic-resolver-knot`_
=============
Model
Data Model
=============
Data Model is located in ``data-model/`` project directory.
* `Current schema tree`_
* :ref:`example json`
* `Example JSON data`_
Data model is divided into several smaller sections.
......
**********
References
**********
.. [RFC7895] Bierman, A.; Bjorklund, M.; Watsen, K. *YANG Module
Library.* `RFC 7895`__, IETF, 2016. 13 p. ISSN 2070-1721.
__ https://tools.ietf.org/html/rfc7895
......@@ -6,20 +6,24 @@ from resolvers_yang.generator import gen_unbound, gen_kresd
json_path = sys.argv[1]
# path to directory where are yang modules
yangdir = "../yang-modules"
# names of configuration files and paths where it will be created
kresd_path = "kresd.conf"
unb_path = "unbound.conf"
# load data model
# yangson load DataModel
model = DataModel.from_file(yangdir + "/yanglib.json", [yangdir])
# load data from json
# load data from Json-encoded file
with open(json_path) as infile:
ri = load(infile)
# load data to DataModel
data = model.from_raw(ri)
# validate against data model
# validate against DataModel
data.validate()
# adding missing default values
......@@ -29,12 +33,12 @@ data_defaults = data.add_defaults()
unb_conf = gen_unbound(data_defaults)
kresd_conf = gen_kresd(data_defaults)
# write kresd.conf
# write Knot Resolver configuration
knot_file = open(kresd_path, "w+")
knot_file.write(kresd_conf)
knot_file.close()
# write unbound.conf
# write Unbound configuration
unb_file = open(unb_path, "w+")
unb_file.write(unb_conf)
unb_file.close()
......@@ -4,29 +4,31 @@ from json import dump
from yangson.datamodel import DataModel
from resolvers_yang.converter import from_unbound
unbconf_path = sys.argv[1]
# path to directory where are yang modules
yangdir = "../yang-modules"
# setup of path where json file will be created
# name of json file and path where it will be created
data_json_path = "unb-data.json"
# load data model
# yangson load DataModel
model = DataModel.from_file(yangdir + "/yanglib.json", [yangdir])
unbconf_path = sys.argv[1]
# load unbound.conf file on specific path
# load unbound.conf file
with open(unbconf_path, "r") as unb_file:
unbconf_data = unb_file.readlines()
# call of conversion function
# call of conversion function unbconf_data >> Dictionary
json_data = from_unbound(unbconf_data)
# save converted configuration to json
# load data to DataModel
model_data = model.from_raw(json_data)
# validate data against data model
# validate data against DataModel
model_data.validate()
# save data to json
# save model_data to json
with open(data_json_path, 'w') as json_file:
dump(json_data, json_file, indent=2, sort_keys=False)
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment