Using the karaf-maven-plugin

The Karaf Maven plugin allows you:

  • to work with Karaf features: verify and validate a features descriptor, add features bundle into a repository, create a KAR archive from a features descriptor, etc.

  • to create Karaf commands help: it generates help from Karaf commands

  • to modify Karaf instances and create distributions

See https://github.com/apache/karaf/blob/master/examples/karaf-maven-example/README.md for details.

Packaging

The most generally useful features of the karaf-maven-plugin are exposed as packagings. To use the packagings the pom or an ancestor must configure the karaf-maven-plugin with extensions:

    <build>
        <pluginManagement>
            <plugins>
                <plugin>
                    <groupId>org.apache.karaf.tooling</groupId>
                    <artifactId>karaf-maven-plugin</artifactId>
                    <version>${project.version}</version>
                    <extensions>true</extensions>
                </plugin>
            </plugins>
        </pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.apache.karaf.tooling</groupId>
                <artifactId>karaf-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

Then specify the packaging in your project as usual, e.g.

    <packaging>kar</packaging>
Packaging Description

feature

The feature packaging verifies a features.xml descriptor using the karaf:verify goal.

kar

The kar packaging generates a features.xml descriptor using the karaf:features-generate-descriptor and then packages a kar using the karaf:features-create-kar goal.

karaf-assembly

Assembles a Karaf server based on the features descriptors and kar files listed as Maven dependencies.

Commands goals

The karaf-maven-plugin is able to generate documentation for Karaf commands

karaf:commands-generate-help

The karaf:commands-generate-help goal generates documentation containing Karaf commands help.

It looks for Karaf commands in the current project class loader and generates the help as displayed with the --help option in the Karaf shell console.

Example

The example below generates help for the commands in the current project:

<project>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.karaf.tooling</groupId>
        <artifactId>karaf-maven-plugin</artifactId>
        <version>${project.version}</version>

        <executions>
          <execution>
            <id>document-commands</id>
            <phase>generate-resources</phase>
            <goals>
              <goal>commands-generate-help</goal>
            </goals>
            <configuration>
              <targetFolder>${project.build.directory}/docbook/sources</targetFolder>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>
Parameters
Name Type Description

targetFolder

File

The directory where the documentation output files are to be generated. Default value: ${project.build.directory}/docbkx/sources

format

String

The output format (docbx, asciidoc, or conf) of the commands documentation. Default value: docbx

classLoader

String

The class loader to use in loading the commands. Default value: ${project}

Features and kar goals

Note

You should use the features or kar packaging instead of these individual goals.

The karaf-maven-plugin provides several goals to help you create and verify features XML descriptors as well as leverage your features to create a custom Karaf distribution.

karaf:features-generate-descriptor

The karaf:features-generate-descriptor goal generates a features XML file based on the Maven dependencies. By default, it will follow Maven transitive dependencies, stopping when it encounters bundles already present in features that are Maven dependencies.

A record of the dependency tree search can be found in target/history/treeListing.txt.

You can track dependency changes and warn or fail on change.

Configuration

Specify the packaging as a top level element

<packaging>feature</packaging>

You can supply a feature descriptor to extend in src/main/feature/feature.xml.

Parameter Name Type Description

aggregateFeatures

boolean (false)

Specifies processing of feature repositories that are (transitive) Maven dependencies. If false, all features in these repositories become dependencies of the generated feature. If true, all features in these repositories are copied into the generated feature repository.

startLevel

int

The start level for the bundles determined from Maven dependencies. This can be overridden by specifying the bundle in the source feature.xml with the desired startlevel.

includeTransitiveDependency

boolean (true)

Whether to follow Maven transitive dependencies.

checkDependencyChange

boolean (false)

Whether to record dependencies in src/main/history/dependencies.xml for change tracking.

warnOnDependencyChange

boolean (false)

whether to fail on changed dependencies (false, default) or warn in the build output (true).

logDependencyChanges

boolean (false)

If true, added and removed dependencies are shown in target/history.

overwriteChangedDependencies

boolean (false)

If true, the src/main/history/dependencies.xml file will be overwritten if it has changed.

markRuntimeScopeAsDependency

boolean (true)

Whether to mark dependencies' in the runtime scope with dependency="true".

markTransitiveAsDependency

boolean (false)

