Jump to: navigation, search

Karaf Distribution Folder and File Guide


This pages attempts to discuss what files and folders you will find in your typical OpenDaylight karaf distribution and what those files and folders are generally used for.

Many of these directories contains a README file which may provide additional information.


The root represents the karaf home directory. You can generally find it under the ../target/assembly directory or you can extract it from a zipped copy in the target directory.


The bin directory contains the scripts required to start the karaf server on either linux/unix or windows. It contains some scripts for setting up your environment and for starting / stopping the karaf instance in a server mode.

In general you will want to start with the "karaf" or "karaf.bat" scripts from which you can start the karaf console in an interactive mode.

[TODO: How to start karaf as a "service" in linux - I thought it was done by passing "start" to the karaf script but that doesn't seem to be the case]

bin/karaf (karaf.bat)

The karaf (or karaf.bat for windows) script contains all of the necessary logic for starting your karaf controller.

  • To start karaf shell in an interactive mode from which you can install features etc simply invoke / run the karaf script.
  • To start karaf shell with remote debugging capability add "debug". Debugging port is by default set to 5005


The configuration folder contains your logback.xml and tomcat-logging properties which allow you to change the logging levels for various bundles at runtime.

[Question: Are these files read and updated at runtime?]

[Question: What is the relationship between /etc/org.ops4j.pax.logging.cfg and configuration/logback.xml]


The data folder is where runtime files are written. For example all of the deployed bundles are cached in this directory by the karaf instance when the bundle or feature is installed. Additionally the data directory contains a log directory which contains the output of all logging in the controller / karaf environment.

This folder will start off essentially empty, but will be populated when the controller starts. The numbered folders correspond to the bundle number.

It *should* be safe to stop the controller, delete this folder, and start again - that will result in all of the bundles being pulled from the system repository again. [TODO: Does anyone have information contrary to this statement?]


The log directory contains the output of the log files (controlled by the logging in the configuration directory) /etc/org.ops4j.pax.logging.cfg.


The deploy folder is used to hot deploy bundles into the controller. This should generally be reserved for DEVELOPMENT ONLY and should not be used in production environments.


The etc directory contains all of the information which configures your controller.

[TODO: Highlight some of the files which are important in configuring ports etc on the controller....]


The opendaylight folder is created under the /etc directory when the controller starts for the first time (or more specifically when bundles are created which contain configuration files for the configuration sub-system). This folder has two child folders: "current" and "karaf".


[TODO: Not sure what is in this folder....]


Karaf contains the configuration sub-system files that are used to start services via the configuration sub-system. These files are deployed from bundles upon their initial installation.

When a feature is uninstalled any configuration files the feature originally deployed are NOT deleted (a manual delete is necessary, when required). Successive feature installs DO NOT over-write existing configuration files of the same name.


Contains the jars and files needed for the root karaf instances to run. See README for more details. Generally speaking you do not need to modify anything in this directory.


This is the default maven repository for this karaf instance. Hence when karaf wants to install a bundle it will look into this folder to find the required bundles. This repository is generally built up as part of the packaging of the karaf distribution. See README for more details.


A simple text file which contains some version and other information about the opendaylight controller version / distribution / environment.