Commit 5e5fd713 authored by Aleš Mrázek's avatar Aleš Mrázek
Browse files

Documentation update: developers, startguide

parent 3c3d2016
master
======
**Added:**
Added:
------
* Root Resource Discovery: https://tools.ietf.org/html/rfc8040#section-3.1
* ``DISABLE_SSL`` and ``CLIENT_CN`` options: https://github.com/CZ-NIC/jetconf/pull/8
* Operation Resource (action): https://tools.ietf.org/html/rfc8040#section-3.6
* DISABLE_SSL and CLIENT_CN options: https://github.com/CZ-NIC/jetconf/pull/8
* RESTCONF actions: https://tools.ietf.org/html/rfc8040#section-3.6
* simple systemd unit: https://github.com/CZ-NIC/jetconf/blob/master/data/jetconf%40.service
# Makefile for Sphinx documentation
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = /bin/sphinx-build
PAPER =
SPHINXPROJ = Jetconf
SOURCEDIR = .
BUILDDIR = _build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help
# Put it first so that "make" without argument is like "make help".
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " applehelp to make an Apple Help Book"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo " coverage to run coverage check of the documentation (if enabled)"
.PHONY: clean
clean:
rm -rf $(BUILDDIR)/*
.PHONY: html
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
.PHONY: dirhtml
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
.PHONY: singlehtml
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
.PHONY: pickle
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
.PHONY: json
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
.PHONY: htmlhelp
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
.PHONY: qthelp
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/JetConf.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/JetConf.qhc"
.PHONY: applehelp
applehelp:
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@echo
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
@echo "N.B. You won't be able to view it unless you put it in" \
"~/Library/Documentation/Help or install it in your application" \
"bundle."
.PHONY: devhelp
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/JetConf"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/JetConf"
@echo "# devhelp"
.PHONY: epub
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
.PHONY: latex
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
.PHONY: latexpdf
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
.PHONY: latexpdfja
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
.PHONY: text
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
.PHONY: man
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
.PHONY: texinfo
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
.PHONY: info
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
.PHONY: gettext
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
.PHONY: changes
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
.PHONY: linkcheck
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
.PHONY: doctest
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
.PHONY: coverage
coverage:
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
@echo "Testing of coverage in the sources finished, look at the " \
"results in $(BUILDDIR)/coverage/python.txt."
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: xml
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
.PHONY: help Makefile
.PHONY: pseudoxml
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
......@@ -32,9 +32,33 @@ In addition to this, backend package can also contain any other resources if nec
When you consider writing a custom backend, looking at the very basic demo package
jetconf_jukebox_ is a good way to start.
Handler inheritance
===================
Because some data models can be quite large, it would be difficult to manually assign
handler objects to all schema nodes. Because of this, for configuration and state data handlers,
Jetconf offers a feature called **Handler inheritance**.
If a node without its own handler is edited, Jetconf finds a nearest
parent node which has the handler assigned and then it calls its ``replace`` or ``replace_item``
method. It's up to backend developer's decision where to place handler objects, a more fine-grained
placement will usually mean better performance (less data rewriting), at the cost of more work.
usr_init
========
Useful for code that has to be executed on the startup or on the end of Jetconf backend.
.. code-block:: python
def jc_startup():
# execute code on startup
def jc_end():
# execute code on end
usr_datastore
=============
......@@ -405,17 +429,5 @@ initialization.
ds.handlers.action.register(act_handlers_obj.my_action_handler, "/ns:schema-path/to/action/node")
Handler inheritance
===================
Because some data models can be quite large, it would be difficult to manually assign
handler objects to all schema nodes. Because of this, for configuration and state data handlers,
Jetconf offers a feature called **Handler inheritance**.
If a node without its own handler is edited, Jetconf finds a nearest
parent node which has the handler assigned and then it calls its ``replace`` or ``replace_item``
method. It's up to backend developer's decision where to place handler objects, a more fine-grained
placement will usually mean better performance (less data rewriting), at the cost of more work.
.. _jetconf_jukebox: https://gitlab.labs.nic.cz/jetconf/jetconf-jukebox
.. _RFC7951: https://tools.ietf.org/html/rfc7951
\ No newline at end of file
......@@ -21,11 +21,10 @@ Their usage is described below.
**Installing OpenSSL**
To start with, check that OpenSSL is installed. If not, it should be available as a package for your operating system.
To start with, check that OpenSSL is installed.
If not, it should be available as a package for your operating system::
::
apt-get install openssl
$ apt-get install openssl
Certification Authority
......@@ -46,24 +45,18 @@ Alternatively, the CA-like certificate and key can be generated using the proced
Generate your own CA-like certificate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Make or move to your working directory
::
~$ mkdir my_ca_cert
~$ cd my_ca_cert
Generate ``ca.key``. see `details <https://www.openssl.org/docs/manmaster/man1/genrsa.html>`_.
Make or move to your working directory::
::
$ mkdir my_ca_cert
$ cd my_ca_cert
~$ openssl genrsa -out ca.key 2048
Generate ``ca.key``. see `details <https://www.openssl.org/docs/manmaster/man1/genrsa.html>`_::
Generate ``ca.pem`` certificate. see `details <https://www.openssl.org/docs/manmaster/man1/openssl-x509.html>`_.
$ openssl genrsa -out ca.key 2048
::
Generate ``ca.pem`` certificate. see `details <https://www.openssl.org/docs/manmaster/man1/openssl-x509.html>`_::
~$ openssl req -x509 -new -nodes -key ca.key -sha256 -days 1024 -out ca.pem
$ openssl req -x509 -new -nodes -key ca.key -sha256 -days 1024 -out ca.pem
Some parameters of the certificate have to be filled in.
They are not terribly important for testing purposes. For example::
......@@ -86,11 +79,11 @@ The script can be used in one of the two following ways.
The command will generate a new server private key along with the certificate::
~$ ./gen_server_cert.sh <out_file_suffix> <domain/ip>
$ ./gen_server_cert.sh <out_file_suffix> <domain/ip>
In this case, the name of the private key file passed to the script as the *<server_key>* argument::
~$ ./gen_server_cert.sh <out_file_suffix> <domain/ip> <server_key>
$ ./gen_server_cert.sh <out_file_suffix> <domain/ip> <server_key>
The script autodetects if the certificate is being issued for a domain
name or an IP address *<domain/ip>*, and sets the appropriate SAN value.
......@@ -98,7 +91,7 @@ name or an IP address *<domain/ip>*, and sets the appropriate SAN value.
For example, this command will create a certificate named ``server_example.crt``
for ``example.com`` domain with new private key ``server_example.key``::
~$ ./gen_server_cert.sh example example.com
$ ./gen_server_cert.sh example example.com
If you want this certificate to be accepted by your web browser,
the issuing CA's certificate needs to be imported to your browser.
......@@ -118,7 +111,7 @@ signed by the previously created CA-like certificate.
The script is used simply as follows::
~$ ./gen_client_cert.sh <email_address>
$ ./gen_client_cert.sh <email_address>
The issued certificate will use the email address passed in the argument is used as the
``emailAddress DN`` and ``commonName`` parameter of the client certificate.
......@@ -126,7 +119,7 @@ Also, the email address identifies the client to the JetConf server by default.
For example, the command::
~$ ./gen_client_cert.sh joe@example.net
$ ./gen_client_cert.sh joe@example.net
will generate the following files:
......
......@@ -8,17 +8,22 @@ Configuration options
:depth: 2
:local:
Jetconf configuration is set as ``.conf`` text file in YAML format loaded by Jetconf on startup.
Jetconf configuration has two types sections, *common* sections and *application-specific* sections.
Common sections
===============
Common sections are configuring core Jetconf settings available in any running same version of Jetconf.
It do not depend on the Jeconf backend package.
GLOBAL:
-------
Example
^^^^^^^
.. code-block:: yaml
GLOBAL:
......@@ -71,7 +76,7 @@ A location of Jetconf's process ID file.
*Default:* ``true``
This option specifies if the changes commited to datastore will also be synchronized to the filesystem
(*JSON* file defined by the ``DATA_JSON_FILE``option). It should be set to true in most cases, but can be turned
(*JSON* file defined by the ``DATA_JSON_FILE`` option). It should be set to true in most cases, but can be turned
off for i.e. testing purposes. If turned off, the Jetconf datastore will contain exactly the same initial
data at every startup.
......@@ -316,14 +321,13 @@ If set to false, NACM rules will not be applied.
A list of superusers allowed to edit NACM data. By default no superuser is specified.
Application-specific section
============================
Example
-------
Application-specific sections
=============================
Application-specific sections are configuring additional Jetconf settings available in specific implementation Jetconf.
Depends on Jeconf backend package. Typically it configures Jetconf backend settings, that have to be defined by backend developer.
Required by ``"jetconf_knot"`` backend package
For instance, configuration required by knot-jetconf_ backend package.
.. code-block:: yaml
......@@ -337,3 +341,6 @@ Required by ``"jetconf_knot"`` backend package
*Default:* ``"/tmp/knot.sock"``
A path to KnotDNS control socket.
.. _knot-jetconf: https://github.com/CZ-NIC/knot-jetconf
\ No newline at end of file
......@@ -2,4 +2,101 @@
**************
For Developers
**************
\ No newline at end of file
**************
.. warning::
It is highly recommended to set up a virtual environment for Jetconf
development. The following procedure uses the ``venv`` module for this
purpose (it is included in the standard Python library since
version 3.3).
Development Environment
=======================
#. Install the latest stable **Python3** version.
#. Clone the Jetconf project in a directory of your choice::
$ git clone https://github.com/CZ-NIC/jetconf.git
#. Create the virtual environment::
$ python3 -m venv jetconf
#. Activate the virtual environment::
$ cd jetconf
$ source bin/activate
#. Install required standard packages inside the virtual environment::
$ make install-deps
If you are prompted to upgrade ``pip``, you can do that, too.
When you are inside the virtual environment, the shell prompt should change to
something like::
(jetconf) $
To leave the virtual environment, just do::
$ deactivate
.. tip::
The virtual environment can be entered anytime later by executing step 4.
The steps preceding it need to be performed just once.
The setup described above has a few consequences that have to be kept in mind:
- Any project files that need to go to ``bin`` (executable Python scripts),``include`` or ``lib`` have to be added as exceptions to *.gitignore*, for example::
!bin/jetconf
- After adding a new Python module dependency, it is necessary to run::
$ make deps
and commit the new content of ``requirements.txt``.
.. Tools and Rules
===============
Programming Style
-----------------
We can mostly follow `Google Python Style Guide <https://google.github.io/styleguide/pyguide.html>`_.
All module-level functions and class/object methods should be annotated with type hints.
For other values, type hints should be used where it seems important.
See `PEP 0484 <https://www.python.org/dev/peps/pep-0484/>`_.
Static Type Checking
--------------------
Later we might use `mypy <http://mypy-lang.org>`_.
Currently it doesn't work well will Python 3.5.
Unit Tests
----------
We use `pytest <http://pytest.org>`_.
Documentation
-------------
We will use [Sphinx](http://www.sphinx-doc.org/en/stable/) for creating documentation.
Docstrings in the code should therefore use Sphinx directives,
see this `example <http://www.sphinx-doc.org/en/stable/domains.html#info-field-lists>`_.
Run from source
===============
For development purposes, Jetconf can also be started directly
from git repository with ``run.py`` script::
$ ./run.py -c <path_to_config_file.yaml>
......@@ -6,7 +6,9 @@ Jetconf Backends
JukeBox
=======
A demo Jetconf backend
- `jukebox-jetconf`
KnotDNS
=======
......@@ -36,12 +38,12 @@ User's certificate with ``_curl`` suffix in ``.pem`` format is needed.
After this command you should get some data from Jetconf server in json. Do not forget to set ``<path_to_pem_cert>`` and ``<jetconf server ip address>``::
~$ curl --http2 -k --cert-type PEM -E <path_to_pem_cert> -X GET https://<jetconf_server_ip_address>:8443/restconf/data
$ curl --http2 -k --cert-type PEM -E <path_to_pem_cert> -X GET https://<jetconf_server_ip_address>:8443/restconf/data
If ``DISABLE_SSL`` and ``CLIENT_CN`` are both set to ``true``, the following command can be used. ``<username>`` is sent in HTTP header::
~$curl --http2-prior-knowledge -H "X-SSL-Client-CN: <username>" -X GET http://<jetconf_server_ip_address>:8443/restconf/data
$ curl --http2-prior-knowledge -H "X-SSL-Client-CN: <username>" -X GET http://<jetconf_server_ip_address>:8443/restconf/data
Jetscreen
=========
......
.. GENERAL:
.. _GNU GPLv3: https://www.gnu.org/licenses/gpl.html
.. _RESTCONF: https://tools.ietf.org/html/rfc8040
.. _YANGSON: https://github.com/CZ-NIC/yangson
.. RFCs
.. _RFC7951: https://tools.ietf.org/html/rfc7951
.. _NACM: https://tools.ietf.org/html/rfc8341
.. _HTTP/2: https://tools.ietf.org/html/rfc7540
.. _YANG 1.1: https://tools.ietf.org/html/rfc7950
.. BACKENDS:
.. _jukebox-jetconf: https://gitlab.labs.nic.cz/jetconf/jetconf-jukebox
.. _jukebox-knot: https://gitlab.labs.nic.cz/jetconf/jetconf-knot
......@@ -7,12 +7,10 @@ Installation
Requirements
============
Jetconf requires **Python 3.5** or **newer**.
Jetconf requires **Python 3.5** or **newer**::
::
~$ apt-get install python3
~$ apt-get install python3-pip
$ apt-get install python3
$ apt-get install python3-pip
Other requirements should be installed automatically during installation.
......@@ -20,26 +18,117 @@ Other requirements should be installed automatically during installation.
Stable version - PyPI
=====================
Stable version is the most actual package version provided by Python Package Index (PyPI).
::
Stable version is the most actual package version provided by Python Package Index (PyPI)::
~$ pip install jetconf
$ pip install jetconf
Latest version - GitHub
=======================
Latest version is the most actual source code available in the Jetconf GitHub repository in ``master`` branch.
Latest version is the most actual source code available in the Jetconf GitHub repository. It is the ``master`` branch.
To install Jetconf from source
To install Jetconf from source::
::
$ git clone https://github.com/CZ-NIC/jetconf.git
$ cd jetconf
$ pip install -r requirements.txt
$ python3 setup.py install
******************************
Sample jukebox-jetconf backend
******************************
``jukebox-jetconf`` is an sample backend project created for Jetconf.
It is very useful as template for start developing a new Jetconf backend.
Installation
============
Clone backend project from repository::
$ git clone https://github.com/CZ-NIC/jukebox-jetconf
~$ git clone https://github.com/CZ-NIC/jetconf.git
~$ cd jetconf