--- /dev/null
+.. _dist-test-features:
+
+Distribution features
+=====================
+
+Overview
+--------
+
+This section provides an overview of **odl-integration-compatible-with-all**
+and **odl-integration-all** features.
+
+Integration/Distribution project produces a Karaf 4 distribution
+which gives users access to many Karaf features provided by upstream OpenDaylight projects.
+Users are free to install arbitrary subset of those features,
+but not every feature combination is expected to work properly.
+
+Some features are pro-active, which means OpenDaylight in contact with othe network elements
+starts diving changes in the network even without prompting by users,
+in order to satisfy initial conditions their use case expects.
+Such activity from one feature may in turn affect behavior of another feature.
+
+In some cases, there exists features which offer diferent implementation of the same service,
+they may fail to initialize properly (e.g. failing to bind a port already bound by the other feature).
+
+Integration/Test project is maintaining system tests (CSIT) jobs.
+Aside of testing scenarios with only a minimal set of features installed (-only- jobs),
+the scenarios are also tested with a large set of features installed (-all- jobs).
+
+In order to define a proper set of features to test with, Integration/Distribution project
+defines two "aggregate" features. Note that these features are not intended for production use,
+so the feature repository which defines them is not enabled by default.
+
+The content of these features is determined by upstream OpenDaylight contributions,
+with Integration/Test providing insight on observed compatibuility relations.
+Integration/Distribution team is focused only on making sure the build process is reliable.
+
+Feature repositories
+--------------------
+
+features-index
+~~~~~~~~~~~~~~
+
+This feature repository is enabled by default.
+It does not refer to any new features directly, instead it refers to upstream feature repositories,
+enabling any feature contained therein to be available for installation.
+
+features-test
+~~~~~~~~~~~~~
+
+This feature repository defines the two aggregate features.
+To enable this repository, change the featuresRepositories line of org.apache.karaf.features.cfg file,
+by copy-pasting the feature-index value and editing the name.
+
+Karaf features
+--------------
+
+The two aggregate features, defining sets of user-facing features defined by compatibility requirements.
+Note that is the compatibility relation differs between single node an cluster deployments,
+single node point of view takes precedence.
+
+odl-integration-all
+~~~~~~~~~~~~~~~~~~~
+
+This feature contains the largest set of user-facing features which may affect each others operation,
+but the set does not affect usability of Karaf infrastructure.
+
+Note that port binding conflicts and "server is unhealthy" status of config subsystem
+are considered to affect usability, as is a failure of Restconf
+to respond to GET on /restconf/modules with HTTP status 200.
+
+This feature is used in verification process for Integration/Distribution contributions.
+
+odl-integration-compatible-with-all
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This feature contains the largest set of user-facing features which are not pro-active
+and do not affect each others operation.
+
+Installing this set together with just one of odl-integration-all features should still result
+in fully operational installation, as one pro-active feature should not lead to any conflicts.
+This should also hold if the single added feature is outside odl-integration-all,
+if it is one of conflicting implementations (and no such implementations is in odl-integration-all).
+
+This feature is used in the aforementioned -all- CSIT jobs.
daexim-developer-guide
didm-developer-guide
distribution-version
+ distribution-test-features
dlux
eman-developer-guide
fabric-as-a-service
--- /dev/null
+========================
+Integration/Distribution
+========================
+
+Major Features
+==============
+
+odl-integration-all
+-------------------
+
+* **Gitweb URL:** https://git.opendaylight.org/gerrit/gitweb?p=integration/distribution.git;a=blob;f=features/singles/odl-integration-all/pom.xml;h=c3df09e8828ff16299d96f82e78b1901de1a60ca;hb=refs/heads/stable/nitrogen
+* **Description:** An aggregate feature grouping all user-facing ODL features
+ which can be installed together without Karaf becoming unusable or without port conflicts.
+* **Top Level:** Yes.
+* **User Facing:** Yes, but not intended for production use (only for testing purposes).
+* **Experimental:** No.
+* **CSIT Test:** https://jenkins.opendaylight.org/releng/job/distribution-deploy-nitrogen
+
+odl-integration-compatible-with-all
+-----------------------------------
+
+* **Gitweb URL:** https://git.opendaylight.org/gerrit/gitweb?p=integration/distribution.git;a=blob;f=features/singles/odl-integration-compatible-with-all/pom.xml;h=5ddd52a15cdc658ed18f4647469666b8c849cf4c;hb=refs/heads/stable/nitrogen
+* **Description:** An aggregate feature grouping all user-facing ODL features
+ which are not pro-active and which (as a group) should be compatible with most other ODL features.
+* **Top Level:** Yes.
+* **User Facing:** Yes, but not intended for production use (only for testing purposes).
+* **Experimental:** No.
+* **CSIT Test:** https://jenkins.opendaylight.org/releng/job/distribution-csit-1node-userfeatures-all-nitrogen
+
+odl-distribution-version
+------------------------
+
+* **Gitweb URL:** https://git.opendaylight.org/gerrit/gitweb?p=integration/distribution.git;a=blob;f=features/singles/odl-distribution-version/pom.xml;h=b504cbeb6889379492d33322f1c5cfa488a207a4;hb=refs/heads/stable/nitrogen
+* **Description:** Allows NETCONF/RESTCONF users to determine the version of ODL they are communicating with.
+* **Top Level:** Yes.
+* **User Facing:** Yes.
+* **Experimental:** No.
+* **CSIT Test:** https://jenkins.opendaylight.org/releng/job/distribution-csit-1node-userfeatures-all-nitrogen
+
+Karaf 4 distribution archive
+----------------------------
+* **Gitweb URL:** https://git.opendaylight.org/gerrit/gitweb?p=integration/distribution.git;a=blob;f=karaf/pom.xml;h=082fd09a2467e02e4303f8a5ce0bd42b48ad0267;hb=refs/heads/stable/nitrogen
+* **Description:** Zip or tar.gz; when extracted, a self-consistent ODL installation is created.
+* **Top Level:** Yes.
+* **User Facing:** Yes.
+* **Experimental:** No.
+* **CSIT Test:** https://jenkins.opendaylight.org/releng/job/distribution-deploy-nitrogen
+
+Documentation
+=============
+
+* **Getting Started Guide**
+
+ * :ref:`Clustering scripts <getting-started-clustering-scripts>`
+ * :ref:`Distribution version <getting-started-opendaylight-version>`
+
+* **User Guide:**
+
+ * :ref:`Distribution version <user-guide-dist-version>`
+
+* **Developer Guide**
+
+ * :ref:`Test features <developer-guide-dist-test-features>`
+ * :ref:`Distribution version <developer-guide-dist-version>`
+
+Security Considerations
+=======================
+
+* Karaf 4 exposes ssh console on port 8101.
+ The security basically basically the same as in upstream Karaf of corresponding versions,
+ except library version overrides implemented in odlparent:karaf-parent.
+
+ See :ref:`securing-karaf`
+
+ There is `Bug 9044 <https://bugs.opendaylight.org/show_bug.cgi?id=9044>` which limits
+ accessibility of karaf console over SSH after restart.
+
+* `Sonar Report <https://sonar.opendaylight.org/overview?id=61911>`_ (0%)
+
+ * Only 42 lines of java `code <https://git.opendaylight.org/gerrit/gitweb?p=integration/distribution.git;a=tree;f=version/src/main/java/org/opendaylight/yang/gen/v1/urn/opendaylight/params/xml/ns/yang/integration/distribution/version/rev160316;h=517b2d5a2e726b77360389a20ad8cd8b1a0a6a46;hb=refs/heads/stable/nitrogen>`_.
+
+* `Test report page <https://wiki.opendaylight.org/view/Integration/Distribution/Nitrogen_Test_Report>`_
+
+* No additional manual testing was needed.
+
+Migration
+---------
+
+* Version feature works exactly the same as in Carbon.
+ After migration the versions are set to the new default, configurable in runtime or via configfile.
+ The Carbon configfile would work, but users are strongly advised to consider reporting the migrated versions.
+* No upgrade path for other major features.
+
+Compatibility
+-------------
+
+* Multiple API changes, as Nitrogen is Karaf 4 while Carbon was Karaf 3.
+* Even odl-distribution-version depends on different version of Config Subsystem.
+* Only cluster configuration scripts remained compatible.
+
+Bugs Fixed
+----------
+
+None since Carbon SR1 release.
+
+Known Issues
+------------
+
+* `Bug 9044 <https://bugs.opendaylight.org/show_bug.cgi?id=9044>`_
+
+** The ssh-dss method is used by Karaf SSH console, but no longer supported by clients such as OpenSSH.
+
+*** **Workaround:** Use the bin/client script, which uses karaf:karaf as the default credentials.
+
+** After restart, Karaf is unable to re-use the generated host.key file.
+
+*** **Workaround** Delete the etc/host.key file before starting Karaf again.
+
+* `Bug 9161 <https://bugs.opendaylight.org/show_bug.cgi?id=9161>`_
+
+** Karaf is slow to start processing features after start.
+
+*** **Workaround:** Use a wait loop to continue only when OpenDaylight starts restonding correctly
+ to requests to the desired northbound interface.
+ If no OpenDaylight feature is installed, use bin/client in the wait loop
+ until Karaf SSH console starts responding.
+
+End-of-life
+===========
+
+* All APIs and functionalities related to Karaf 3 were removed.
+ Only Karaf 4 (or higher) will be supported from now on.
+
+Standards
+=========
+
+No standard implemented directly (see upstream projects).
+
+Release Mechanics
+=================
+
+* `Release plan <https://wiki.opendaylight.org/view/Integration/Distribution/Nitrogen_Release_Plan>`_
+
+* Major shifts in release schedule
+
+ * Upstream OpenDaylight projects were slow to controbute their Karaf 4 features and debug them when needed.
+ * While project deliverables were relatively on time, wiki updates were late,
+ and documentation and milestone report were extremely late.
+++ /dev/null
-========================
-Integration/Distribution
-========================
-
-Major Features
-==============
-
-odl-integration-all
--------------------
-
-* **Gitweb URL:** https://git.opendaylight.org/gerrit/gitweb?p=integration/distribution.git;a=blob;f=features3-test/src/main/features/features.xml;hb=refs/heads/stable/carbon
-* **Description:** An aggregate feature grouping all user-facing ODL features
- which can be installed together without Karaf becoming unusable or without port conflicts.
-* **Top Level:** Yes
-* **User Facing:** No (CSIT purposes only)
-* **Experimental:** No
-* **CSIT Test:** https://jenkins.opendaylight.org/releng/view/distribution/job/distribution-deploy-carbon
-
-odl-integration-compatible-with-all
------------------------------------
-
-* **Gitweb URL:** https://git.opendaylight.org/gerrit/gitweb?p=integration/distribution.git;a=blob;f=features3-test/src/main/features/features.xml;hb=refs/heads/stable/carbon
-* **Description:** An aggregate feature grouping all user-facing ODL features
- which are not pro-active and which (as a group) should be compatible with most other ODL features.
-* **Top Level:** Yes
-* **User Facing:** No (CSIT purposes only)
-* **Experimental:** No
-* **CSIT Test:** https://jenkins.opendaylight.org/releng/view/distribution/job/distribution-csit-1node-userfeatures-all-carbon
-
-odl-distribution-version
-------------------------
-
-* **Gitweb URL:** https://git.opendaylight.org/gerrit/gitweb?p=integration/distribution.git;a=blob;f=features3-distribution/src/main/features/features.xml;hb=refs/heads/stable/carbon
-* **Description:** Allows NETCONF/RESTCONF users to determine the version of ODL they are communicating with.
-* **Top Level:** Yes
-* **User Facing:** Yes
-* **Experimental:** No
-* **CSIT Test:** https://jenkins.opendaylight.org/releng/view/distribution/job/distribution-csit-1node-userfeatures-only-carbon
-
-Karaf 3 distribution archive
-----------------------------
-* **Gitweb URL:** https://git.opendaylight.org/gerrit/gitweb?p=integration/distribution.git;a=blob;f=distribution-karaf/pom.xml;hb=refs/heads/stable/carbon
-* **Description:** Zip or tar.gz; when extracted, a self-consistent ODL installation is created.
-* **Top Level:** Yes
-* **User Facing:** Yes
-* **Experimental:** No
-* **CSIT Test:** https://jenkins.opendaylight.org/releng/view/distribution/job/distribution-offline-carbon
-
-Karaf 4 distribution archive
-----------------------------
-* **Gitweb URL:** https://git.opendaylight.org/gerrit/gitweb?p=integration/distribution.git;a=blob;f=karaf/pom.xml;hb=refs/heads/stable/carbon
-* **Description:** Zip or tar.gz; when extracted, a self-consistent ODL installation is created.
-* **Top Level:** Yes
-* **User Facing:** Yes
-* **Experimental:** Yes
-* **CSIT Test:** Removed to save resources.
-
-Documentation
-=============
-
-* **User Guide:**
-
- * :ref:`Clustering scripts <getting-started-clustering-scripts>`
-
-* **Developer Guide:**
-
- * :ref:`dist-version`
-
-Security Considerations
-=======================
-
-* Karaf 3 exposes ssh console on port 8101.
- The security basically basically the same as in upstream Karaf of corresponding versions,
- except library version overrides implemented in odlparent:karaf-parent.
-
- See :ref:`securing-karaf`
-
-Quality Assurance
-=================
-
-* `Sonar Report <https://sonar.opendaylight.org/overview?id=61911>`_ (0%)
-
- * Only 42 lines of java `code <https://git.opendaylight.org/gerrit/gitweb?p=integration/distribution.git;a=tree;f=version/src/main/java/org/opendaylight/yang/gen/v1/urn/opendaylight/params/xml/ns/yang/integration/distribution/version/rev160316;hb=refs/heads/stable/carbon>`_.
-
-* `Test report page <https://wiki.opendaylight.org/view/Integration/Distribution/Carbon_Test_Report>`_
-* No additional manual testing.
-
-Migration
----------
-
-* Version feature works exactly the same as in Boron.
- After migration the versions are set to the new default, configurable in runtime or via configfile.
- The Boron configfile would work, but users are advised to consider reporting a bumped version.
-* No upgrade path for other features.
-
-Compatibility
--------------
-
-* No API changes in Karaf 3.
-* Karaf features are not compatible with Boron.
-
- * even odl-distribution-version depends on different version of Config Subsystem.
-
-Bugs Fixed
-----------
-
-* `Bug 4296 <https://bugs.opendaylight.org/show_bug.cgi?id=4296>`_:
- At the time of Boron release, the default versions were not being set properly. Now they are.
-* `Bug 7255 <https://bugs.opendaylight.org/show_bug.cgi?id=7255>`_:
- During Carbon deveopment -all- jobs for NETCONF started to fail.
- Turns out NETCONF provides two NETCONF topology managers (single node or cluster)
- which are incompatible with each other.
- Fixed by moving both out of odl-integration-compatible-with-all.
-* `Bug 7493 <https://bugs.opendaylight.org/show_bug.cgi?id=7493>`_:
- Controller briefly used Artery, but distribution scripts were not compatible with that.
- After all, Artery is not used in Carbon release,
- but the scripts now contain information how to make them compatible if needed.
-* `Bug 4219 <https://bugs.opendaylight.org/show_bug.cgi?id=4219>`_:
- Karaf 4 features and archives are available, but in experimental state only.
- NETCONF server and NETCONF connectors do not work. RESTCONF works only up to attempted re-install.
-
-
-Known Issues
-------------
-
-* No known issues for Karaf 3.
-* Karaf 4 is highly experimental.
-
-End-of-life
-===========
-
-No features/APIs which are EOLed, deprecated, and/or removed in this release.
-
-Standards
-=========
-
-No standard implemented directly (see upstream projects).
-
-Release Mechanics
-=================
-
-* `Release plan <https://wiki.opendaylight.org/view/Integration/Distribution/Carbon_Release_Plan>`_
-* Major shifts in release schedule
-
- * Karaf 4 was running late due to difficulty of making CSIT work.
- Eventually Karaf 4 was moved to experimental status.
- * Team Lead was often busy, neglecting status updates.
* Is it possible to migrate from the previous release? If so, how?
- N/A as this is first release
+ Yes, no changes to API
Compatibility
-------------
-N/A as this is first release
+Yes, compatible with other features and the previous release
Bugs Fixed
----------
* List of bugs fixed since the previous release
- N/A as this is first release
+ None
Known Issues
------------
* List key known issues with workarounds
- no known issues
+ No known issues
* Link to Open Bugs
- no open bugs
+ No open bugs
End-of-life
===========
* List of features/APIs which are EOLed, deprecated, and/or removed in this release
- N/A as this is first release
+ None
Standards
=========
* List of standards implemented and to what extent
* `IETF Energy Management (eman) standards. <https://datatracker.ietf.org/wg/eman/charter/>`_
- Only powerMeasurement table currently implemented.
+ Only powerMeasurement table is currently implemented.
Release Mechanics
=================
-* `Link to release plan <https://wiki.opendaylight.org/view/Eman:Carbon_Release_Plan>`_
+* `Link to release plan <https://wiki.opendaylight.org/view/Eman:Nitrogen_Release_Plan>`_
* Describe any major shifts in release schedule from the release plan
None
odl-of-config-all
-----------------
-* **Feature URL:** https://git.opendaylight.org/gerrit/gitweb?p=of-config.git;a=blob;f=features/features-of-config/src/main/features/features.xml;hb=stable/carbon
-* **Feature Description:** This is a top level wrapper feature which includes all the sub features OF-CONFIG offers.
+* **Feature URL:** https://git.opendaylight.org/gerrit/gitweb?p=of-config.git;a=blob;f=features/features-of-config/src/main/features/features.xml;h=86615e2f22ebc8f21b403185d3a600aa2a463588;hb=HEAD
+* **Feature Description:** This is a top level wrapper feature which includes all the sub features of-config offers.
* **Top Level:** Yes
* **User Facing:** Yes
* **Experimental:** Yes
* Other manual testing and QA information
* Testing methodology. How extensive was it? What should be expected to work?
What has not been tested as much?
-* External System Test is almost done manually, since the sandbox environment
- could not satisfy OF-CONFIG's requirement. The test has covered all external
- APIs of OF-CONFIG and all supplementary options based on OF-CONFIG 1.2.
+* External System Test is almost done manually. The test has coverd all external APIs of OF-CONFIG and all supplementary options based on OF-CONFIG 1.2.
Migration
---------
* Is it possible to migrate from the previous release? If so, how?
- There is no additional support for migration in OF-CONFIG than there is in
- general. User configuration and state will need to be manually migrated when
- upgrading between major versions of OpenDaylight.
+Yes, there are no additional steps for migration.
Compatibility
-------------
Bugs Fixed
----------
-* List of bugs fixed since the previous release
-
- `Replace mockito-all by mockito-core <https://git.opendaylight.org/gerrit/#/c/50878/>`_
+None.
Known Issues
------------
Release Mechanics
=================
-* `Link to release plan <https://wiki.opendaylight.org/view/OF-CONFIG:Carbon:Release_Plan>`_
+* `Link to release plan <https://wiki.opendaylight.org/view/OF-CONFIG:Nitrogen:Release_Plan>`_
* Describe any major shifts in release schedule from the release plan
N/A
* **Experimental:** Yes
* **CSIT Test:**
- * https://jenkins.opendaylight.org/releng/view/snmp/job/snmp-csit-1node-basic-all-carbon/
- * https://jenkins.opendaylight.org/releng/view/snmp/job/snmp-csit-1node-basic-only-carbon/
+ * https://jenkins.opendaylight.org/releng/view/snmp/job/snmp-csit-1node-basic-all-nitrogen/
Documentation
=============
* `Link to Sonar Report <https://sonar.opendaylight.org/overview?id=69960>`_ (3.5% code coverage)
* Link to CSIT Jobs:
- * https://jenkins.opendaylight.org/releng/view/snmp/job/snmp-csit-1node-basic-all-carbon/
- * https://jenkins.opendaylight.org/releng/view/snmp/job/snmp-csit-1node-basic-only-carbon/
+ * https://jenkins.opendaylight.org/releng/view/snmp/job/snmp-csit-1node-basic-all-nitrogen/
* Other manual testing and QA information: None
Compatibility
-------------
-Compatible with previous release. No functional change to features
+Compatible with the previous release, no functional change to features
Bugs Fixed
----------
* List of bugs fixed since the previous release
- None. No functional change to features
+ None - no functional change to features
Known Issues
------------
* List of features/APIs which are EOLed, deprecated, and/or removed in this release
- none
+ None
Standards
=========
Release Mechanics
=================
-* `Link to release plan <https://wiki.opendaylight.org/view/SNMP_Plugin:Carbon_Release_Plan>`_
+* `Link to release plan <https://wiki.opendaylight.org/view/SNMP_Plugin:Nitrogen_Release_Plan>`_
* Describe any major shifts in release schedule from the release plan
None
project-release-notes/controller
project-release-notes/daexim-release-notes
project-release-notes/didm
- project-release-notes/distribution
+ project-release-notes/distribution-release-notes
project-release-notes/dluxapps
project-release-notes/docs
project-release-notes/eman
--- /dev/null
+.. _dist-version:
+
+Distribution Version reporting
+==============================
+
+Overview
+--------
+
+This section provides an overview of **odl-distribution-version** feature.
+
+A remote user of OpenDaylight usually has access to RESTCONF and NETCONF
+northbound interfaces, but does not have access to the system
+OpenDaylight is running on. OpenDaylight has released multiple versions
+including Service Releases, and there are incompatible changes between them.
+In order to know which YANG modules to use, which bugs to expect
+and which workarounds to apply, such user would need to know the exact version
+of at least one OpenDaylight component.
+
+There are indirect ways to deduce such version, but the direct way is enabled
+by odl-distribution-version feature. Administrator can specify version strings,
+which would be available to users via NETCONF, or via RESTCONF
+if OpenDaylight is configured to initiate NETCONF connection
+to its config subsystem northbound interface.
+
+By default, users have write access to config subsystem,
+so they can add, modify or delete any version strings present there.
+Admins can only influence whether the feature is installed, and initial values.
+
+Config subsystem is local only, not cluster aware,
+so each member reports versions independently. This is suitable for heterogeneous clusters.
+
+Default config file
+~~~~~~~~~~~~~~~~~~~
+
+Initial version values are set via config file ``odl-version.xml`` which is created in
+``$KARAF_HOME/etc/opendaylight/karaf/`` upon installation of ``odl-distribution-version`` feature.
+If admin wants to use different content, the file with desired content has to be created
+there before feature installation happens.
+
+By default, the config file defines two config modules, named ``odl-distribution-version``
+and ``odl-odlparent-version``.
+
+RESTCONF usage
+~~~~~~~~~~~~~~
+
+Opendaylight config subsystem NETCONF northbound is not made available just by installing
+``odl-distribution-version``, but most other feature installations would enable it.
+RESTCONF interfaces are enabled by installing ``odl-restconf`` feature,
+but that do not allow access to config subsystem by itself.
+
+On single node deployments, installation of ``odl-netconf-connector-ssh`` is recommended,
+which would configure ``controller-config`` device and its MD-SAL mount point.
+
+For cluster deployments, installing ``odl-netconf-clustered-topology`` is recommended.
+See documentation for clustering on how to create similar devices for each member,
+as ``controller-config`` name is not unique in that context.
+
+Assuming single node deployment and user located on the same system,
+here is an example ``curl`` command accessing ``odl-odlparent-version`` config module:
+
+.. code:: bash
+
+ curl 127.0.0.1:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/module/odl-distribution-version:odl-version/odl-odlparent-version
centinel-user-guide
daexim-user-guide
didm-user-guide
+ distribution-version-user-guide
eman-user-guide
fabric-as-a-service
genius-user-guide
Code Review / docs.git / commitdiff