Whether to mark transitive dependencies' with dependency="true".
Example
<project>
...
  <packaging>feature</packaging>
  <dependencies>
    <dependency>
      <groupId>org.apache</groupId>
      <artifactId>bundle1</artifactId>
      <version>1.0</version>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.karaf.tooling</groupId>
        <artifactId>karaf-maven-plugin</artifactId>
        <version>${project.version}</version>
        <extensions>true</extensions>
        <configuration>
          <enableGeneration>true</enableGeneration>
        </configuration>
        <executions>
          <execution>
            <id>generate-features-file</id>
            <phase>generate-resources</phase>
            <goals>
              <goal>features-generate-descriptor</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>
karaf:verify

Except in unusual circumstances, use the <packaging>feature</packaging> to run this goal.

The karaf:verify goal verifies and validates a features XML descriptor by checking if all the required imports for the bundles defined in the features can be matched to a provided export.

By default, the plugin tries to add the Karaf core features (standard and enterprise) in the repositories set. It means that it’s not required to explicitly define the Karaf features descriptor in the repository section of your features descriptor.

Example

The example below validates the features defined in the target/features.xml by checking all the imports and exports. It reads the definition for the packages that are exported by the system bundle from the src/main/resources/config.properties file.

<project>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.karaf.tooling</groupId>
        <artifactId>karaf-maven-plugin</artifactId>
        <configuration>
        </configuration>
        <executions>
          <execution>
            <id>verify</id>
            <phase>process-resources</phase>
            <goals>
              <goal>verify</goal>
            </goals>
            <configuration>
              <descriptors>
                <descriptor>mvn:org.apache.karaf.features/framework/4.0.4/xml/features</descriptor>
                <descriptor>file:${project.build.directory}/feature/feature.xml</descriptor>
              </descriptors>
              <distribution>org.apache.karaf.features:framework</distribution>
              <javase>1.8</javase>
              <framework>
                <feature>framework</feature>
              </framework>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>
Parameters
Name Type Description

descriptors

String[]

The list of features XML repositories to use for the verify

features

String[]

The list of features to verify. If not specified, all features in the descriptors will be verified.

framework

String[]

The features providing the Karaf framework (optional)

javase

String

The Java version to use for the verify
karaf:features-add-to-repository

Consider using the karaf-assembly packaging which makes it easy to assemble a custom distribution in one step instead of this individual goal.

The karaf:features-add-to-repository goal adds all the required bundles for a given set of features into directory. You can use this goal to create a /system directory for building your own Karaf-based distribution.

By default, the Karaf core features descriptors (standard and enterprise) are automatically included in the descriptors set.

Example

The example below copies the bundles for the spring and war features defined in the Karaf features XML descriptor into the target/features-repo directory.

<project>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.karaf.tooling</groupId>
        <artifactId>karaf-maven-plugin</artifactId>
        <version>${project.version}</version>

        <executions>
          <execution>
            <id>features-add-to-repo</id>
            <phase>generate-resources</phase>
            <goals>
              <goal>features-add-to-repository</goal>
            </goals>
            <configuration>
              <descriptors>
                <descriptor>mvn:org.apache.karaf.features/standard/4.0.0/xml/features</descriptor>
                <descriptor>mvn:my.groupid/my.artifactid/1.0.0/xml/features</descriptor>
              </descriptors>
              <features>
                <feature>spring</feature>
                <feature>war</feature>
                <feature>my</feature>
              </features>
              <repository>target/features-repo</repository>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>
Parameters
Name Type Description

descriptors

String[]

List of features XML descriptors where the features are defined

features

String[]

List of features that bundles should be copied to the repository directory

repository

File

The directory where the bundles will be copied by the plugin goal

timestampedSnapshot

boolean

For SNAPSHOT artifacts, if false we use the base version (foo-1.0-SNAPSHOT), else we use the timestamped version (foo-1.0-2019xxxx). Default value: false
karaf:create-kar
Note

Except in unusual circumstances, use the <packaging>kar</packaging> to run this goal.

The karaf:kar goal assembles a KAR archive from a features XML descriptor file, normally generated in the same project with the karaf:features-generate-descriptor goal.

There are two important directories in a kar:

  • repository/ contains a Maven structured repository of artifacts to be copied into the Karaf repository. The features descriptor and all the bundles mentioned in it are installed in this directory.

  • resources/ contains other resources to be copied over the Karaf installation.

Everything in target/classes is copied into the kar. Therefore resources you want installed into Karaf need to be in e.g. src/main/resources/resources. This choice is so other resources such as legal files from the maven-remote-resources-plugin can be included under META-INF in the kar, without getting installed into Karaf.

