Commit 2a4e923c authored by Ales Mrazek's avatar Ales Mrazek

Documentation update: developers, startguide, README

parent 5e5fd713
......@@ -20,6 +20,7 @@ release:
rm -f dist/*
python3 setup.py sdist
python3 setup.py bdist_wheel
twine check dist/*
upload:
twine upload dist/*
......@@ -6,7 +6,7 @@ Jetconf is an implementation of the RESTCONF_ protocol written in
Python 3.
* `Documentation`_
* `GitHub repository`_
* `Git repository`_
Main features:
......@@ -18,59 +18,24 @@ Main features:
* Support for NACM_
Requirements
Installation
============
Jetconf requires **Python 3.6 or newer**::
Python 3.5 or newer is required::
~$ apt-get install python3
~$ apt-get install python3-pip
These requirements should be installed by running *Instalation*
::
colorlog
h2==3.0.1
pytz
PyYAML
yangson
Installation
============
JetConf can be installed by PyPI::
Jetconf can be installed by PyPI::
$ python3 -m pip install jetconf
Running
=======
Running JetConf::
Run Jetconf
===========
::
~$ jetconf -c <path_to_config_file.yaml>
For development purposes, JetConf can also be started directly
from git repository with ``run.py`` script.::
~$ ./run.py -c <path_to_config_file.yaml>
Example configuration (template)
================================
In the ``data`` folder, there is an example template ``example-config.yaml`` for
configuring paths, certificates etc.
In this configuration file, you have to modify all paths to match
your actual file locations.
.. _RESTCONF: https://tools.ietf.org/html/draft-ietf-netconf-restconf-18
.. _NACM: https://datatracker.ietf.org/doc/rfc6536/
.. _GitHub repository: https://github.com/CZ-NIC/jetconf
.. _Git repository: https://github.com/CZ-NIC/jetconf
.. _Documentation: https://jetconf.readthedocs.io
.. include:: references.rst
.. _architecture:
************
......@@ -7,7 +8,7 @@ Architecture
Jetconf is an implementation of the RESTCONF_ protocol for remote
management of network devices and services.
`YANG 1.1`_ data modelling language is also fully supported.
`YANG 1.1`_ data modelling language is also fully supported.
JetConf is written in Python 3 language and available as open source
software under the terms of the `GNU GPLv3`_ license.
......@@ -15,7 +16,7 @@ software under the terms of the `GNU GPLv3`_ license.
Requirements and Restrictions
=============================
JetConf is a compliant RESTCONF_ implementation supporting all mandatory features.
Jetconf is a compliant RESTCONF_ implementation supporting all mandatory features.
Although it is written in Python, it should be fast enough to support
large configuration databases with moderate rate of changes. A typical
......@@ -53,7 +54,7 @@ The current version of Jetconf implements NACM_ access control
system, which enables to specify fine-grained access permissions to
particular data resources.
The NACM_ data can only be edited by privileged users in startup configuration.
The NACM data can only be edited by privileged users in startup configuration.
Jetconf Server Loop
===================
......@@ -114,10 +115,3 @@ Python Modules
* ``helpers``: static helper classes shared across modules,
* ``op_internal``: implementation of Jetconf internal RPCs,
* ``errors``: definition of exceptions used in Jetconf.
.. _YANG 1.1: https://tools.ietf.org/html/rfc7950
.. _RESTCONF: https://tools.ietf.org/html/rfc8040
.. _GNU GPLv3: https://www.gnu.org/licenses/gpl.html
.. _HTTP/2: https://tools.ietf.org/html/rfc7540
.. _YANGSON: https://github.com/CZ-NIC/yangson
.. _NACM: https://tools.ietf.org/html/rfc8341
\ No newline at end of file
.. include:: references.rst
.. _backendapi:
***********
......@@ -30,7 +31,7 @@ Every backend package for Jetconf server has to provide implementation of follow
In addition to this, backend package can also contain any other resources if necessary.
When you consider writing a custom backend, looking at the very basic demo package
jetconf_jukebox_ is a good way to start.
jukebox-jetconf_ is a good way to start.
Handler inheritance
===================
......@@ -224,7 +225,7 @@ state data is the purpose of state data handlers.
A state data handler has to acquire actual state data from backend application and generate data
content of the node where it's assigned. The output data are formatted in Python's representation
of *JSON* (using lists, dicts etc.) and their structure must be compliant with the standardized
JSON encoding of YANG data (see RFC7951_).
JSON encoding of YANG data (RFC7951_).
A state node handler is implemented by creating a custom class which inherits from either
``StateDataContainerHandler`` or ``StateDataListHandler``, depending on the YANG node type.
......@@ -428,6 +429,3 @@ initialization.
act_handlers_obj = ActionHandlersContainer(ds)
ds.handlers.action.register(act_handlers_obj.my_action_handler, "/ns:schema-path/to/action/node")
.. _jetconf_jukebox: https://gitlab.labs.nic.cz/jetconf/jetconf-jukebox
.. _RFC7951: https://tools.ietf.org/html/rfc7951
\ No newline at end of file
.. include:: references.rst
.. _certificates:
***************************
......@@ -50,11 +51,11 @@ 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>`_::
Generate ``ca.key``. see `genrsa <https://www.openssl.org/docs/manmaster/man1/genrsa.html>`_::
$ openssl genrsa -out ca.key 2048
Generate ``ca.pem`` certificate. see `details <https://www.openssl.org/docs/manmaster/man1/openssl-x509.html>`_::
Generate ``ca.pem`` certificate. see `x509 <https://www.openssl.org/docs/manmaster/man1/openssl-x509.html>`_::
$ openssl req -x509 -new -nodes -key ca.key -sha256 -days 1024 -out ca.pem
......@@ -128,5 +129,3 @@ will generate the following files:
- ``joe@example.net_curl.pem`` - the previous 2 files combined and protected by a password. Some utilities, such as curl_, expect the client certificate in this format.
- ``joe@example.net.pfx`` - *PKCS#12* format for browsers. The password is the email address, i.e. ``joe@example.net`` in this case.
.. _OpenSSL: https://www.openssl.org/
.. _curl: https://curl.haxx.se/:
\ No newline at end of file
.. include:: references.rst
.. _configuration:
*********************
......@@ -341,6 +342,3 @@ For instance, configuration required by knot-jetconf_ 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
.. include:: references.rst
.. _developers:
**************
......@@ -73,23 +74,23 @@ and commit the new content of ``requirements.txt``.
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/>`_.
See `PEP 0484`_.
Static Type Checking
--------------------
Later we might use `mypy <http://mypy-lang.org>`_.
Later we might use mypy_.
Currently it doesn't work well will Python 3.5.
Unit Tests
----------
We use `pytest <http://pytest.org>`_.
We use pytest_.
Documentation
-------------
We will use [Sphinx](http://www.sphinx-doc.org/en/stable/) for creating documentation.
We use Sphinx_ 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>`_.
......
.. include:: references.rst
.. _examples:
****************
......@@ -6,16 +7,17 @@ Jetconf Backends
JukeBox
=======
A demo Jetconf backend
A sample Jetconf backend
- `jukebox-jetconf`
- `jukebox-jetconf`_
KnotDNS
=======
- `knot-jetconf`_
***************
Jetconf clients
Jetconf Clients
***************
Useful links:
......@@ -27,12 +29,12 @@ Useful links:
cURL
====
- `cURL site <https://curl.haxx.se/>`_
- `cURL source <https://github.com/curl/curl>`_
- cURL_
- `cURL GitHub`_
A Swiss-knife tool for HTTP/2.
View data in a terminal with curl
View data in a terminal with cURL
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
User's certificate with ``_curl`` suffix in ``.pem`` format is needed.
......@@ -48,8 +50,8 @@ If ``DISABLE_SSL`` and ``CLIENT_CN`` are both set to ``true``, the following com
Jetscreen
=========
- `Public page <https://jetconf.pages.labs.nic.cz/jetscreen>`_
- `Jetscreen source <https://gitlab.labs.nic.cz/jetconf/jetscreen>`_
- `Jetscreen Page`_
- `Jetscreen Source`_
A prototype of an interactive graphical Jetconf client written in Angular 2.
Works only with the JetConf implementation.
......@@ -58,7 +60,7 @@ View data with Jetscreen
^^^^^^^^^^^^^^^^^^^^^^^^
User's certificate in ``.pfx`` format must be imported to the browser.
#. Open public Jetscreen page https://jetconf.pages.labs.nic.cz/jetscreen
#. Open public `Jetscreen Page`_
#. Enter your Jetconf server URL and press *enter* or click the *Reset* button. You may be prompted to select a user certificate.
#. Top-level data containers should then appear.
......
.. include:: references.rst
*******
Jetconf
*******
The `RESTCONF <https://tools.ietf.org/html/rfc8040>`_ protocol implementation written in Python 3.
Jetconf is an implementation of the RESTCONF_ protocol written in
Python 3.
.. toctree::
:maxdepth: 1
......
.. GENERAL:
.. _Jetconf: https://github.com/CZ-NIC/jetconf
.. _GNU GPLv3: https://www.gnu.org/licenses/gpl.html
.. _RESTCONF: https://tools.ietf.org/html/rfc8040
.. _YANGSON: https://github.com/CZ-NIC/yangson
.. _OpenSSL: https://www.openssl.org/
.. 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
.. _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
.. _knot-jetconf: https://github.com/CZ-NIC/knot-jetconf
.. CLIENTS:
.. _Jetscreen Page: https://jetconf.pages.labs.nic.cz/jetscreen
.. _Jetscreen Source: https://gitlab.labs.nic.cz/jetconf/jetscreen
.. _cURL: https://curl.haxx.se/:
.. _cURL GitHub: https://github.com/curl/curl
.. FOR DEVELOPERS:
.. _PEP 0484: https://www.python.org/dev/peps/pep-0484/
.. _mypy: http://mypy-lang.org
.. _pytest: http://pytest.org
.. _Sphinx: http://www.sphinx-doc.org/en/stable/
......
.. include:: references.rst
.. _changelog:
*************
......
.. include:: references.rst
.. _startguide:
************
......@@ -95,9 +96,9 @@ Set up all on your own:
* :ref:`configuration`
* :ref:`certificates`
**********
How to run
**********
***********
Run Jetconf
***********
command line
============
......@@ -107,13 +108,13 @@ All logging information will be displayed in terminal::
systemd integration
===================
systemd
=======
In ``data`` directory there is a simple ``systemd`` service file for Jetconf.
To allow running Jetconf using systemd, this file needs to be copied to ``/etc/systemd/system/``::
cp jetconf@.service /etc/systemd/system/
$ cp jetconf@.service /etc/systemd/system/
Change the user in ``/etc/systemd/system/jetconf@.service`` to yours or create ``jetconf`` user.
......@@ -131,4 +132,4 @@ For ``jukebox`` backend from above::
$ systemctl start jetconf@jukebox.service
.. _Jetconf: https://github.com/CZ-NIC/jetconf
......@@ -11,9 +11,9 @@ setup(
packages=find_packages(),
use_scm_version=True,
setup_requires=["setuptools_scm"],
description="Pure Python implementation of RESTCONF server",
description="Pure Python implementation of the RESTCONF protocol",
long_description=long_description,
url="https://gitlab.labs.nic.cz/labs/jetconf",
url="https://github.com/CZ-NIC/jetconf",
author="Ales Mrazek",
author_email="ales.mrazek@nic.cz",
entry_points={
......@@ -21,10 +21,10 @@ setup(
},
install_requires=["yangson", "h2", "colorlog", "pyaml", "pytz"],
tests_require=["pytest"],
keywords=["RESTCONF", "yang", "data model", "configuration", "json"],
keywords=["restconf", "yang", "data model", "configuration", "json"],
classifiers=[
"Programming Language :: Python",
"Programming Language :: Python :: 3.6",
"Programming Language :: Python :: 3.5",
"Development Status :: 3 - Alpha",
"Intended Audience :: System Administrators",
"Intended Audience :: Telecommunications Industry",
......
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