Commit a394bf9d authored by Ales Mrazek's avatar Ales Mrazek

documentation update

parent fee3b4ea
master
======
**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
* simple systemd unit: https://github.com/CZ-NIC/jetconf/blob/master/data/jetconf%40.service
......@@ -5,6 +5,9 @@ Jetconf
Jetconf is an implementation of the RESTCONF_ protocol written in
Python 3.
* `Documentation`_
* `GitHub repository`_
Main features:
* HTTP/2 over TLS, certificate-based authentication of clients
......@@ -16,7 +19,7 @@ Main features:
* Support for NACM_
Requirements
=============
============
Jetconf requires **Python 3.6 or newer**::
......@@ -38,19 +41,19 @@ These requirements should be installed by running *Instalation*
Installation
============
Jetconf can be installed by PyPI::
JetConf can be installed by PyPI::
~$ python3 -m pip install jetconf
$ python3 -m pip install jetconf
Running
=======
Running Jetconf::
Running JetConf::
~$ jetconf -c <path_to_config_file.yaml>
For development purposes, Jetconf can also be started directly
For development purposes, JetConf can also be started directly
from git repository with ``run.py`` script.::
~$ ./run.py -c <path_to_config_file.yaml>
......@@ -67,12 +70,7 @@ In this configuration file, you have to modify all paths to match
your actual file locations.
Links
=====
* `GitHub repository`_
* `Documentation`_
.. _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
.. _Documentation: https://gitlab.labs.nic.cz/labs/jetconf/wikis/home
.. _Documentation: https://jetconf.readthedocs.io
.. _architecture:
************
Architecture
************
.. _backendapi:
***********
Backend API
***********
\ No newline at end of file
.. _backends:
********
Backends
********
==============
Jukebox (demo)
==============
=======
KnotDNS
=======
\ No newline at end of file
.. _certificates:
***************************
Generating SSL Certificates
***************************
This tutorial explains how to generate self-signed certificates for the Jetconf server
and clients using OpenSSL_. Example certificates can be found in ``data`` subdirectory.
.. warning::
Self-signed certificates are of course not considered trustworthy
by web browsers and operating systems, so they are only suitable for testing.
Two bash scripts to help generate SSL certificates are placed in ``/utils/cert_gen`` directory
* ``gen_server_cert.sh`` is used once for generating the server certificate.
* ``gen_client_cert.sh`` is used repeatedly for creating client certificates.
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.
::
apt-get install openssl
Certification Authority
=======================
The generated server and client certificates have to be signed by a Certification Authority (CA).
For testing purposes, though, a self-signed CA-like certificate will do.
.. warning::
For production uses, a trusted CA should always be used.
The easiest, but least secure, way is to use the pre-generated CA-like certificate and
private key from the files ``ca.pem`` and ``ca.key`` available from the ``utils/cert_gen`` directory.
Alternatively, the CA-like certificate and key can be generated using the procedure below.
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>`_.
::
~$ 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
Some parameters of the certificate have to be filled in.
They are not terribly important for testing purposes. For example::
Country Name (2 letter code) [AU]:CZ
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Example CA
Organizational Unit Name (eg, section) []:exca.cz
Common Name (e.g. server FQDN or YOUR name) []:mail@exca.cz
Email Address []:mail@exca.cz
Server Certificate
==================
To generate a new server certificate for JetConf that will be accepted even by
the more pedantic web browsers like Chrome, just run the provided
``gen_server_cert.sh`` script.
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>
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>
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.
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
If you want this certificate to be accepted by your web browser,
the issuing CA's certificate needs to be imported to your browser.
.. warning::
It is strongly recommended to do not import the provided CA's
certificate ``ca.pem`` to your production browser, as its private key is
publicly known. If you do so, someone could perform a MITM attack to
any connection with an SSL-protected website.
Client Certificate
==================
The ``gen_client_cert.sh`` script is intended for generating client certificates
signed by the previously created CA-like certificate.
The script is used simply as follows::
~$ ./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.
Also, the email address identifies the client to the JetConf server by default.
For example, the command::
~$ ./gen_client_cert.sh joe@example.net
will generate the following files:
- ``joe@example.net.pem`` - the client certificate
- ``joe@example.net.key`` - the client private key
- ``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
.. _clients:
***************
Clients
***************
====
curl
====
=========
JetScreen
=========
\ No newline at end of file
This diff is collapsed.
.. _configuration:
*********************
Configuration options
*********************
.. contents::
:depth: 2
:local:
Common sections
===============
GLOBAL:
-------
Example
^^^^^^^
.. code-block:: yaml
GLOBAL:
TIMEZONE: "Europe/Prague"
LOGFILE: "-"
PIDFILE: "/tmp/jetconf.pid"
PERSISTENT_CHANGES: true
LOG_LEVEL: "info"
LOG_DBG_MODULES: ["usr_conf_data_handlers", "data"]
YANG_LIB_DIR: "yang-data/"
DATA_JSON_FILE: "data.json"
VALIDATE_TRANSACTIONS: true
CLIENT_CN: false
BACKEND_PACKAGE: "jetconf_jukebox"
Options
^^^^^^^
.. code-block:: yaml
TIMEZONE:
*Default:* ``"GMT"``
A timezone of the Jetconf server.
This is necessary because all timestamps returned in HTTP response headers need to be returned in GMT.
.. code-block:: yaml
LOGFILE:
*Default:* ``"-"``
A location of Jetconf's log file. This can be either a ``path`` on the filesystem or a ``-``.
If configured as a ``-``, Jetconf server will run in foreground and all logging information will
be written to stdout (suitable for testing).
.. code-block:: yaml
PIDFILE:
*Default:* ``"/tmp/jetconf.pid"``
A location of Jetconf's process ID file.
.. code-block:: yaml
PERSISTENT_CHANGES:
*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
off for i.e. testing purposes. If turned off, the Jetconf datastore will contain exactly the same initial
data at every startup.
.. code-block:: yaml
LOG_LEVEL:
*Default:* ``"info"``
Defines the Jetconf's log verbosity. Possible values are: ``debug``, ``info``, ``warning`` and ``error``.
.. code-block:: yaml
LOG_DBG_MODULES:
*Default:* ``[*]``
When ``LOG_LEVEL`` is set to "debug", this options defines list of Python modules which will write out debugging information.
This is useful to prevent flooding the log with debugging messages from irrelevant modules.
I.e. when debugging ``"usr_conf_data_handlers"`` module, you may not be interested with debug
information from the ``"nacm"``. Can be set to wildcard ``*``.
.. code-block:: yaml
YANG_LIB_DIR:
*Default:* ``"yang-data/"``
Specifies the location of **YANG library**. This is the directory containing ``*.yang`` files,
it must also contain the ``"yang-library-data.json"`` file with configuration and description of
all present YANG modules.
.. code-block:: yaml
DATA_JSON_FILE:
*Default:* ``"data.json"``
A path to JSON file containing the datastore data. This file will be loaded at Jetconf startup.
If ``PERSISTENT_CHANGES`` option is set to true, all changes made to the datastore will be also stored
to this file.
.. code-block:: yaml
VALIDATE_TRANSACTIONS:
*Default:* ``true``
This option defines if the datastore data should be validated according to
YANG data model after a transaction is commited. It should be set to true except for
testing and debugging purposes.
.. code-block:: yaml
CLIENT_CN:
*Default:* ``false``
If enabled, Jetconf will use ``commonName`` to identify users.
By default Jetconf is using ``emailAddress`` to identify users.
.. code-block:: yaml
BACKEND_PACKAGE:
*Default:* ``"jetconf_jukebox"``
This option selects the package with backend bindings that Jetconf will use.
An exact name of the Python package has to be specified here,
and also the package has to be installed in Python's environment.
HTTP_SERVER:
------------
Example
^^^^^^^
.. code-block:: yaml
HTTP_SERVER:
DOC_ROOT: "doc-root"
DOC_DEFAULT_NAME: "index.html"
API_ROOT: "/restconf"
API_ROOT_STAGING: "/restconf_staging"
SERVER_NAME: "jetconf-h2"
UPLOAD_SIZE_LIMIT: 1
LISTEN_LOCALHOST_ONLY: false
PORT: 8443
DISABLE_SSL: false
SERVER_SSL_CERT: "server.crt"
SERVER_SSL_PRIVKEY: "server.key"
CA_CERT: "ca.pem"
DBG_DISABLE_CERTS: false
Options
^^^^^^^
.. code-block:: yaml
DOC_ROOT:
*Default:* ``"doc-root"``
A root directory where regular files will be placed.
All HTTP GET requests outside ``API_ROOT`` are considered as requests for regular files on filesystem.
.. code-block:: yaml
DOC_DEFAULT_NAME:
*Default:* ``"index.html"``
A default filename in DOC_ROOT and its subdirectories.
.. code-block:: yaml
API_ROOT:
*Default:* ``"/restconf"``
Defines the base URI of RESTCONF data. All requests for resources inside API_ROOT will be considered as RESTCONF requests.
It is usually not needed to change this value. Example: ``"/restconf" -> https://localhost/restconf/ns:some_resouce``
.. code-block:: yaml
API_ROOT_STAGING:
*Default:* ``/restconf_staging``
Same as above, except this is for staging data (data edited by user, but not commited yet).
.. code-block:: yaml
SERVER_NAME:
*Default:* ``"jetconf-h2"``
A value returned in ``"Server: "`` header of HTTP response.
.. code-block:: yaml
UPLOAD_SIZE_LIMIT:
*Default:* ``1``
A maximum size of incoming data in ``PUT`` or ``POST`` body (in **megabytes**), which the server can handle.
.. code-block:: yaml
LISTEN_LOCALHOST_ONLY:
*Default:* ``false``
If set to ``true``, the Jetconf HTTP server will only accept incoming connections from *localhost*.
.. code-block:: yaml
PORT:
*Default:* ``8443``
The TCP port of Jetconf server.
.. code-block:: yaml
DISABLE_SSL:
*Default:* ``false``
If enabled, the user authentication system based on client certificates will be turned off and user data
will be parsed from HTTP headers. For instance, this change allows you to run Jetconf behind a
load balancer where the TLS connection is terminated and and http request is forwarded to
Jetconf server with relevant headers. Can be combined with ``DBG_DISABLE_CERT``.
.. code-block:: yaml
SERVER_SSL_CERT:
*Default:* ``"server.crt"``
The location of server SSL certificate in PEM format.
.. code-block:: yaml
SERVER_SSL_PRIVKEY:
*Default:* ``"server.key"``
The location of server SSL private key in PEM format.
.. code-block:: yaml
CA_CERT:
*Default:* ``"ca.pem"``
The location of certification authority certificate, which is used for issuing client certificates.
.. code-block:: yaml
DBG_DISABLE_CERTS:
*Default:* ``false``
If enabled, the user authentication system based on client certificates will be turned off
and every incoming connection will default to "test-user" username. This should never be turned
on in real environment, it is only intended for testing and benchmarking purposes
(no HTTP/2 benchmarking tools support client certificates at this moment).
Can be combined with ``DISABLE_SSL``.
NACM:
-----
Example
^^^^^^^
.. code-block:: yaml
NACM:
ENABLED: true
ALLOWED_USERS: ["superuser@example.com", "admin@example.com"]
Options
^^^^^^^
.. code-block:: yaml
ENABLED:
*Default:* ``true``
If set to false, NACM rules will not be applied.
.. code-block:: yaml
ALLOWED_USERS:
*Default:* ``[]``
A list of superusers allowed to edit NACM data. By default no superuser is specified.
Application-specific section
============================
Example
-------
Required by ``"jetconf_knot"`` backend package
.. code-block:: yaml
KNOT:
SOCKET: "/tmp/knot.sock"
.. code-block:: yaml
SOCKET:
*Default:* ``"/tmp/knot.sock"``
A path to KnotDNS control socket.
.. _examples:
****************
Jetconf Backends
****************
JukeBox
=======
KnotDNS
=======
***************
Jetconf clients
***************
Useful links:
- :ref:`certificates`
- :ref:`configuration`
cURL
====
- `cURL site <https://curl.haxx.se/>`_
- `cURL source <https://github.com/curl/curl>`_
A Swiss-knife tool for HTTP/2.
View data in a terminal with curl
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
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
Jetscreen
=========
- `Public page <https://jetconf.pages.labs.nic.cz/jetscreen>`_
- `Jetscreen source <https://gitlab.labs.nic.cz/jetconf/jetscreen>`_
A prototype of an interactive graphical Jetconf client written in Angular 2.
Works only with the JetConf implementation.
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
#. 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.
.. _features:
********
Features
********
curl --http2-prior-knowledge -H "X-SSL-Client-CN: ales.mrazek@nic.cz" -X GET http://localhost:8443/.well-known/host-meta
curl --http2-prior-knowledge -H "X-SSL-Client-CN: ales.mrazek@nic.cz" -X GET http://localhost:8443/restconf/data
\ No newline at end of file
Welcome to JetConf's documentation!
===================================
*******
Jetconf
*******
Contents:
The `RESTCONF <https://tools.ietf.org/html/rfc8040>`_ protocol implementation written in Python 3.
.. toctree::
:maxdepth: 1
:caption: Guides
startguide
certificates
developers
.. toctree::
:maxdepth: 2
:caption: Documentation
architecture
configuration
backendapi
.. toctree::
:maxdepth: 1
releasenotes
.. toctree::
:maxdepth: 1
:caption: Examples
examples
server
Indices and tables
==================
......
.. _changelog:
*************
Release Notes
*************
.. include:: ../NEWS
sphinx-rtd-theme
sphinx
\ No newline at end of file
JetConf Server
==============
hi!
.. _startguide:
************
Installation
************
Requirements
============
Jetconf requires **Python 3.5** or **newer**.
::
~$ apt-get install python3
~$ apt-get install python3-pip
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).
::
~$ pip install jetconf
Latest version - GitHub
=======================
Latest version is the most actual source code available in the Jetconf GitHub repository in ``master`` branch.
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
*************
Configuration
*************
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