Example
<project>
...
  <packaging>kar</packaging>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.karaf.tooling</groupId>
        <artifactId>karaf-maven-plugin</artifactId>
        <version>${project.version}</version>
        <extensions>true</extensions>
        <!-- There is no useful configuration for the kar mojo. The features-generate-descriptor mojo configuration may be useful -->
      </plugin>
    </plugins>
  </build>
</project>
karaf:install-kar

Instances and distributions goals

The karaf-maven-plugin helps you to build custom Karaf distributions or archives existing Karaf instances:

karaf:assembly
Note

This goal is run as part of the karaf-assembly packaging.

The karaf:assembly goal creates a Karaf instance (assembly) filesystem using the Maven dependencies and a provided configuration.

Example
    ...
    <packaging>karaf-assembly</packaging>
    ...
    <dependencies>
        <dependency>
            <groupId>org.apache.karaf.features</groupId>
            <artifactId>framework</artifactId>
            <type>kar</type>
        </dependency>
        <dependency>
            <groupId>org.apache.karaf.features</groupId>
            <artifactId>standard</artifactId>
            <classifier>features</classifier>
            <type>xml</type>
            <scope>runtime</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.karaf.tooling</groupId>
                <artifactId>karaf-maven-plugin</artifactId>
                <extensions>true</extensions>
                <configuration>
                    <finalName>${project.artifactId}</finalName>
                    <installedBundles>
                        <installedBundle>${additional.bundle}</installedBundle>
                    </installedBundles>
                    <bootFeatures>
                        <feature>bundle</feature>
                        <feature>config</feature>
                        <feature>diagnostic</feature>
                        <feature>feature</feature>
                        <feature>jaas</feature>
                        <feature>shell</feature>
                        <feature>log</feature>
                        <feature>management</feature>
                        <feature>package</feature>
                        <feature>shell-compat</feature>
                        <feature>ssh</feature>
                        <feature>system</feature>
                        <feature>wrap</feature>
                    </bootFeatures>
                </configuration>
            </plugin>
        </plugins>
    </build>

By default, the generated Karaf instance is a dynamic distribution (it’s started with default set of resources and then you can deploy new applications in this instance).

It’s also possible to generate a Karaf instance as a static distribution (kind of immutable):

    <dependencies>
        <dependency>
            <groupId>org.apache.karaf.features</groupId>
            <artifactId>static</artifactId>
            <type>kar</type>
        </dependency>
        <dependency>
            <groupId>org.apache.karaf.features</groupId>
            <artifactId>standard</artifactId>
            <classifier>features</classifier>
            <type>xml</type>
        </dependency>
        <dependency>
            <groupId>org.apache.karaf.services</groupId>
            <artifactId>org.apache.karaf.services.staticcm</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.karaf.tooling</groupId>
                <artifactId>karaf-maven-plugin</artifactId>
                <extensions>true</extensions>
                <configuration>
                    <startupFeatures>
                        <startupFeature>static-framework</startupFeature>
                        <startupFeature>scr</startupFeature>
                        <startupFeature>http-whiteboard</startupFeature>
                    </startupFeatures>
                    <framework>static</framework>
                    <useReferenceUrls>true</useReferenceUrls>
                    <environment>static</environment>
                </configuration>
            </plugin>
        </plugins>
    </build>
Parameters
Name Type Description

sourceDirectory

File

Base directory used to overwrite resources in generated assembly after the build (resource directory). Default value: ${project.basedir}/src/main/resources/assembly

workDirectory

File

Base directory used to copy the resources during the build (working directory). Default value: ${project.build.directory}/assembly

featuresProcessing

File

Optional location for custom features processing XML configuration (etc/org.apache.karaf.features.cfg). Default value: null

installAllFeaturesByDefault

Boolean

For given stage (startup, boot, install) if there are no stage-specific features and profiles, all features from stage-specific repositories will be used. Default value: true

environment

String

An environment identifier that may be used to select different variant of PID configuration file, e.g., org.ops4j.pax.url.mvn.cfg#docker. Default value: null

framework

String[]

The features providing the Karaf framework (optional)

javase

String

The Java version to use for the verify

defaultStartLevel

int

Default start level for bundles in features that don’t specify it. Default value: 30

startupRepositories

List<String>

List of compile-scope features XML files to be used in startup stage (etc/startup.properties).

bootRepositories

List<String>

List of runtime-scope features XML files to be used in boot stage (etc/org.apache.karaf.features.cfg)

installedRepositories

List<String>

List of provided-scope features XML files to be used in install stage

blacklistedRepositories

List<String>

