Commit b0ccfc51 authored by Ales Mrazek's avatar Ales Mrazek

sphinx doctest ext, removed classes Generator and Converter, examples correction

parent 4220f06f
# include YANG modules and YANG library data
recursive-include yang-modules *.yang *.json
......@@ -26,7 +26,7 @@ author = 'Ales Mrazek'
# The short X.Y version
version = '0.1'
# The full version, including alpha/beta/rc tags
release = '0.1beta'
release = '0.1alpha'
# -- General configuration ---------------------------------------------------
......@@ -39,7 +39,7 @@ release = '0.1beta'
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.autodoc', 'sphinx.ext.doctest',
]
# Add any paths that contain templates here, relative to this directory.
......
.. _`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
**************************
\ No newline at end of file
......@@ -7,18 +7,17 @@ Resolvers-YANG
==========================================
YANG data models, python3 library and tools for unified configuration of DNS resolvers.
* `Knot Resolver`_
* Unbound_
* `Knot Resolver <https://www.knot-resolver.cz/>`_
* `Unbound <https://www.unbound.net/>`_
.. toctree::
:maxdepth: 2
:caption: Contents:
installation
model
library
examples
model
example_usage
Indices and tables
......@@ -29,5 +28,3 @@ Indices and tables
* :ref:`search`
.. _Knot Resolver: https://www.knot-resolver.cz/
.. _Unbound: https://www.unbound.net/
\ No newline at end of file
**************************
Getting Started
**************************
\ No newline at end of file
**************************
Resolvers-YANG library requires `Python 3.5 <https://www.python.org/>`_ or newer::
$ sudo apt-get install python3
$ sudo apt-get install python3-pip
===========
Development
===========
1. Clone the project in a directory of your choice::
$ git clone git@gitlab.labs.nic.cz:labs/resolvers-yang.git
2. Create the virtual environment::
$ python3 -m venv resolvers-yang
3. Activate the virtual environment::
$ cd resolvers-yang
$ source bin/activate
When inside the virtual environment, the shell prompt should change to something like::
(resolvers-yang) $
4. Install required standard packages inside the virtual environment::
$ pip install -r requirements.txt
If you are prompted to upgrade *pip*, you can do that, too.
5. To leave the virtual environment, just do::
(resolvers-yang) $ deactivate
The virtual environment can be entered anytime later by executing step 3. The steps preceding it need to be performed just once.
Now you can edit and install Resolvers-YANG.
============
Installation
============
::
$ git clone https://gitlab.labs.nic.cz/labs/resolvers-yang
$ cd resolvers-yang
$ python3 setup.py install
**************************
Library Functions
**************************
\ No newline at end of file
Library Usage
**************************
.. testsetup::
>>> 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#>`_
`Yangson <https://yangson.labs.nic.cz/quickstart.html#>`_ is a library for working with JSON encoded configuration and state data modelled using the YANG data modelling language.
=============
Using Yangson
=============
This library is used to prepare and validate data.
Import necessary python modules.
.. doctest::
>>> from json import load
>>> from yangson.datamodel import DataModel
Initialize the YANG data model. It can be done easily
by reading YANG library data [RFC7895]_ from a file:
.. doctest::
>>> model = DataModel.from_file('yang-modules/yanglib.json', 'yang-modules')
Load data from json file
.. doctest::
>>> with open('examples/example-data.json') as infile:
... ri = load(infile)
>>> json_data = dm.from_raw(ri)
Validate data against the data model:
.. doctest::
>>> json_data.validate()
Now you can use Resolvers-YANG library with this data.
===============
Library modules
===============
Generator
---------
Import ``gen_unbound`` and ``gen_kresd`` functions to generate Unbound and Knot Resolver configuration strings from valid python dictionary loaded from Json.
.. doctest::
>>> from resolvers_yang.generator import gen_unbound, gen_kresd
Call generator functions to generate `unbound.conf` and `kresd.conf`.
.. doctest::
>>> unbound_conf = gen_unbound(json_data)
>>> kresd_conf = gen_kresd(json_data)
Converter
---------
Import ``from_unbound`` function for converting Unbound configuration string to valid python dictionary which can be save as Json file.
.. doctest::
>>> from resolvers_yang.converter import from_unbound
.. code-block:: python
# import of Converter module
from resolvers_yang.converter import from_unbound
# call of conversion function
json_data = Converter.from_unbound(unbound_conf)
......@@ -2,3 +2,51 @@
YANG Data Model
***************
=============
YANG Modules
=============
All Modules are located in ``yang-modules/`` project directory.
* `cznic-dns-types`_
* `cznic-resolver-common`_
* `cznic-resolver-knot`_
=============
Model
=============
Data Model is located in ``data-model/`` project directory.
* `Current schema tree`_
* :ref:`example json`
Data model is divided into several smaller sections.
server:
-------------
network:
-------------
resolver:
-------------
logging:
-------------
dnssec:
-------------
cache:
-------------
dns64:
-------------
.. _Current schema tree: https://gitlab.labs.nic.cz/jetconf/jetconf-resolver/raw/master/data-model/model.tree
.. _Example JSON data: https://gitlab.labs.nic.cz/jetconf/jetconf-resolver/raw/master/tests/complete/example-data.json
.. _cznic-dns-types: https://gitlab.labs.nic.cz/jetconf/jetconf-resolver/raw/master/yang-modules/cznic-dns-types@2018-05-14.yang
.. _cznic-resolver-common: https://gitlab.labs.nic.cz/jetconf/jetconf-resolver/raw/master/yang-modules/cznic-resolver-knot@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
import sys
from yangson.datamodel import DataModel
from json import load
from resolvers_yang.generator import Generator
from resolvers_yang.generator import gen_kresd, gen_unbound
json_path = sys.argv[1]
......@@ -23,6 +23,9 @@ data = model.from_raw(ri)
# validate against data model
data.validate()
# adding missing default values
data_defaults = data.add_defaults()
# get path where is mock data located
mock_path = data["cznic-deckard:deckard"]["mock-data"].value
......@@ -34,8 +37,8 @@ mock_begin = mock_data.find("SCENARIO_BEGIN")
mock_data = mock_data[mock_begin:]
# generate configuration strings
unb_conf = Generator.unbound(data)
kresd_conf = Generator.kresd(data)
unb_conf = gen_unbound(data_defaults)
kresd_conf = gen_kresd(data_defaults)
# write kresd.conf
knot_file = open(kresd_path, "w+")
......
......@@ -2,8 +2,7 @@ import sys
from json import load
from yangson.datamodel import DataModel
from resolvers_yang.generator import Generator
from resolvers_yang.generator import gen_unbound, gen_kresd
json_path = sys.argv[1]
......@@ -27,8 +26,8 @@ data.validate()
data_defaults = data.add_defaults()
# generate configuration strings
unb_conf = Generator.unbound(data_defaults)
kresd_conf = Generator.kresd(data_defaults)
unb_conf = gen_unbound(data_defaults)
kresd_conf = gen_kresd(data_defaults)
# write kresd.conf
knot_file = open(kresd_path, "w+")
......
......@@ -2,7 +2,7 @@ import sys
from json import dump
from yangson.datamodel import DataModel
from resolvers_yang.converter import Converter
from resolvers_yang.converter import from_unbound
yangdir = "../yang-modules"
......@@ -18,7 +18,7 @@ with open(unbconf_path, "r") as unb_file:
unbconf_data = unb_file.readlines()
# call of conversion function
json_data = Converter.from_unbound(unbconf_data)
json_data = from_unbound(unbconf_data)
# save converted configuration to json
model_data = model.from_raw(json_data)
......
This diff is collapsed.
This diff is collapsed.
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