Chapter 16. Introduction to the Deploying into Apache Karaf user guide Abstract Before you use this User Guide section of the Deploying into Apache Karaf guide, you must have installed the latest version of Red Hat Fuse, following the instructions in Installing on Apache Karaf . 16.1. Introducing Fuse Configuration The OSGi Configuration Admin service specifies the configuration information for deployed services and ensures that the services receive that data when they are active. 16.2. OSGi configuration A configuration is a list of name-value pairs read from a .cfg file in the FUSE_HOME/etc directory. The file is interpreted using the Java properties file format. The filename is mapped to the persistent identifier (PID) of the service that is to be configured. In OSGi, a PID is used to identify a service across restarts of the container. 16.3. Configuration files You can configure the Red Hat Fuse runtime using the following files: Table 16.1. Fuse Configuration Files Filename Description config.properties The main configuration file for the container. custom.properties The main configuration file for custom properties for the container. keys.properties Lists the users who can access the Fuse runtime using the SSH key-based protocol. The file's contents take the format username = publicKey , role org.apache.karaf.features.repos.cfg The features repository URLs. org.apache.karaf.features.cfg Configures a list of feature repositories to be registered and a list of features to be installed when Fuse starts up for the first time. org.apache.karaf.jaas.cfg Configures options for the Karaf JAAS login module. Mainly used for configuring encrypted passwords (disabled by default). org.apache.karaf.log.cfg Configures the output of the log console commands. org.apache.karaf.management.cfg Configures the JMX system. org.apache.karaf.shell.cfg Configures the properties of remote consoles. org.ops4j.pax.logging.cfg Configures the logging system. org.ops4j.pax.transx.tm.narayana.cfg Narayana transaction manager configuration org.ops4j.pax.url.mvn.cfg Configures additional URL resolvers. org.ops4j.pax.web.cfg Configures the default Undertow container (Web server). See Securing the Undertow HTTP Server in the Red Hat Fuse Apache CXF Security Guide. startup.properties Specifies which bundles are started in the container and their start-levels. Entries take the format bundle = start-level . system.properties Specifies Java system properties. Any properties set in this file are available at runtime using System.getProperties() . users.properties Lists the users who can access the Fuse runtime either remotely or via the web console. The file's contents take the format username = password , role setenv or setenv.bat This file is in the /bin directory. It is used to set JVM options. The file's contents take the format JAVA_MIN_MEM= 512M , where 512M is the minimum size of Java memory. See Section 16.6, "Setting Java Options" for more information. 16.4. Advanced Undertow configuration 16.4.1. IO configuration Since PAXWEB-1255 the configuration of the XNIO worker and buffer pool used by the listeners can be altered. In undertow.xml template there is a section that specifies default values of some IO-related parameters: The following buffer-pool parameters may be specified: buffer-size Specifies size of the buffer used for IO operations. When not specified, size is calculated depending on available memory. direct-buffers Determines whether java.nio.ByteBuffer#allocateDirect or java.nio.ByteBuffer#allocate should be used. The following worker parameters may be specified: io-threads The number of I/O threads to create for the worker. If not specified, the number of threads is set to the number of CPUs x 2. task-core-threads The number of threads for the core task thread pool. task-max-threads The maximum number of threads for the worker task thread pool. If not specified, the maximum number of threads is set to the number of CPUs x 16. 16.4.2. Worker IO configuration The Undertow thread pools and their names can be configured on a per-service or bundle basis which helps to make monitoring from Hawtio console and debugging more efficient. In the bundle blueprint configuration file (which is typically stored under the src/main/resources/OSGI-INF/blueprint directory in a Maven project), you can configure the workerIOName and ThreadPool as demonstrated in the following example. Example 16.1. httpu:engine-factory element with workerIOName and ThreadPool configuration The following threadingParameters may be specified: minThreads Specifies the number of "core" threads for the worker task thread pool. Generally this should be reasonably high, at least 10 per CPU core.. maxThreads Specifies the maximum number of threads for the worker task thread pool. The following worker parameters may be specified: workerIOThreads Specifies the number of I/O threads to create for the worker. If not specified, a default will be chosen. One IO thread per CPU core is a reasonable default. workerIOName Specifies the name for the worker. If not specified, the default "XNIO-1" will be chosen. 16.5. Configuration file naming convention The file naming convention for configuration files depends on whether the configuration is intended for an OSGi Managed Service or for an OSGi Managed Service factory. The configuration file for an OSGi Managed Service obeys the following naming convention: Where <PID> is the persistent ID of the OSGi Managed Service (as defined in the OSGi Configuration Admin specification). A persistent ID is normally dot-delimited-for example, org.ops4j.pax.web . The configuration file for an OSGi Managed Service Factory obeys the following naming convention: Where <PID> is the persistent ID of the OSGi Managed Service Factory. In the case of a managed service factory's <PID>, you can append a hyphen followed by an arbitrary instance ID, <InstanceID> . The managed service factory then creates a unique service instance for each <InstanceID> that it finds. 16.6. Setting Java Options Java Options can be set using the /bin/setenv file in Linux, or the bin/setenv.bat file for Windows. Use this file to directly set a group of Java options: JAVA_MIN_MEM, JAVA_MAX_MEM, JAVA_PERM_MEM, JAVA_MAX_PERM_MEM. Other Java options can be set using the EXTRA_JAVA_OPTS variable. For example, to allocate minimum memory for the JVM use 16.7. Config Console Commands There are a number of console commands that can be used to change or interrogate the configuration of Fuse 7.13. See the Config section in the Apache Karaf Console Reference for more details about the config: commands. 16.8. JMX ConfigMBean On the JMX layer, the MBean is dedicated to configuration management. The ConfigMBean object name is: org.apache.karaf:type=config,name=*` . 14.1.2.1. Attributes The config MBean contains a list of all configuration PIDs. 14.1.2.2. Operations Table 16.2. JMX MBean Operations Operation name Description listProperties(pid) returns the list of properties (property=value formatted) for the configuration pid. deleteProperty(pid, property) deletes the property from the configuration pid. appendProperty(pid, property, value) appends value at the end of the value of the property of the configuration pid. setProperty(pid, property, value) sets value for the value of the property of the configuration pid. delete(pid) deletes the configuration identified by the pid. create(pid) creates an empty (without any property) configuration with pid. update(pid, properties) updates a configuration identified with pid with the provided properties map. 16.9. Using the console 16.9.1. Available commands To see a list of the available commands in the console, you can use the help : You have the list of all commands with a short description. You can use the tab key to get a quick list of all commands: 16.9.2. Subshell and completion mode The commands have a scope and a name. For instance, the command feature:list has feature as scope, and list as name. Karaf "groups" the commands by scope. Each scope form a subshell. You can directly execute a command with its full qualified name (scope:name): or enter in a subshell and type the command contextual to the subshell: You can note that you enter in a subshell directly by typing the subshell name (here feature ). You can "switch" directly from a subshell to another: The prompt displays the current subshell between (). The exit command goes to the parent subshell: The completion mode defines the behaviour of the tab key and the help command. You have three different modes available: GLOBAL FIRST SUBSHELL You can define your default completion mode using the completionMode property in etc/org.apache.karaf.shell.cfg file. By default, you have: You can also change the completion mode "on the fly" (while using the Karaf shell console) using the shell:completion command: shell:completion can inform you about the current completion mode used. You can also provide the new completion mode that you want. GLOBAL completion mode is the default one in Karaf 4.0.0 (mostly for transition purpose). GLOBAL mode doesn't really use subshell: it's the same behavior as in Karaf versions. When you type the tab key, whatever in which subshell you are, the completion will display all commands and all aliases: FIRST completion mode is an alternative to the GLOBAL completion mode. If you type the tab key on the root level subshell, the completion will display the commands and the aliases from all subshells (as in GLOBAL mode). However, if you type the tab key when you are in a subshell, the completion will display only the commands of the current subshell: SUBSHELL completion mode is the real subshell mode. If you type the tab key on the root level, the completion displays the subshell commands (to go into a subshell), and the global aliases. Once you are in a subshell, if you type the TAB key, the completion displays the commands of the current subshell: 16.9.3. Unix like environment Karaf console provides a full Unix like environment. 16.9.3.1. Help or man We already saw the usage of the help command to display all commands available. But you can also use the help command to get details about a command or the man command which is an alias to the help command. You can also use another form to get the command help, by using the --help option to the command. So these commands All produce the same help output: 16.9.3.2. Completion When you type the tab key, Karaf tries to complete: subshell commands aliases command arguments command options 16.9.3.3. Alias An alias is another name associated to a given command. The shell:alias command creates a new alias. For instance, to create the list-installed-features alias to the actual feature:list -i command, you can do: At login, the Apache Karaf console reads the etc/shell.init.script file where you can create your aliases. It's similar to a bashrc or profile file on Unix. You can see here the aliases available by default: ld is a short form to display log (alias to log:display command) lde is a short form to display exceptions (alias to log:exception-display command) la is a short form to list all bundles (alias to bundle:list -t 0 command) ls is a short form to list all services (alias to service:list command) cl is a short form to list all configurations (alias to config:list command) halt is a short form to shutdown Apache Karaf (alias to system:shutdown -h -f command) help is a short form to display help (alias to *:help command) man is the same as help (alias to help command) log:list displays all loggers and level (alias to log:get ALL command) You can create your own aliases in the etc/shell.init.script file. 16.9.3.4. Key binding Like on most Unix environment, Karaf console support some key bindings: the arrows key to navigate in the commands history CTRL-D to logout/shutdown Karaf CTRL-R to search previously executed command CTRL-U to remove the current line 16.9.3.5. Pipe You can pipe the output of one command as input to another one. It's a pipe, using the | character: 16.9.3.6. Grep, more, find, ... Karaf console provides some core commands similar to Unix environment: shell:alias creates an alias to an existing command shell:cat displays the content of a file or URL shell:clear clears the current console display shell:completion displays or change the current completion mode shell:date displays the current date (optionally using a format) shell:each executes a closure on a list of arguments shell:echo echoes and prints arguments to stdout shell:edit calls a text editor on the current file or URL shell:env displays or sets the value of a shell session variable shell:exec executes a system command shell:grep prints lines matching the given pattern shell:head displays the first line of the input shell:history prints the commands history shell:if allows you to use conditions (if, then, else blocks) in script shell:info prints various information about the current Karaf instance shell:java executes a Java application shell:less file pager shell:logout disconnects shell from current session shell:more is a file pager shell:new creates a new Java object shell:printf formats and prints arguments shell:sleep sleeps for a bit then wakes up shell:sort writes sorted concatenation of all files to stdout shell:source executes commands contained in a script shell:stack-traces-print prints the full stack trace in the console when the execution of a command throws an exception shell:tac captures the STDIN and returns it as a string shell:tail displays the last lines of the input shell:threads prints the current thread shell:watch periodically executes a command and refresh the output shell:wc prints newline, words, and byte counts for each file shell:while loop while the condition is true You don't have to use the fully qualified name of the command, you can directly use the command name as long as it is unique. So you can use 'head' instead of 'shell:head' Again, you can find details and all options of these commands using help command or --help option. 16.9.3.7. Scripting The Apache Karaf Console supports a complete scripting language, similar to bash or csh on Unix. The each ( shell:each ) command can iterate in a list: Note The same loop could be written with the shell:while command: You can create the list yourself (as in the example), or some commands can return a list too. We can note that the console created a "session" variable with the name list that you can access with USDlist . The USDit variable is an implicit one corresponding to the current object (here the current iterated value from the list). When you create a list with [] , Apache Karaf console creates a Java ArrayList. It means that you can use methods available in the ArrayList objects (like get or size for instance): We can note here that calling a method on an object is directly using (object method argument) . Here (USDlist get 0) means USDlist.get(0) where USDlist is the ArrayList. The class notation will display details about the object: You can "cast" a variable to a given type. If it fails, you will see the casting exception: You can "call" a script using the shell:source command: where script.txt contains: Note The spaces are important when writing script. For instance, the following script is not correct: and will fail with: because a space is missing after the if statement. As for the aliases, you can create init scripts in the etc/shell.init.script file. You can also named you script with an alias. Actually, the aliases are just scripts. See the Scripting section of the developers guide for details. 16.9.4. Security The Apache Karaf console supports a Role Based Access Control (RBAC) security mechanism. It means that depending of the user connected to the console, you can define, depending of the user's groups and roles, the permission to execute some commands, or limit the values allowed for the arguments. Console security is detailed in the Security section of this user guide. 16.10. Provisioning Apache Karaf supports the provisioning of applications and modules using the concept of Karaf Features. 16.10.1. Application By provisioning application, it means install all modules, configuration, and transitive applications. 16.10.2. OSGi It natively supports the deployment of OSGi applications. An OSGi application is a set of OSGi bundles. An OSGi bundles is a regular jar file, with additional metadata in the jar MANIFEST. In OSGi, a bundle can depend to other bundles. So, it means that to deploy an OSGi application, most of the time, you have to firstly deploy a lot of other bundles required by the application. So, you have to find these bundles first, install the bundles. Again, these "dependency" bundles may require other bundles to satisfy their own dependencies. More over, typically, an application requires configuration (see the [Configuration section|configuration] of the user guide). So, before being able to start your application, in addition of the dependency bundles, you have to create or deploy the configuration. As we can see, the provisioning of an application can be very long and fastidious. 16.10.3. Feature and resolver Apache Karaf provides a simple and flexible way to provision applications. In Apache Karaf, the application provisioning is an Apache Karaf "feature". A feature describes an application as: a name a version a optional description (eventually with a long description) a set of bundles optionally a set configurations or configuration files optionally a set of dependency features When you install a feature, Apache Karaf installs all resources described in the feature. It means that it will automatically resolves and installs all bundles, configurations, and dependency features described in the feature. The feature resolver checks the service requirements, and install the bundles providing the services matching the requirements. The default mode enables this behavior only for "new style" features repositories (basically, the features repositories XML with schema equal or greater to 1.3.0). It doesn't apply for "old style" features repositories (coming from Karaf 2 or 3). You can change the service requirements enforcement mode in etc/org.apache.karaf.features.cfg file, using the serviceRequirements property. The possible values are: disable: service requirements are completely ignored, for both "old style" and "new style" features repositories default: service requirements are ignored for "old style" features repositories, and enabled for "new style" features repositories. enforce: service requirements are always verified, for "old style" and "new style" features repositories. Additionally, a feature can also define requirements. In that case, Karaf can automatically additional bundles or features providing the capabilities to satisfy the requirements. A feature has a complete lifecycle: install, start, stop, update, uninstall. 16.10.4. Features repositories The features are described in a features XML descriptor. This XML file contains the description of a set of features. A features XML descriptor is named a "features repository". Before being able to install a feature, you have to register the features repository that provides the feature (using feature:repo-add command or FeatureMBean as described later). For instance, the following XML file (or "features repository") describes the feature1 and feature2 features: We can note that the features XML has a schema. Take a look on [Features XML Schema section|provisioning-schema] of the user guide for details. The feature1 feature is available in version 1.0.0 , and contains two bundles. The <bundle/> element contains a URL to the bundle artifact (see [Artifacts repositories and URLs section|urls] for details). If you install the feature1 feature (using feature:install or the FeatureMBean as described later), Apache Karaf will automatically installs the two bundles described. The feature2 feature is available in version 1.1.0 , and contains a reference to the feature1 feature and a bundle. The <feature/> element contains the name of a feature. A specific feature version can be defined using the version attribute to the <feature/> element ( <feature version="1.0.0">feature1</feature> ). If the version attribute is not specified, Apache Karaf will install the latest version available. If you install the feature2 feature (using feature:install or the FeatureMBean as described later), Apache Karaf will automatically installs feature1 (if it's not already installed) and the bundle. A feature repository is registered using the URL to the features XML file. The features state is stored in the Apache Karaf cache (in the KARAF_DATA folder). You can restart Apache Karaf, the previously installed features remain installed and available after restart. If you do a clean restart or you delete the Apache Karaf cache (delete the KARAF_DATA folder), all previously features repositories registered and features installed will be lost: you will have to register the features repositories and install features by hand again. To prevent this behaviour, you can specify features as boot features. 16.10.5. Boot features You can describe some features as boot features. A boot feature will be automatically install by Apache Karaf, even if it has not been previously installed using feature:install or FeatureMBean. Apache Karaf features configuration is located in the etc/org.apache.karaf.features.cfg configuration file. This configuration file contains the two properties to use to define boot features: featuresRepositories contains a list (comma-separated) of features repositories (features XML) URLs. featuresBoot contains a list (comma-separated) of features to install at boot. 16.10.6. Features upgrade You can update a release by installing the same feature (with the same SNAPSHOT version or a different version). Thanks to the features lifecycle, you can control the status of the feature (started, stopped, etc). You can also use a simulation to see what the update will do. 16.10.7. Overrides Bundles defined in features can be overridden by using a file etc/overrides.properties. Each line in the file defines one override. The syntax is: <bundle-uri>[;range="[min,max)"] The given bundle will override all bundles in feature definitions with the same symbolic name if the version of the override is greater than the version of the overridden bundle and the range matches. If no range is given then compatibility on the micro version level is assumed. So for example the override mvn:org.ops4j.pax.logging/pax-logging-service/1.8.5 would overide pax-logging-service 1.8.3 but not 1.8.6 or 1.7.0. 16.10.8. Feature bundles 16.10.8.1. Start Level By default, the bundles deployed by a feature will have a start-level equals to the value defined in the etc/config.properties configuration file, in the karaf.startlevel.bundle property. This value can be "overrided" by the start-level attribute of the <bundle/> element, in the features XML. The start-level attribute insure that the myproject-dao bundle is started before the bundles that use it. Instead of using start-level, a better solution is to simply let the OSGi framework know what your dependencies are by defining the packages or services you need. It is more robust than setting start levels. 16.10.8.2. Simulate, Start and stop You can simulate the installation of a feature using the -t option to feature:install command. You can install a bundle without starting it. By default, the bundles in a feature are automatically started. A feature can specify that a bundle should not be started automatically (the bundle stays in resolved state). To do so, a feature can specify the start attribute to false in the <bundle/> element: 16.10.8.3. Dependency A bundle can be flagged as being a dependency, using the dependency attribute set to true on the <bundle/> element. This information can be used by resolvers to compute the full list of bundles to be installed. 16.10.9. Dependent features A feature can depend to a set of other features: When the my-project feature will be installed, the other feature will be automatically installed as well. It's possible to define a version range for a dependent feature: The feature with the highest version available in the range will be installed. If a single version is specified, the range will be considered open-ended. If nothing is specified, the highest available will be installed. To specify an exact version, use a closed range such as [3.1,3.1] . 16.10.9.1. Feature prerequisites Prerequisite feature is special kind of dependency. If you will add prerequisite attribute to dependant feature tag then it will force installation and also activation of bundles in dependant feature before installation of actual feature. This may be handy in case if bundles enlisted in given feature are not using pre installed URL such wrap or war . 16.10.10. Feature configurations The <config/> element in a feature XML allows a feature to create and/or populate a configuration (identified by a configuration PID). The name attribute of the <config/> element corresponds to the configuration PID (see the [Configuration section|configuration] for details). The installation of the feature will have the same effect as dropping a file named com.foo.bar.cfg in the etc folder. The content of the <config/> element is a set of properties, following the key=value standard. 16.10.11. Feature configuration files Instead of using the <config/> element, a feature can specify <configfile/> elements. Instead of directly manipulating the Apache Karaf configuration layer (as when using the <config/> element), the <configfile/> element takes directly a file specified by a URL, and copy the file in the location specified by the finalname attribute. If not specified, the location is relative from the KARAF_BASE variable. It's also possible to use variable like USD{karaf.home}, USD{karaf.base}, USD{karaf.etc}, or even system properties. For instance: If the file is already present at the desired location it is kept and the deployment of the configuration file is skipped, as a already existing file might contain customization. This behaviour can be overriden by override set to true. The file URL is any URL supported by Apache Karaf (see the [Artifacts repositories and URLs|urls] of the user guide for details). 16.10.11.1. Requirements A feature can also specify expected requirements. The feature resolver will try to satisfy the requirements. For that, it checks the features and bundles capabilities and will automatically install the bundles to satisfy the requirements. For instance, a feature can contain: The requirement specifies that the feature will work by only if the JDK version is not 1.8 (so basically 1.7). The features resolver is also able to refresh the bundles when an optional dependency is satisfy, rewiring the optional import. 16.10.12. Commands 16.10.12.1. feature:repo-list The feature:repo-list command lists all registered features repository: Each repository has a name and the URL to the features XML. Apache Karaf parses the features XML when you register the features repository URL (using feature:repo-add command or the FeatureMBean as described later). If you want to force Apache Karaf to reload the features repository URL (and so update the features definition), you can use the -r option: 16.10.12.2. feature:repo-add To register a features repository (and so having new features available in Apache Karaf), you have to use the feature:repo-add command. The feature:repo-add command requires the name/url argument. This argument accepts: a feature repository URL. It's an URL directly to the features XML file. Any URL described in the [Artifacts repositories and URLs section|urls] of the user guide is supported. a feature repository name defined in the etc/org.apache.karaf.features.repos.cfg configuration file. The etc/org.apache.karaf.features.repos.cfg defines a list of "pre-installed/available" features repositories: You can directly provide a features repository name to the feature:repo-add command. For install, to install PAX JDBC, you can do: When you don't provide the optional version argument, Apache Karaf installs the latest version of the features repository available. You can specify a target version with the version argument: Instead of providing a features repository name defined in the etc/org.apache.karaf.features.repos.cfg configuration file, you can directly provide the features repository URL to the feature:repo-add command: By default, the feature:repo-add command just registers the features repository, it doesn't install any feature. If you specify the -i option, the feature:repo-add command registers the features repository and installs all features described in this features repository: 16.10.12.3. feature:repo-refresh Apache Karaf parses the features repository XML when you register it (using feature:repo-add command or the FeatureMBean). If the features repository XML changes, you have to indicate to Apache Karaf to refresh the features repository to load the changes. The feature:repo-refresh command refreshes the features repository. Without argument, the command refreshes all features repository: Instead of refreshing all features repositories, you can specify the features repository to refresh, by providing the URL or the features repository name (and optionally version): 16.10.12.4. feature:repo-remove The feature:repo-remove command removes a features repository from the registered ones. The feature:repo-remove command requires an argument: the features repository name (as displayed in the repository column of the feature:repo-list command output) the features repository URL (as displayed in the URL column of the feature:repo-list command output) By default, the feature:repo-remove command just removes the features repository from the registered ones: it doesn't uninstall the features provided by the features repository. If you use -u option, the feature:repo-remove command uninstalls all features described by the features repository: 16.10.12.5. feature:list The feature:list command lists all available features (provided by the different registered features repositories): If you want to order the features by alphabetical name, you can use the -o option: By default, the feature:list command displays all features, whatever their current state (installed or not installed). Using the -i option displays only installed features: 16.10.12.6. feature:install The feature:install command installs a feature. It requires the feature argument. The feature argument is the name of the feature, or the name/version of the feature. If only the name of the feature is provided (not the version), the latest version available will be installed. We can simulate an installation using -t or --simulate option: it just displays what it would do, but it doesn't do it: You can specify a feature version to install: By default, the feature:install command is not verbose. If you want to have some details about actions performed by the feature:install command, you can use the -v option: If a feature contains a bundle which is already installed, by default, Apache Karaf will refresh this bundle. Sometime, this refresh can cause issue to other running applications. If you want to disable the auto-refresh of installed bundles, you can use the -r option: You can decide to not start the bundles installed by a feature using the -s or --no-auto-start option: 16.10.12.7. feature:start By default, when you install a feature, it's automatically installed. However, you can specify the -s option to the feature:install command. As soon as you install a feature (started or not), all packages provided by the bundles defined in the feature will be available, and can be used for the wiring in other bundles. When starting a feature, all bundles are started, and so, the feature also exposes the services. 16.10.12.8. feature:stop You can also stop a feature: it means that all services provided by the feature will be stop and removed from the service registry. However, the packages are still available for the wiring (the bundles are in resolved state). 16.10.12.9. feature:uninstall The feature:uninstall command uninstalls a feature. As the feature:install command, the feature:uninstall command requires the feature argument. The feature argument is the name of the feature, or the name/version of the feature. If only the name of the feature is provided (not the version), the latest version available will be installed. The features resolver is involved during feature uninstallation: transitive features installed by the uninstalled feature can be uninstalled themselves if not used by other feature. 16.10.13. Deployer You can "hot deploy" a features XML by dropping the file directly in the deploy folder. Apache Karaf provides a features deployer. When you drop a features XML in the deploy folder, the features deployer does: * register the features XML as a features repository * the features with install attribute set to "auto" will be automatically installed by the features deployer. For instance, dropping the following XML in the deploy folder will automatically install feature1 and feature2, whereas feature3 won't be installed: 16.10.14. JMX FeatureMBean On the JMX layer, you have a MBean dedicated to the management of the features and features repositories: the FeatureMBean. The FeatureMBean object name is: org.apache.karaf:type=feature,name=* . 16.10.14.1. Attributes The FeatureMBean provides two attributes: Features is a tabular data set of all features available. Repositories is a tabular data set of all registered features repositories. The Repositories attribute provides the following information: Name is the name of the features repository. Uri is the URI to the features XML for this repository. Features is a tabular data set of all features (name and version) provided by this features repository. Repositories is a tabular data set of features repositories "imported" in this features repository. The Features attribute provides the following information: Name is the name of the feature. Version is the version of the feature. Installed is a boolean. If true, it means that the feature is currently installed. Bundles is a tabular data set of all bundles (bundles URL) described in the feature. Configurations is a tabular data set of all configurations described in the feature. Configuration Files is a tabular data set of all configuration files described in the feature. Dependencies is a tabular data set of all dependent features described in the feature. 16.10.14.2. Operations addRepository(url) adds the features repository with the url . The url can be a name as in the feature:repo-add command. addRepository(url, install) adds the features repository with the url and automatically installs all bundles if install is true. The url can be a name like in the feature:repo-add command. removeRepository(url) removes the features repository with the url . The url can be a name as in the feature:repo-remove command. installFeature(name) installs the feature with the name . installFeature(name, version) installs the feature with the name and version . installFeature(name, noClean, noRefresh) installs the feature with the name without cleaning the bundles in case of failure, and without refreshing already installed bundles. installFeature(name, version, noClean, noRefresh) ` installs the feature with the `name and version without cleaning the bundles in case of failure, and without refreshing already installed bundles. uninstallFeature(name) uninstalls the feature with the name . uninstallFeature(name, version) uninstalls the feature with the name and version . 16.10.14.3. Notifications The FeatureMBean sends two kind of notifications (on which you can subscribe and react): When a feature repository changes (added or removed). When a feature changes (installed or uninstalled).

Commands:
<!-- Only "default" worker and buffer-pool are supported and can be used to override the default values used by all listeners buffer-pool: - buffer-size defaults to: - when < 64MB of Xmx: 512 - when < 128MB of Xmx: 1024 - when >= 128MB of Xmx: 16K - 20 - direct-buffers defaults to: - when < 64MB of Xmx: false - when >= 64MB of Xmx: true worker: - io-threads defaults to Math.max(Runtime.getRuntime().availableProcessors(), 2); - task-core-threads and task-max-threads default to io-threads * 8 --> <!-- <subsystem xmlns="urn:jboss:domain:io:3.0"> <buffer-pool name="default" buffer-size="16364" direct-buffers="true" /> <worker name="default" io-threads="8" task-core-threads="64" task-max-threads="64" task-keepalive="60000" /> </subsystem> -->
<httpu:engine-factory> <httpu:engine port="9001"> <httpu:threadingParameters minThreads="99" maxThreads="777" workerIOThreads="8" workerIOName="WorkerIOTest"/> </httpu:engine> </httpu:engine-factory>
<PID>.cfg
<PID>-<InstanceID>.cfg
JAVA_MIN_MEM=512M # Minimum memory for the JVM
To set a Java option other than the direct options, use
EXTRA_JAVA_OPTS=" Java option "
For example,
EXTRA_JAVA_OPTS="-XX:+UseG1GC"
karaf@root()> help bundle Enter the subshell bundle:capabilities Displays OSGi capabilities of a given bundles. bundle:classes Displays a list of classes/resources contained in the bundle bundle:diag Displays diagnostic information why a bundle is not Active bundle:dynamic-import Enables/disables dynamic-import for a given bundle. bundle:find-class Locates a specified class in any deployed bundle bundle:headers Displays OSGi headers of a given bundles. bundle:id Gets the bundle ID.
karaf@root()> Display all 294 possibilities? (y or n)
karaf@root()> feature:list
karaf@root()> feature karaf@root(feature)> list
karaf@root()> feature karaf@root(feature)> bundle karaf@root(bundle)>
karaf@root()> feature karaf@root(feature)> exit karaf@root()>
completionMode = GLOBAL
karaf@root()> shell:completion GLOBAL karaf@root()> shell:completion FIRST karaf@root()> shell:completion FIRST
karaf@root()> <TAB> karaf@root()> Display all 273 possibilities? (y or n) karaf@root()> feature karaf@root(feature)> <TAB> karaf@root(feature)> Display all 273 possibilities? (y or n)
karaf@root()> shell:completion FIRST karaf@root()> <TAB> karaf@root()> Display all 273 possibilities? (y or n) karaf@root()> feature karaf@root(feature)> <TAB> karaf@root(feature)> info install list repo-add repo-list repo-remove uninstall version-list karaf@root(feature)> exit karaf@root()> log karaf@root(log)> <TAB> karaf@root(log)> clear display exception-display get log set tail
karaf@root()> shell:completion SUBSHELL karaf@root()> <TAB> karaf@root()> * bundle cl config dev feature help instance jaas kar la ld lde log log:list man package region service shell ssh system karaf@root()> bundle karaf@root(bundle)> <TAB> karaf@root(bundle)> capabilities classes diag dynamic-import find-class headers info install list refresh requirements resolve restart services start start-level stop uninstall update watch karaf@root(bundle)> exit karaf@root()> camel karaf@root(camel)> <TAB> karaf@root(camel)> backlog-tracer-dump backlog-tracer-info backlog-tracer-start backlog-tracer-stop context-info context-list context-start context-stop endpoint-list route-info route-list route-profile route-reset-stats route-resume route-show route-start route-stop route-suspend
karaf@root()> help feature:list karaf@root()> man feature:list karaf@root()> feature:list --help
DESCRIPTION feature:list Lists all existing features available from the defined repositories. SYNTAX feature:list [options] OPTIONS --help Display this help message -o, --ordered Display a list using alphabetical order -i, --installed Display a list of all installed features only --no-format Disable table rendered output
karaf@root()> alias "list-features-installed = { feature:list -i }" karaf@root()> list-features-installed Name | Version | Required | State | Repository | Description ------------------------------------------------------------------------------------------------------------------------------ feature | 4.0.0 | x | Started | standard-4.0.0 | Features Support shell | 4.0.0 | x | Started | standard-4.0.0 | Karaf Shell deployer | 4.0.0 | x | Started | standard-4.0.0 | Karaf Deployer bundle | 4.0.0 | x | Started | standard-4.0.0 | Provide Bundle support config | 4.0.0 | x | Started | standard-4.0.0 | Provide OSGi ConfigAdmin support diagnostic | 4.0.0 | x | Started | standard-4.0.0 | Provide Diagnostic support instance | 4.0.0 | x | Started | standard-4.0.0 | Provide Instance support jaas | 4.0.0 | x | Started | standard-4.0.0 | Provide JAAS support log | 4.0.0 | x | Started | standard-4.0.0 | Provide Log support package | 4.0.0 | x | Started | standard-4.0.0 | Package commands and mbeans service | 4.0.0 | x | Started | standard-4.0.0 | Provide Service support system | 4.0.0 | x | Started | standard-4.0.0 | Provide System support kar | 4.0.0 | x | Started | standard-4.0.0 | Provide KAR (KARaf archive) support ssh | 4.0.0 | x | Started | standard-4.0.0 | Provide a SSHd server on Karaf management | 4.0.0 | x | Started | standard-4.0.0 | Provide a JMX MBeanServer and a set of MBeans in
ld = { log:display USDargs } ; lde = { log:exception-display USDargs } ; la = { bundle:list -t 0 USDargs } ; ls = { service:list USDargs } ; cl = { config:list "(service.pid=USDargs)" } ; halt = { system:shutdown -h -f USDargs } ; help = { *:help USDargs | more } ; man = { help USDargs } ; log:list = { log:get ALL } ;
karaf@root()> feature:list |grep -i war pax-war | 4.1.4 | | Uninstalled | org.ops4j.pax.web-4.1.4 | Provide support of a full WebContainer pax-war-tomcat | 4.1.4 | | Uninstalled | org.ops4j.pax.web-4.1.4 | war | 4.0.0 | | Uninstalled | standard-4.0.0 | Turn Karaf as a full WebContainer blueprint-web | 4.0.0 | | Uninstalled | standard-4.0.0 | Provides an OSGI-aware Servlet ContextListener fo
karaf@root()> list = [1 2 3]; each (USDlist) { echo USDit } 1 2 3
karaf@root()> a = 0 ; while { %((a+=1) <= 3) } { echo USDa } 1 2 3
karaf@root()> list = ["Hello" world]; echo (USDlist get 0) (USDlist get 1) Hello world
karaf@root()> USDlist class ProtectionDomain ProtectionDomain null null <no principals> java.security.Permissions@6521c24e ( ("java.security.AllPermission" "<all permissions>" "<all actions>") ) Signers null SimpleName ArrayList TypeParameters [E]
karaf@root()> ("hello world" toCharArray) [h, e, l, l, o, , w, o, r, l, d]
karaf@root()> ("hello world" toCharArray)[0] Error executing command: [C cannot be cast to [Ljava.lang.Object;
karaf@root> shell:source script.txt True!
foo = "foo" if { USDfoo equals "foo" } { echo "True!" }
if{ USDfoo equals "foo" }
karaf@root> shell:source script.txt Error executing command: Cannot coerce echo "true!"() to any of []
serviceRequirements=default
<features xmlns="http://karaf.apache.org/xmlns/features/v1.3.0"> <feature name="feature1" version="1.0.0"> <bundle>...</bundle> <bundle>...</bundle> </feature> <feature name="feature2" version="1.1.0"> <feature>feature1</feature> <bundle>...</bundle> </feature> </features>
<feature name="my-project" version="1.0.0"> <bundle start-level="80">mvn:com.mycompany.myproject/myproject-dao</bundle> <bundle start-level="85">mvn:com.mycompany.myproject/myproject-service</bundle> </feature>
<feature name="my-project" version="1.0.0"> <bundle start-level="80" start="false">mvn:com.mycompany.myproject/myproject-dao</bundle> <bundle start-level="85" start="false">mvn:com.mycompany.myproject/myproject-service</bundle> </feature>
<feature name="my-project" version="1.0.0"> <feature>other</feature> <bundle start-level="80" start="false">mvn:com.mycompany.myproject/myproject-dao</bundle> <bundle start-level="85" start="false">mvn:com.mycompany.myproject/myproject-service</bundle> </feature>
<feature name="spring-dm"> <feature version="[2.5.6,4)">spring</feature> </feature>
<config name="com.foo.bar"> myProperty = myValue </config>
<configfile finalname="/etc/myfile.cfg" override="false">URL</configfile>
<configfile finalname="USD{karaf.etc}/myfile.cfg" override="false">URL</configfile>
<requirement>osgi.ee;filter:=&quot;(&amp;(osgi.ee=JavaSE)(!(version&gt;=1.8)))&quot;</requirement>
karaf@root()> feature:repo-list Repository | URL -------------------------------------------------------------------------------------- org.ops4j.pax.cdi-0.12.0 | mvn:org.ops4j.pax.cdi/pax-cdi-features/0.12.0/xml/features org.ops4j.pax.web-4.1.4 | mvn:org.ops4j.pax.web/pax-web-features/4.1.4/xml/features standard-4.0.0 | mvn:org.apache.karaf.features/standard/4.0.0/xml/features enterprise-4.0.0 | mvn:org.apache.karaf.features/enterprise/4.0.0/xml/features spring-4.0.0 | mvn:org.apache.karaf.features/spring/4.0.0/xml/features
karaf@root()> feature:repo-list -r Reloading all repositories from their urls Repository | URL -------------------------------------------------------------------------------------- org.ops4j.pax.cdi-0.12.0 | mvn:org.ops4j.pax.cdi/pax-cdi-features/0.12.0/xml/features org.ops4j.pax.web-4.1.4 | mvn:org.ops4j.pax.web/pax-web-features/4.1.4/xml/features standard-4.0.0 | mvn:org.apache.karaf.features/standard/4.0.0/xml/features enterprise-4.0.0 | mvn:org.apache.karaf.features/enterprise/4.0.0/xml/features spring-4.0.0 | mvn:org.apache.karaf.features/spring/4.0.0/xml/features
################################################################################ # Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at # http://www.apache.org/licenses/LICENSE-2.0 # Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. # ################################################################################ # This file describes the features repository URL It could be directly installed using feature:repo-add command # enterprise=mvn:org.apache.karaf.features/enterprise/LATEST/xml/features spring=mvn:org.apache.karaf.features/spring/LATEST/xml/features cellar=mvn:org.apache.karaf.cellar/apache-karaf-cellar/LATEST/xml/features cave=mvn:org.apache.karaf.cave/apache-karaf-cave/LATEST/xml/features camel=mvn:org.apache.camel.karaf/apache-camel/LATEST/xml/features camel-extras=mvn:org.apache-extras.camel-extra.karaf/camel-extra/LATEST/xml/features cxf=mvn:org.apache.cxf.karaf/apache-cxf/LATEST/xml/features cxf-dosgi=mvn:org.apache.cxf.dosgi/cxf-dosgi/LATEST/xml/features cxf-xkms=mvn:org.apache.cxf.services.xkms/cxf-services-xkms-features/LATEST/xml activemq=mvn:org.apache.activemq/activemq-karaf/LATEST/xml/features jclouds=mvn:org.apache.jclouds.karaf/jclouds-karaf/LATEST/xml/features openejb=mvn:org.apache.openejb/openejb-feature/LATEST/xml/features wicket=mvn:org.ops4j.pax.wicket/features/LATEST/xml/features hawtio=mvn:io.hawt/hawtio-karaf/LATEST/xml/features pax-cdi=mvn:org.ops4j.pax.cdi/pax-cdi-features/LATEST/xml/features pax-jdbc=mvn:org.ops4j.pax.jdbc/pax-jdbc-features/LATEST/xml/features pax-jpa=mvn:org.ops4j.pax.jpa/pax-jpa-features/LATEST/xml/features pax-web=mvn:org.ops4j.pax.web/pax-web-features/LATEST/xml/features pax-wicket=mvn:org.ops4j.pax.wicket/pax-wicket-features/LATEST/xml/features ecf=http://download.eclipse.org/rt/ecf/latest/site.p2/karaf-features.xml decanter=mvn:org.apache.karaf.decanter/apache-karaf-decanter/LATEST/xml/features
karaf@root()> feature:repo-add pax-jdbc Adding feature url mvn:org.ops4j.pax.jdbc/pax-jdbc-features/LATEST/xml/features
karaf@root()> feature:repo-add pax-jdbc 1.3.0 Adding feature url mvn:org.ops4j.pax.jdbc/pax-jdbc-features/1.3.0/xml/features
karaf@root()> feature:repo-add mvn:org.ops4j.pax.jdbc/pax-jdbc-features/1.3.0/xml/features Adding feature url mvn:org.ops4j.pax.jdbc/pax-jdbc-features/1.3.0/xml/features
karaf@root()> feature:repo-add -i pax-jdbc
karaf@root()> feature:repo-refresh Refreshing feature url mvn:org.ops4j.pax.cdi/pax-cdi-features/0.12.0/xml/features Refreshing feature url mvn:org.ops4j.pax.web/pax-web-features/4.1.4/xml/features Refreshing feature url mvn:org.apache.karaf.features/standard/4.0.0/xml/features Refreshing feature url mvn:org.apache.karaf.features/enterprise/4.0.0/xml/features Refreshing feature url mvn:org.apache.karaf.features/spring/4.0.0/xml/features
karaf@root()> feature:repo-refresh mvn:org.apache.karaf.features/standard/4.0.0/xml/features Refreshing feature url mvn:org.apache.karaf.features/standard/4.0.0/xml/features
karaf@root()> feature:repo-refresh pax-jdbc Refreshing feature url mvn:org.ops4j.pax.jdbc/pax-jdbc-features/LATEST/xml/features
karaf@root()> feature:repo-remove org.ops4j.pax.jdbc-1.3.0
karaf@root()> feature:repo-remove mvn:org.ops4j.pax.jdbc/pax-jdbc-features/1.3.0/xml/features
karaf@root()> feature:repo-remove -u org.ops4j.pax.jdbc-1.3.0
Name | Version | Required | State | Repository | Description ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- pax-cdi | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI support pax-cdi-1.1 | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI 1.1 support pax-cdi-1.2 | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI 1.2 support pax-cdi-weld | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld CDI support pax-cdi-1.1-weld | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld CDI 1.1 support pax-cdi-1.2-weld | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld CDI 1.2 support pax-cdi-openwebbeans | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | OpenWebBeans CDI support pax-cdi-web | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Web CDI support pax-cdi-1.1-web | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Web CDI 1.1 support
karaf@root()> feature:list -o Name | Version | Required | State | Repository | Description ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- deltaspike-core | 1.2.1 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Apache Deltaspike core support deltaspike-data | 1.2.1 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Apache Deltaspike data support deltaspike-jpa | 1.2.1 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Apache Deltaspike jpa support deltaspike-partial-bean | 1.2.1 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Apache Deltaspike partial bean support pax-cdi | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI support pax-cdi-1.1 | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI 1.1 support pax-cdi-1.1-web | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Web CDI 1.1 support pax-cdi-1.1-web-weld | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld Web CDI 1.1 support pax-cdi-1.1-weld | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Weld CDI 1.1 support pax-cdi-1.2 | 0.12.0 | | Uninstalled | org.ops4j.pax.cdi-0.12.0 | Provide CDI 1.2 support
karaf@root()> feature:list -i Name | Version | Required | State | Repository | Description ------------------------------------------------------------------------------------------------------------------- aries-proxy | 4.0.0 | | Started | standard-4.0.0 | Aries Proxy aries-blueprint | 4.0.0 | x | Started | standard-4.0.0 | Aries Blueprint feature | 4.0.0 | x | Started | standard-4.0.0 | Features Support shell | 4.0.0 | x | Started | standard-4.0.0 | Karaf Shell shell-compat | 4.0.0 | x | Started | standard-4.0.0 | Karaf Shell Compatibility deployer | 4.0.0 | x | Started | standard-4.0.0 | Karaf Deployer bundle | 4.0.0 | x | Started | standard-4.0.0 | Provide Bundle support config | 4.0.0 | x | Started | standard-4.0.0 | Provide OSGi ConfigAdmin support diagnostic | 4.0.0 | x | Started | standard-4.0.0 | Provide Diagnostic support instance | 4.0.0 | x | Started | standard-4.0.0 | Provide Instance support jaas | 4.0.0 | x | Started | standard-4.0.0 | Provide JAAS support log | 4.0.0 | x | Started | standard-4.0.0 | Provide Log support package | 4.0.0 | x | Started | standard-4.0.0 | Package commands and mbeans service | 4.0.0 | x | Started | standard-4.0.0 | Provide Service support system | 4.0.0 | x | Started | standard-4.0.0 | Provide System support kar | 4.0.0 | x | Started | standard-4.0.0 | Provide KAR (KARaf archive) support ssh | 4.0.0 | x | Started | standard-4.0.0 | Provide a SSHd server on Karaf management | 4.0.0 | x | Started | standard-4.0.0 | Provide a JMX MBeanServer and a set of MBeans in wrap | 0.0.0 | x | Started | standard-4.0.0 | Wrap URL handler
karaf@root()> feature:install eventadmin
karaf@root()> feature:install -t -v eventadmin Adding features: eventadmin/[4.0.0,4.0.0] No deployment change. Managing bundle: org.apache.felix.metatype / 1.0.12
karaf@root()> feature:install eventadmin/4.0.0
karaf@root()> feature:install -v eventadmin Adding features: eventadmin/[4.0.0,4.0.0] No deployment change. Done.
karaf@root()> feature:install -v -r eventadmin Adding features: eventadmin/[4.0.0,4.0.0] No deployment change. Done.
karaf@root()> feature:install -s eventadmin
karaf@root()> feature:uninstall eventadmin
<?xml version="1.0" encoding="UTF-8"?> <features name="my-features" xmlns="http://karaf.apache.org/xmlns/features/v1.3.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://karaf.apache.org/xmlns/features/v1.3.0 http://karaf.apache.org/xmlns/features/v1.3.0"> <feature name="feature1" version="1.0" install="auto"> </feature> <feature name="feature2" version="1.0" install="auto"> </feature> <feature name="feature3" version="1.0"> </feature> </features>