This section discusses the troubleshooting process with respect to the multi-bundle/OSGi aspects of ONOS.
As mentioned in ONOS : An Overview, ONOS is a multi-module project managed as OSGi bundles by Karaf.
Each bundle is represented by a Maven project with its own POM file, and each project may implement zero or more services defined by Java interfaces. The dependencies for a bundle are described by:
@Reference) within the code - interdependencies between various services, used by Karaf to resolve module dependencies during system startup and when loading bundles at runtime
Notably, both prohibit circular references, and the POM file hierarchy, the cross-linking of projects not indicated to be dependencies. As such, the following result in various failure modes:
We focus on the case where the project builds, but does not load properly, as in cases 2 and 4.
Unloaded modules may manifest as failures of certain commands from the Karaf command line, and/or the absence of bundles in the output of
list. As a contrived example, for a system with a circular dependency between two services:
@Reference(cardinality = ReferenceCardinality.MANDATORY_UNARY) protected MastershipService mastershipService;
@Reference(cardinality = ReferenceCardinality.MANDATORY_UNARY) protected DeviceService devService;
One finds that the project builds without errors, but many CLI commands do not work:
onos> roles Service org.onlab.onos.net.device.DeviceService not found
Additionally, in the above case,
list will show that all proper bundles are loaded, as the cyclically dependent Services are just a subset of services exported by
|An example of case 4 may be where one references |
The Karaf runtime may be viewed via the
webconsole Web GUI.
webconsole may be loaded at runtime at the CLI:
onos> feature:install webconsole
Alternatively, it can be loaded by appending
webconsole to featuresBoot in apache-karaf-3.0.2/etc/org.apache.karaf.features.cfg .
To access, point a browser at the machine running karaf (in this example, 192.168.56.20):
At this time, the username/password are the default karaf/karaf. The console should take you to a page displaying all bundles:
Selecting an entry in the list displays more information regarding the bundle, such as imported and exported packages and used services. Bundles may also be stopped, uninstalled, or restarted from here. Two views of particular interest in our case are (accessed from dropdown, highlighted in red above):
Returning to the cyclic dependency example -- While onos-core-trivial appears as installed in the features page:
the interdependent services reveal unmet dependencies (each other) on the Components page.
A similar diagnosis can be used to detect other forms of unmet dependencies, such as a service referencing an implementing class. In the example below, part of the Intent Framework was referencing an implementing class (
LinkResourceManager) instead of the
LinkResourceService. After the codebase was refactored, the service could not be found:
As demonstrated above, cross-referencing the bundles, features, and Components views of
webconsole provides better hints about what is going on than the Karaf CLI.
Previous : Appendix C : Source Tree Organization
Home : Developer's Guide