docs/user-guide/distribution-version-user-guide.rst

   1 .. _dist-version:
   2
   3 Distribution Version reporting
   4 ==============================
   5
   6 Overview
   7 --------
   8
   9 This section provides an overview of **odl-distribution-version** feature.
  10
  11 A remote user of OpenDaylight usually has access to RESTCONF and NETCONF
  12 northbound interfaces, but does not have access to the system
  13 OpenDaylight is running on. OpenDaylight has released multiple versions
  14 including Service Releases, and there are incompatible changes between them.
  15 In order to know which YANG modules to use, which bugs to expect
  16 and which workarounds to apply, such user would need to know the exact version
  17 of at least one OpenDaylight component.
  18
  19 There are indirect ways to deduce such version, but the direct way is enabled
  20 by odl-distribution-version feature. Administrator can specify version strings,
  21 which would be available to users via NETCONF, or via RESTCONF
  22 if OpenDaylight is configured to initiate NETCONF connection
  23 to its config subsystem northbound interface.
  24
  25 By default, users have write access to config subsystem,
  26 so they can add, modify or delete any version strings present there.
  27 Admins can only influence whether the feature is installed, and initial values.
  28
  29 Config subsystem is local only, not cluster aware,
  30 so each member reports versions independently. This is suitable for heterogeneous clusters.
  31
  32 Default config file
  33 ~~~~~~~~~~~~~~~~~~~
  34
  35 Initial version values are set via config file ``odl-version.xml`` which is created in
  36 ``$KARAF_HOME/etc/opendaylight/karaf/`` upon installation of ``odl-distribution-version`` feature.
  37 If admin wants to use different content, the file with desired content has to be created
  38 there before feature installation happens.
  39
  40 By default, the config file defines two config modules, named ``odl-distribution-version``
  41 and ``odl-odlparent-version``.
  42
  43 RESTCONF usage
  44 ~~~~~~~~~~~~~~
  45
  46 OpenDaylight config subsystem NETCONF northbound is not made available just by installing
  47 ``odl-distribution-version``, but most other feature installations would enable it.
  48 RESTCONF interfaces are enabled by installing ``odl-restconf`` feature,
  49 but that do not allow access to config subsystem by itself.
  50
  51 On single node deployments, installation of ``odl-netconf-connector-ssh`` is recommended,
  52 which would configure ``controller-config`` device and its MD-SAL mount point.
  53
  54 For cluster deployments, installing ``odl-netconf-clustered-topology`` is recommended.
  55 See documentation for clustering on how to create similar devices for each member,
  56 as ``controller-config`` name is not unique in that context.
  57
  58 Assuming single node deployment and user located on the same system,
  59 here is an example ``curl`` command accessing ``odl-odlparent-version`` config module:
  60
  61 .. code:: bash
  62
  63     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