X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;ds=sidebyside;f=docs%2Fuser-guide.rst;h=6e34b1de75e7e4c30805f557ed7817e2e07bcab2;hb=b084f152b100fcba165350ac2629ef47e22514d3;hp=49e9cb33ed50f469041b3966010b472fe58a57fc;hpb=1afaf777cb77151f3b04f76854a578fedd046627;p=netconf.git
diff --git a/docs/user-guide.rst b/docs/user-guide.rst
index 49e9cb33ed..6e34b1de75 100644
--- a/docs/user-guide.rst
+++ b/docs/user-guide.rst
@@ -125,7 +125,7 @@ without specifying the node in the URL:
* - rfc8040
- http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf
-Payload:
+Payload for password authentication:
.. tabs::
@@ -153,6 +153,7 @@ Payload:
20000
0
2000
+ 1800000
1.5
120
@@ -181,14 +182,205 @@ Payload:
"netconf-node-topology:username": "admin",
"netconf-node-topology:password": "admin"
},
+ "netconf-node-topology:host": "127.0.0.1",
+ "netconf-node-topology:min-backoff-millis": 2000,
+ "netconf-node-topology:max-backoff-millis": 1800000,
"netconf-node-topology:backoff-multiplier": 1.5,
+ "netconf-node-topology:keepalive-delay": 120
+ }
+ ]
+ }
+
+.. note::
+
+ You have the option to use the 'login-password' configuration for authentication as shown below:
+
+ .. code-block:: json
+
+ "login-password": {
+ "netconf-node-topology:username": "netconf",
+ "netconf-node-topology:password": "c5R3aLBss7J8T2VC3pEeAQ=="
+ }
+
+ In OpenDaylight's configuration, the AAAEncryptionServiceImpl generates a new encryption key with
+ each application build. You can use this method if you have access to the current encryption key.
+ Additionally, it is important to ensure that the entire password is encoded in base64 format and
+ that its length is a multiple of 16 bytes for successful authentication.
+
+There is also option of using key-based authentication instead
+of password. First we need to create key in datastore.
+
+*Adding a client private key credential to the netconf-keystore*
+
+.. code-block::
+
+ POST HTTP/1.1
+ /rests/operations/netconf-keystore:add-keystore-entry
+ Content-Type: application/json
+ Accept: application/json
+
+.. code-block:: json
+
+ {
+ "input": {
+ "key-credential": [
+ {
+ "key-id": "example-client-key-id",
+ "private-key": "PEM-format-private-key",
+ "passphrase": "passphrase"
+ }
+ ]
+ }
+ }
+
+After we can use this key to create connector using this key.
+
+Payload for key-based authentication via SSH:
+
+.. tabs::
+
+ .. tab:: XML
+
+ **Content-type:** ``application/xml``
+
+ **Accept:** ``application/xml``
+
+ **Authentication:** ``admin:admin``
+
+ .. code-block:: xml
+
+
+ new-netconf-device
+ 127.0.0.1
+ 17830
+
+ admin
+ key-id
+
+ false
+
+ false
+ 20000
+ 0
+ 2000
+ 1800000
+ 1.5
+
+ 120
+
+
+ .. tab:: JSON
+
+ **Content-type:** ``application/json``
+
+ **Accept:** ``application/json``
+
+ **Authentication:** ``admin:admin``
+
+ .. code-block:: json
+
+ {
+ "node": [
+ {
+ "node-id": "new-netconf-device",
+ "netconf-node-topology:port": 17830,
+ "netconf-node-topology:reconnect-on-changed-schema": false,
+ "netconf-node-topology:connection-timeout-millis": 20000,
+ "netconf-node-topology:tcp-only": false,
+ "netconf-node-topology:max-connection-attempts": 0,
+ "netconf-node-topology:key-based": {
+ "netconf-node-topology:username": "admin",
+ "netconf-node-topology:key-id": "key-id"
+ },
"netconf-node-topology:host": "127.0.0.1",
"netconf-node-topology:min-backoff-millis": 2000,
+ "netconf-node-topology:max-backoff-millis": 1800000,
+ "netconf-node-topology:backoff-multiplier": 1.5,
"netconf-node-topology:keepalive-delay": 120
}
]
}
+Connecting via TLS protocol is similar to SSH. First setup keystore
+by using three RPCs from `Configure device to connect over TLS protocol`_
+to add a client private key, associate a private key with a client and CA
+certificates chain and add a list of trusted CA and server certificates.
+Only after that we can process and create a new NETCONF connector you need
+to send the following PUT request.
+
+Payload for key-based authentication via TLS:
+
+.. tabs::
+
+ .. tab:: XML
+
+ **Content-type:** ``application/xml``
+
+ **Accept:** ``application/xml``
+
+ **Authentication:** ``admin:admin``
+
+ .. code-block:: xml
+
+
+ new-netconf-device
+ 127.0.0.1
+ 17830
+
+ admin
+ key-id
+
+ false
+
+ false
+ 20000
+ 0
+ 2000
+ 1800000
+ 1.5
+
+ 120
+
+ TLS
+
+
+
+ .. tab:: JSON
+
+ **Content-type:** ``application/json``
+
+ **Accept:** ``application/json``
+
+ **Authentication:** ``admin:admin``
+
+ .. code-block:: json
+
+ {
+ "node": [
+ {
+ "node-id": "new-netconf-device",
+ "netconf-node-topology:port": 17830,
+ "netconf-node-topology:reconnect-on-changed-schema": false,
+ "netconf-node-topology:connection-timeout-millis": 20000,
+ "netconf-node-topology:tcp-only": false,
+ "netconf-node-topology:max-connection-attempts": 0,
+ "netconf-node-topology:key-based": {
+ "netconf-node-topology:username": "admin",
+ "netconf-node-topology:key-id": "key-id"
+ },
+ "netconf-node-topology:host": "127.0.0.1",
+ "netconf-node-topology:min-backoff-millis": 2000,
+ "netconf-node-topology:max-backoff-millis": 1800000,
+ "netconf-node-topology:backoff-multiplier": 1.5,
+ "netconf-node-topology:keepalive-delay": 120,
+ "protocol": {
+ "name": "TLS"
+ }
+ }
+ ]
+ }
+
+
Note that the device name in element must match the last
element of the restconf URL.
@@ -977,7 +1169,48 @@ Preconditions:
- Netopeer is up and running in docker
-Now just follow the section: `Spawning new NETCONF connectors`_.
+Now just follow the section: `Spawning new NETCONF connectors`_ for
+password authentication.
+In the payload change the:
+
+- name, e.g., to netopeer
+
+- username/password to your system credentials
+
+- ip to localhost
+
+- port to 830.
+
+After netopeer is mounted successfully, its configuration can be read
+using RESTCONF by invoking:
+
+GET
+http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=netopeer/yang-ext:mount?content:config
+
+Mounting netopeer NETCONF server using key-based authentication SSH
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Install docker https://docs.docker.com/get-started/
+
+2. Create RSA key pair - it will be user for connection.
+
+3. Start the netopeer image(this command will also copy you pub key
+ into docker container):
+
+ ::
+
+ docker run -dt -p 830:830 -v {path-to-pub-key}:/home/{netopeer-username}/.ssh/authorized_keys sysrepo/sysrepo-netopeer2:latest netopeer2-server -d -v 2
+
+4. Verify netopeer is running by invoking (netopeer should send its
+ HELLO message right away:
+
+ ::
+
+ ssh root@localhost -p 830 -s netconf
+ (password root)
+
+Now just follow the section: `Spawning new NETCONF connectors`_ for
+key-based authentication(SSH) to create device.
In the payload change the:
- name, e.g., to netopeer
@@ -986,7 +1219,61 @@ In the payload change the:
- ip to localhost
-- port to 1831.
+- port to 830.
+
+After netopeer is mounted successfully, its configuration can be read
+using RESTCONF by invoking:
+
+GET
+http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=netopeer/yang-ext:mount?content:config
+
+Mounting netopeer NETCONF server using key-based authentication TLS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Install docker https://docs.docker.com/get-started/
+
+2. Run netopeer2
+
+ ::
+
+ docker pull sysrepo/sysrepo-netopeer2
+ docker run -it --name sysrepo -p 830:830 --rm sysrepo/sysrepo-netopeer2:latest
+
+3. Enable TLS communication on server netopeer2
+
+ ::
+
+ ssh root@localhost -p 830 -s netconf
+ (type password root)
+
+ After successful connecting to netopeer2 setup your
+ TLS configuration xml
+ (See: https://github.com/CESNET/netopeer2/tree/master/example_configuration).
+
+4. Run ODL:
+
+- :~/netconf/karaf/target/assembly/bin$ ./karaf
+
+- feature:install odl-netconf-topology odl-restconf-nb-bierman02 odl-mdsal-apidocs
+
+5. Set up ODL netconf keystore
+
+ To setup keystore is needed to send three RPCs from
+ `Configure device to connect over TLS protocol`_
+ to add a client private key, associate a private key with a client and CA
+ certificates chain and add a list of trusted CA and server certificates.
+
+Now just follow the section: `Spawning new NETCONF connectors`_ for
+key-based authentication(TLS) to create device.
+In the payload change the:
+
+- name, e.g., to netopeer
+
+- username/password to your system credentials
+
+- ip to localhost
+
+- port to 830.
After netopeer is mounted successfully, its configuration can be read
using RESTCONF by invoking:
@@ -1219,6 +1506,7 @@ set:
* ``ping-executor-name-prefix``, which defaults to ``ping-executor``
* ``max-thread-count``, which defaults to ``1``
* ``use-sse``, which defaults to ``true``
+* ``restconf``, which defaults to ``rests``
*maximum-fragment-length* â Maximum web-socket fragment length in number of Unicode code units (characters)
(exceeded message length leads to fragmentation of messages)
@@ -1234,6 +1522,8 @@ set:
*use-sse* â In case of ``true`` access to notification streams will be via Server-Sent Events.
Otherwise web-socket servlet will be initialized.
+*restconf* â The value of RFC8040 restconf URI template, pointing to the root resource. Must not end with '/'.
+
In order to change these settings, you can either modify the corresponding configuration
file, ``org.opendaylight.restconf.nb.rfc8040.cfg``, for example:
@@ -1242,9 +1532,10 @@ file, ``org.opendaylight.restconf.nb.rfc8040.cfg``, for example:
maximum-fragment-length=0
heartbeat-interval=10000
idle-timeout=30000
- ping-executor-name-prefix="ping-executor"
+ ping-executor-name-prefix=ping-executor
max-thread-count=1
use-sse=true
+ restconf=rests
Or use Karaf CLI:
@@ -1257,6 +1548,7 @@ Or use Karaf CLI:
opendaylight-user@root>config:property-set ping-executor-name-prefix "ping-executor"
opendaylight-user@root>config:property-set max-thread-count 1
opendaylight-user@root>config:property-set use-sse true
+ opendaylight-user@root>config:property-set restconf "rests"
opendaylight-user@root>config:update
NETCONF Call Home
@@ -1519,7 +1811,7 @@ storing them within the netconf-keystore.
"key-credential": [
{
"key-id": "example-client-key-id",
- "private-key": "base64encoded-private-key",
+ "private-key": "PEM-format-private-key",
"passphrase": "passphrase"
}
]