List of blacklisted repository URIs. Blacklisted URI may use globs and version ranges.

startupFeatures

List<String>

List of features from compile-scope features XML files and KARs to be installed into system repo and listed in etc/startup.properties.

bootFeatures

List<String>

List of features from runtime-scope features XML files and KARs to be installed into system repo and listed in featuresBoot property in etc/org.apache.karaf.features.cfg

installedFeatures

List<String>

List of features from provided-scope features XML files and KARs to be installed into system repo and not mentioned elsewhere.

blacklistedFeatures

List<String>

List of feature blacklisting clauses. Each clause is in one of the formats (feature-name, feature-name;range=version-or-range, feature-name/version-or-range

startupBundles

List<String>

List of compile-scope bundles added to etc/startup.properties

bootBundles

List<String>

List of runtime-scope bundles wrapped in special feature added to featuresBoot property in etc/org.apache.karaf.features.cfg

installedBundles

List<String>

List of provided-scope bundles added to system repo

blacklistedBundles

List<String>

List of blacklisted bundle URIs. Blacklisted URI may use globs and version ranges.

profilesUris

List<String>

List of profile URIs to use

startupProfiles

List<String>

List of profiles names to load from configured profilesUris and use as startup profiles.

bootProfiles

List<String>

List of profiles names to load from configured profilesUris and use as boot profiles.

installedProfiles

List<String>

List of profiles names to load from configured profilesUris and use as installed profiles.

blacklistedProfiles

List<String>

List of blacklisted profile names (possibly using * glob).

writeProfiles

boolean

When assembly custom distribution, we can include generated and added profiles in the distribution itself, in ${karaf.etc}/profiles directory. Default value: false

generateConsistencyReport

String

When assembly custom distribution, we can also generate an XML/XSLT report with the summary of bundles. This parameter specifies target directory, to which bundle-report.xml and bundle-report-full.xml (along with XSLT stylesheet) will be written.

consistencyReportProjectName

String

When generating consistency report, we can specify project name. Default value: Apache Karaf

consistencyReportProjectVersion

String

When generating consistency report, we can specify project version. Default value: ${project.version}
karaf:archive
Note

This goal is run as part of the karaf-assembly packaging.

The karaf:archive goal packages a Karaf instance archive from a given assembled instance.

Both tar.gz and zip formats are generated in the destination folder.

Example

The example below create archives for the given Karaf instance:

<project>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.karaf.tooling</groupId>
        <artifactId>karaf-maven-plugin</artifactId>
        <version>${project.version}</version>
          <executions>
            <execution>
              <id>generate</id>
              <phase>package</phase>
              <goals>
                <goal>archive</goal>
              </goals>
              <configuration>
                <destDir>${project.build.directory}</destDir>
                <targetServerDirectory>${project.build.directory}/assembly</targetServerDirectory>
                <targetFile>${project.file}</targetFile>
              </configuration>
            </execution>
          </executions>
        </plugin>
    </plugins>
  </build>
</project>
Parameters
Name Type Description

destDir

File

The target directory of the project. Default value: ${project.build.directory}

targetServerDirectory

File

The location of the server repository. Default value: ${project.build.directory}/assembly

pathPrefix

String

Path prefix of files in the created archive. Default value: ${project.artifactId}-${project.version}

usePathPrefix

boolean

Use a path prefix of files in the created archive. Default value: false

targetFile

File

The target file to set as the project’s artifact. Default value: ${project.artifactId}-${project.version}

archiveZip

Boolean

Switches creation of *.zip artifact on or off. Default value: true

archiveTarGz

Boolean

Switches creation of *.tar.gz artifact on or off. Default value: true

attach

boolean

Whether to attach the resulting assembly to the project as an artifact. Default value: true

classifier

String

If supplied, the classifier for the artifact when attached.

useSymLinks

boolean

Use symbolic links in tar.gz or zip archives. Symbolic links are not very well supported by windows Platform. At least, is does not work on WinXP + NTFS, so do not include them for now. Default value: false

Run, client, deploy goals

These goals allows you to run Karaf via Maven or interact with a running instance.

karaf:run

karaf:run goal runs a Karaf instance from Maven.

It can use the current project if it’s a bundle to directly deploy the project artifact in the running Karaf instance.

Example
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.karaf.tooling</groupId>
                <artifactId>karaf-maven-plugin</artifactId>
                <executions>
                    <execution>
                        <id>run</id>
                        <goals>
                            <goal>run</goal>
                        </goals>
                        <configuration>
                            <karafDistribution>mvn:org.apache.karaf/apache-karaf/4.2.4/zip</karafDistribution>
                            <keepRunning>false</keepRunning>
                            <deployProjectArtifact>false</deployProjectArtifact>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
Parameters
Name Type Description

karafDirectory

File

Directory containing Karaf container base directory. Default value: ${project.build.directory}/karaf

karafDistribution

File

Location where to download the Karaf distribution. Default value: mvn:org.apache.karaf/apache-karaf/LATEST/zip

deployProjectArtifact

boolean

Define if the project artifact should be deployed in the started container or not. Default value: true

featureRepositories

String[]

A list of URLs referencing feature repositories that will be added to the karaf instance started by this goal.

featuresToInstall

String

Comma-separated list of features to install.

keepRunning

boolean

Define if the Karaf container keep running or stop just after the goal execution. Default value: true

startSsh

boolean

Define if the Karaf embedded sshd should be started or not. Default value: false
karaf:client

The karaf:client interacts with a running Karaf instance directly from Maven via SSH.

Example
<execution>
    <id>client</id>
    <goals>
        <goal>client</goal>
    <goals>
    <configuration>
        <commands>
            <command>
                <rank>1</rank>
                <command>feature:install foo</command>
            </command>
        </commands>
    </configuration>
</execution>
Parameters
Name Type Description

port

int

SSH port of the running Karaf instance. Default value: 8101

host

String

Hostname or IP address of the running Karaf instance. Default value: localhost

user

String

The username to connect to the running Karaf instance. Default value: karaf

password

String

The password to connect to the running Karaf instance. Default value: karaf

keyFile

File

The key file to use to connect to the running Karaf instance.

attempts

int

The number of attempts to connect to the running Karaf instance. Default value: 0

delay

int

The delay (in second) to wait before trying to connect to the Karaf instance. Default value: 2

commands

List<CommandDescriptor>

The list of the commands to execute on the running Karaf instance.

scripts

List<ScriptDescriptor>

The list of the scripts to execute on the running Karaf instance.

skip

boolean

Skip or not the execution of the client goal execution. Default value: false
karaf:deploy

The karaf:deploy goal allows you to deploy bundles on a running Karaf instance (via SSH or JMX).

Example
<execution>
    <id>deploy</id>
    <goals>
        <goal>deploy</goal>
    <goals>
    <configuration>
        <useProjectArtifact>true</useProjectArtifact>
    </configuration>
</execution>
Parameters
Name Type Description

port

int

SSH port of the running Karaf instance. Default value: 8101

host

String

Hostname or IP address of the running Karaf instance. Default value: localhost

user

String

The username to connect to the running Karaf instance. Default value: karaf

password

String

The password to connect to the running Karaf instance. Default value: karaf

keyFile

File

The key file to use to connect to the running Karaf instance.

attempts

int

The number of attempts to connect to the running Karaf instance. Default value: 0

delay

int

The delay (in second) to wait before trying to connect to the Karaf instance. Default value: 2

instance

String

Name of the Karaf instance. Default value: karaf-root

useSsh

boolean

Define if the deployment is done via SSH or via JMX. Default value: false

useProjectArtifact

boolean

Define if deploy uses the current Maven project artifact (in the case of the project is a bundle project). Default value: true

artifactLocations

List<String>

The list of bundle locations (mvn, http, file, …​ URLs) to deploy.

Dockerfile, Docker

The Karaf Maven plugin is also able to generate Dockerfile and eventually interact with a local Docker daemon.

Dockerfile

The karaf:dockerfile goal creates a ready to use Dockerfile for a given Karaf distribution/assembly.

Example
<execution>
    <id>dockerfile</id>
    <goals>
        <goal>dockerfile</goal>
    </goals>
</execution>
Parameters
Name Type Description

destDir

File

The directory where the Dockerfile is generated. Default value: ${project.build.directory}

assembly

File

The directory containing the Karaf assembly (as generated by karaf:assembly). Default value: ${project.build.directory}/assembly
Docker

The karaf:docker goal interacts directly with a local Docker daemon (via the command line) to directly create a Docker image with your Karaf assembly.

Note

This goal requires a local Docker daemon and runs only on Unix. The docker command has to be in the PATH.
Example
<execution>
    <id>docker</id>
    <goals>
        <goal>docker</docker>
    </goals>
</execution>
Parameters
Name Type Description

location

File

The directory containing the Dockerfile (can be generated by karaf:dockerfile). Default value: ${project.build.directory}

imageName

String

The name of the generated Docker image. Default value: karaf