+.. _netconf-user-guide:
+
NETCONF User Guide
==================
- `RFC-6022 <https://tools.ietf.org/html/rfc6022>`__
+- `draft-ietf-netconf-yang-library-06 <https://tools.ietf.org/html/draft-ietf-netconf-yang-library-06>`__
+
**Netconf-connector is fully model-driven (utilizing the YANG modeling
language) so in addition to the above RFCs, it supports any
data/RPC/notifications described by a YANG model that is implemented by
the device.**
- **Tip**
+.. tip::
NETCONF southbound can be activated by installing
``odl-netconf-connector-all`` Karaf feature.
**For such devices you only need to put the schema into folder
cache/schema inside your Karaf distribution.**
- **Important**
+.. important::
The file with YANG schema for ietf-inet-types has to be called
ietf-inet-types@2010-09-24.yang. It is the required naming format of
new NETCONF connectors both through the NETCONF server for MD-SAL (port
2830) or RESTCONF. This guide focuses on RESTCONF.
- **Tip**
+.. tip::
To enable NETCONF connector configuration through MD-SAL install
either the ``odl-netconf-topology`` or
DELETE http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/new-netconf-device
+Connecting to a device supporting only NETCONF 1.0
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+OpenDaylight is schema-based distribution and heavily depends on YANG
+models. However some legacy NETCONF devices are not schema-based and
+implement just RFC 4741. This type of device does not utilize YANG
+models internally and OpenDaylight does not know how to communicate
+with such devices, how to validate data, or what the semantics of data
+are.
+
+NETCONF connector can communicate also with these devices, but the
+trade-offs are worsened possibilities in utilization of NETCONF
+mountpoints. Using RESTCONF with such devices is not suported. Also
+communicating with schemaless devices from application code is slightly
+different.
+
+To connect to schemaless device, there is a optional configuration option
+in netconf-node-topology model called schemaless. You have to set this
+option to true.
+
Clustered NETCONF connector
~~~~~~~~~~~~~~~~~~~~~~~~~~~
To spawn NETCONF connectors that are cluster-aware you need to install
the ``odl-netconf-clustered-topology`` karaf feature.
- **Warning**
+.. warning::
The ``odl-netconf-topology`` and ``odl-netconf-clustered-topology``
features are considered **INCOMPATIBLE**. They both manage the same
Should return 200 response code with no body.
- **Tip**
+.. tip::
This call is transformed into a couple of NETCONF RPCs. Resulting
NETCONF RPCs that go directly to the device can be found in the
- Serves as an alternative interface for MD-SAL (besides RESTCONF)
and allows users to read/write data from MD-SAL’s datastore and to
invoke its rpcs (NETCONF notifications are not available in the
- Beryllium release of OpenDaylight)
+ Boron release of OpenDaylight)
.. note::
different approach for NETCONF message handling and data
translation. These 2 components will probably merge in the future.
+.. note::
+
+ Since Nitrogen release, there is performance regression in NETCONF
+ servers accepting SSH connections. While opening a connection takes
+ less than 10 seconds on Carbon, on Nitrogen time can increase up to
+ 60 seconds. Please see https://bugs.opendaylight.org/show_bug.cgi?id=9020
+
NETCONF server for config-subsystem
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- `RFC-6470 <https://tools.ietf.org/html/rfc6470>`__
- (partially, only the schema-change notification is available in
- Beryllium release)
+ Boron release)
- `RFC-6022 <https://tools.ietf.org/html/rfc6022>`__
- `RFC-6022 <https://tools.ietf.org/html/rfc6022>`__
-Notifications over NETCONF are not supported in the Beryllium release.
+- `draft-ietf-netconf-yang-library-06 <https://tools.ietf.org/html/draft-ietf-netconf-yang-library-06>`__
- **Tip**
+Notifications over NETCONF are not supported in the Boron release.
+
+.. tip::
Install NETCONF northbound for MD-SAL by installing feature:
``odl-netconf-mdsal`` in karaf. Default binding port is **2830**.
These jars are part of OpenDaylight’s controller project and are built
from the NETCONF codebase in OpenDaylight.
- **Tip**
+.. tip::
Download testtool from OpenDaylight Nexus at:
- https://nexus.opendaylight.org/content/repositories/public/org/opendaylight/netconf/netconf-testtool/1.0.2-Beryllium-SR2/
+ https://nexus.opendaylight.org/content/repositories/public/org/opendaylight/netconf/netconf-testtool/1.1.0-Boron/
**Nexus contains 3 executable tools:**
- perf-client.jar - RESTCONF stress/performance measuring tool
- **Tip**
+.. tip::
Each executable tool provides help. Just invoke ``java -jar
<name-of-the-tool.jar> --help``
Netconf-testtool is now part of default maven build profile for
controller and can be also downloaded from nexus. The executable jar for
testtool can be found at:
-`nexus-artifacts <https://nexus.opendaylight.org/content/repositories/public/org/opendaylight/netconf/netconf-testtool/1.0.2-Beryllium-SR2/>`__
+`nexus-artifacts <https://nexus.opendaylight.org/content/repositories/public/org/opendaylight/netconf/netconf-testtool/1.1.0-Boron/>`__
Running testtool
^^^^^^^^^^^^^^^^
http://localhost:8181/restconf/operational/network-topology:network-topology/topology/topology-netconf/node/17830-sim-device/yang-ext:mount/
- **Warning**
+.. warning::
Data will be mirrored in operational datastore only when using the
default simple datastore.
Very similar to NETCONF stress tool with the difference of using
RESTCONF protocol instead of NETCONF.
+YANGLIB remote repository
+-------------------------
+
+There are scenarios in NETCONF deployment, that require for a centralized
+YANG models repository. YANGLIB plugin provides such remote repository.
+
+To start this plugin, you have to install odl-yanglib feature. Then you
+have to configure YANGLIB either through RESTCONF or NETCONF. We will
+show how to configure YANGLIB through RESTCONF.
+
+YANGLIB configuration through RESTCONF
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You have to specify what local YANG modules directory you want to provide.
+Then you have to specify address and port whre you want to provide YANG
+sources. For example, we want to serve yang sources from folder /sources
+on localhost:5000 adress. The configuration for this scenario will be
+as follows:
+
+::
+
+ PUT http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/module/yanglib:yanglib/example
+
+Headers:
+
+- Accept: application/xml
+
+- Content-Type: application/xml
+
+Payload:
+
+::
+
+ <module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
+ <name>example</name>
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:yanglib:impl">prefix:yanglib</type>
+ <broker xmlns="urn:opendaylight:params:xml:ns:yang:controller:yanglib:impl">
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">prefix:binding-broker-osgi-registry</type>
+ <name>binding-osgi-broker</name>
+ </broker>
+ <cache-folder xmlns="urn:opendaylight:params:xml:ns:yang:controller:yanglib:impl">/sources</cache-folder>
+ <binding-addr xmlns="urn:opendaylight:params:xml:ns:yang:controller:yanglib:impl">localhost</binding-addr>
+ <binding-port xmlns="urn:opendaylight:params:xml:ns:yang:controller:yanglib:impl">5000</binding-port>
+ </module>
+
+This should result in a 2xx response and new YANGLIB instance should be
+created. This YANGLIB takes all YANG sources from /sources folder and
+for each generates URL in form:
+
+::
+
+ http://localhost:5000/schemas/{modelName}/{revision}
+
+On this URL will be hosted YANG source for particular module.
+
+YANGLIB instance also write this URL along with source identifier to
+ietf-netconf-yang-library/modules-state/module list.
+
+Netconf-connector with YANG library as fallback
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There is an optional configuration in netconf-connector called
+yang-library. You can specify YANG library to be plugged as additional
+source provider into the mount's schema repository. Since YANGLIB
+plugin is advertising provided modules through yang-library model, we
+can use it in mount point's configuration as YANG library. To do this,
+we need to modify the configuration of netconf-connector by adding this
+XML
+
+::
+
+ <yang-library xmlns="urn:opendaylight:netconf-node-topology">
+ <yang-library-url xmlns="urn:opendaylight:netconf-node-topology">http://localhost:8181/restconf/operational/ietf-yang-library:modules-state</yang-library-url>
+ <username xmlns="urn:opendaylight:netconf-node-topology">admin</username>
+ <password xmlns="urn:opendaylight:netconf-node-topology">admin</password>
+ </yang-library>
+
+This will register YANGLIB provided sources as a fallback schemas for
+particular mount point.
+
+NETCONF Call Home
+-----------------
+
+.. important::
+
+ The call home feature is experimental and will change in a future
+ release. In particular, the Yang models will change to those specified
+ in the `RFC 8071 <https://tools.ietf.org/html/rfc8071>`__
+
+Call Home Installation
+~~~~~~~~~~~~~~~~~~~~~~
+
+ODL Call-Home server is installed in Karaf by installing karaf feature
+``odl-netconf-callhome-ssh``. RESTCONF feature is recommended for
+configuring Call Home & testing its functionality.
+
+::
+
+ feature:install odl-netconf-callhome-ssh
+
+
+.. note::
+
+ In order to test Call Home functionality we recommend Netopeer.
+ See `Netopeer Call Home <https://github.com/CESNET/netopeer/wiki/CallHome>`__ to learn how to enable call-home on Netopeer.
+
+Northbound Call-Home API
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The northbound Call Home API is used for administering the Call-Home Server. The
+following describes this configuration.
+
+Global Configuration
+^^^^^^^^^^^^^^^^^^^^
+
+Configuring global credentials
+''''''''''''''''''''''''''''''
+
+ODL Call-Home server allows user to configure global credentials, which
+will be used for devices which does not have device-specific credentials
+configured.
+
+This is done by creating
+``/odl-netconf-callhome-server:netconf-callhome-server/global/credentials``
+with username and passwords specified.
+
+*Configuring global username & passwords to try*
+
+.. code-block:: http
+
+ PUT
+ /restconf/config/odl-netconf-callhome-server:netconf-callhome-server/global/credentials HTTP/1.1
+ Content-Type: application/json
+ Accept: application/json
+
+.. code-block:: json
+
+ {
+ "credentials":
+ {
+ "username": "example",
+ "passwords": [ "first-password-to-try", "second-password-to-try" ]
+ }
+ }
+
+Configuring to accept any ssh server key using global credentials
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+By default Netconf Call-Home Server accepts only incoming connections
+from allowed devices
+``/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices``,
+if user desire to allow all incoming connections, it is possible to set
+``accept-all-ssh-keys`` to ``true`` in
+``/odl-netconf-callhome-server:netconf-callhome-server/global``.
+
+The name of this devices in ``netconf-topology`` will be in format
+``ip-address:port``. For naming devices see Device-Specific
+Configuration.
+
+*Allowing unknown devices to connect*
+
+This is a debug feature and should not be used in production. Besides being an obvious
+security issue, this also causes the Call-Home Server to drastically increase its output
+to the log.
+
+.. code-block:: http
+
+ POST
+ /restconf/config/odl-netconf-callhome-server:netconf-callhome-server/global HTTP/1.1
+ Content-Type: application/json
+ Accept: application/json
+
+.. code-block:: json
+
+ {
+ "global": {
+ "accept-all-ssh-keys": "true"
+ }
+ }
+
+Device-Specific Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Allowing Device & Configuring Name
+''''''''''''''''''''''''''''''''''
+
+Netconf Call Home Server uses device provided SSH server key (host key)
+to identify device. The pairing of name and server key is configured in
+``/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices``.
+This list is colloquially called a whitelist.
+
+If the Call-Home Server finds the SSH host key in the whitelist, it continues
+to negotiate a NETCONF connection over an SSH session. If the SSH host key is
+not found, the connection between the Call Home server and the device is dropped
+immediately. In either case, the device that connects to the Call home server
+leaves a record of its presence in the operational store.
+
+*Example of configuring device*
+
+.. code-block:: http
+
+ PUT
+ /restconf/config/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices/device/example HTTP/1.1
+ Content-Type: application/json
+ Accept: application/json
+
+.. code-block:: json
+
+ {
+ "device": {
+ "unique-id": "example",
+ "ssh-host-key": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDHoH1jMjltOJnCt999uaSfc48ySutaD3ISJ9fSECe1Spdq9o9mxj0kBTTTq+2V8hPspuW75DNgN+V/rgJeoUewWwCAasRx9X4eTcRrJrwOQKzb5Fk+UKgQmenZ5uhLAefi2qXX/agFCtZi99vw+jHXZStfHm9TZCAf2zi+HIBzoVksSNJD0VvPo66EAvLn5qKWQD4AdpQQbKqXRf5/W8diPySbYdvOP2/7HFhDukW8yV/7ZtcywFUIu3gdXsrzwMnTqnATSLPPuckoi0V2jd8dQvEcu1DY+rRqmqu0tEkFBurlRZDf1yhNzq5xWY3OXcjgDGN+RxwuWQK3cRimcosH"
+ }
+ }
+
+Configuring Device with Device-specific Credentials
+'''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Call Home Server also allows to configure credentials per device basis,
+this is done by introducing ``credentials`` container into
+device-specific configuration. Format is same as in global credentials.
+
+*Configuring Device with Credentials*
+
+.. code-block:: http
+
+ PUT
+ /restconf/config/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices/device/example HTTP/1.1
+ Content-Type: application/json
+ Accept: application/json
+
+.. code-block:: json
+
+ {
+ "device": {
+ "unique-id": "example",
+ "credentials": {
+ "username": "example",
+ "passwords": [ "password" ]
+ },
+ "ssh-host-key": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDHoH1jMjltOJnCt999uaSfc48ySutaD3ISJ9fSECe1Spdq9o9mxj0kBTTTq+2V8hPspuW75DNgN+V/rgJeoUewWwCAasRx9X4eTcRrJrwOQKzb5Fk+UKgQmenZ5uhLAefi2qXX/agFCtZi99vw+jHXZStfHm9TZCAf2zi+HIBzoVksSNJD0VvPo66EAvLn5qKWQD4AdpQQbKqXRf5/W8diPySbYdvOP2/7HFhDukW8yV/7ZtcywFUIu3gdXsrzwMnTqnATSLPPuckoi0V2jd8dQvEcu1DY+rRqmqu0tEkFBurlRZDf1yhNzq5xWY3OXcjgDGN+RxwuWQK3cRimcosH"
+ }
+ }
+
+Operational Status
+^^^^^^^^^^^^^^^^^^
+
+Once an entry is made into the config side of "allowed-devices", the Call-Home Server will
+populate an corresponding operational device that is the same as the config device but
+has an additional status. By default, this status is *DISCONNECTED*. Once a device calls
+home, this status will change to one of:
+
+*CONNECTED* — The device is currently connected and the NETCONF mount is available for network
+management.
+
+*FAILED_AUTH_FAILURE* — The last attempted connection was unsuccessful because the Call-Home
+Server was unable to provide the acceptable credentials of the device. The device is also
+disconnected and not available for network management.
+
+*FAILED_NOT_ALLOWED* — The last attempted connection was unsuccessful because the device was
+not recognized as an acceptable device. The device is also disconnected and not available for
+network management.
+
+*FAILED* — The last attempted connection was unsuccessful for a reason other than not
+allowed to connect or incorrect client credentials. The device is also disconnected and not
+available for network management.
+
+*DISCONNECTED* — The device is currently disconnected.
+
+Rogue Devices
+'''''''''''''
+
+Devices which are not on the whitelist might try to connect to the Call-Home Server. In
+these cases, the server will keep a record by instantiating an operational device. There
+will be no corresponding config device for these rogues. They can be identified readily
+because their device id, rather than being user-supplied, will be of the form
+"address:port". Note that if a device calls back multiple times, there will only be
+a single operatinal entry (even if the port changes); these devices are recognized by
+their unique host key.
+
+Southbound Call-Home API
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Call-Home Server listens for incoming TCP connections and assumes that the other side of
+the connection is a device calling home via a NETCONF connection with SSH for
+management. The server uses port 6666 by default and this can be configured via a
+blueprint configuration file.
+
+The device **must** initiate the connection and the server will not try to re-establish the
+connection in case of a drop. By requirement, the server cannot assume it has connectivity
+to the device due to NAT or firewalls among others.
Code Review / docs.git / blobdiff