Apache Karaf Cookbook

The first step is generating a template command project. To encourage building custom commands, the community has provided the following Maven archetype invocation to generate Karaf command projects:

mvn archetype:generate \
  -DarchetypeGroupId=org.apache.karaf.archetypes \
  -DarchetypeArtifactId=karaf-command-archetype \
  -DarchetypeVersion=3.0.0 \
  -DgroupId=com.packt.chapter1 \
  -DartifactId=command \
-Dversion=1.0.0-SNAPSHOT \
-Dpackage=com.packt

In the preceding archetype invocation, we supply the Maven project group and artifact names. The process will request you to supply a command name. Maven then generates a project template for your command.

The next step is implementing your custom code. The custom command template project will supply you with a Maven POM file, Blueprint wiring (in the src/main/resources/OSGI-INF/blueprint directory), and custom command stub implementation (in the src/main/java/ directory). Edit these files as required to add your custom actions.

The last step is building and deploying the custom command in Karaf. We build our command via the Maven invocation mvn install. Deploying it in Karaf only requires issuing a well-formed install command; to do this, invoke install –s mvn:groupId/artifactId in the Karaf console. Consider the following invocation:

karaf@root()> install –s mvn:com.packt.chapter1/command
 Bundle ID: 88
karaf@root()>

The preceding invocation has the groupId value as com.packt.chapter1 and the artifactId value as command.

The first step is generating a Maven-based project structure. For this recipe, we need to only create the bare of Maven POM files, set its packaging to bundle, and include a build section.

The next step is adding a resource directive to our POM file's build section. In our POM file, we add a resource directive to our build section, as shown in the following code:

<resource>
  <directory>
    ${project.basedir}/src/main/resources
  </directory>
  <filtering>true</filtering>
  <includes>
    <include>**/*</include>
  </includes>
</resource>

We add a resource directive to our build section to instruct Maven to process the contents of our resources folder, filter any wildcards, and include the result in the generated bundle.

Next, we configure the Maven Bundle Plugin as shown in the following code:

<configuration>
  <instructions>
    <Bundle-SymbolicName>
      ${project.artifactId}
    </Bundle-SymbolicName>
    <Import-Package>*</Import-Package>
    <Private-Package>!*</Private-Package>
    <Export-Package>
      org.apache.karaf.branding
    </Export-Package>
    <Spring-Context>
      *;publish-context:=false
    </Spring-Context>
  </instructions>
</configuration>

We configured the Maven Bundle Plugin to export Bundle-SymbolicName as the artifactId and set the Export-Package option to org.apache.karaf.branding. The symbolic name as the project's artifactId variable is a common convention among Karaf bundle developers. We export the Karaf branding package so that the Karaf runtime will identify the bundle as containing the custom branding.

The next step is creating our custom branding resource file. Returning to our project, we'll create a branding.properties file in the src/main/resource/org/apache/karaf/branding directory. This .properties file will contain ASCII and Jansi text characters, organized to produce your custom look. Using Maven resource filtering, you can use variable substitutions in the ${variable} format, as shown in the following code:

##
welcome = \
\u001B[33m\u001B[0m\n\
\u001B[33m      _       ___  ____    ______  \u001B[0m\n\
\u001B[33m     / \\    |_  ||_  _|  .' ___  | \u001B[0m\n\
\u001B[33m    / _ \\     | |_/ /   / .'   \\_| \u001B[0m\n\
\u001B[33m   / ___ \\    |  __'.   | |        \u001B[0m\n\
\u001B[33m _/ /   \\ \\_ _| |  \\  \\_ \\ '.___.'\\ \u001B[0m\n\
\u001B[33m|____| |____||____||____| '.____ .' \u001B[0m\n\
\u001B[33m                                   \u001B[0m\n\
\u001B[33m       Apache Karaf Cookbook       \u001B[0m\n\
\u001B[33m Packt Publishing - http://www.packtpub.com\u001B[0m\n\
\u001B[33m       (version ${project.version})\u001B[0m\n\
\u001B[33m\u001B[0m\n\
\u001B[33mHit '\u001B[1m<tab>\u001B[0m' for a list of available commands\u001B[0m\n\
\u001B[33mand '\u001B[1m[cmd] --help\u001B[0m' for help on a specific command.\u001B[0m\n\
\u001B[33mHit '\u001B[1m<ctrl-d>\u001B[0m' or '\u001B[1mosgi:shutdown\u001B[0m' to shutdown\u001B[0m\n\
\u001B[33m\u001B[0m\n\

In the preceding code, we use a combination of ASCII characters and Jansi text markup in the branding.properties file to produce simple text effects in Karaf, as shown in the following screenshot:

The final step is building and deploying our custom branding. We build our branding via the Maven invocation mvn install. After we build our branding bundle, we place a copy inside Karaf's KARAF_HOME/lib folder and then start the container. Upon the first boot, you will see our custom branding displayed.

The first step is generating a Maven-based project. For this recipe, we need to create a Maven POM file, set its packaging to bundle, and include a build section.

The next step is editing the POM file's build directives. We add a resources directive to our POM file's build section and maven-resources-plugin and build-helper-maven-plugin to its plugin list. Consider the following code:

<resources>
    <resource>
        <directory>src/main/resources</directory>
        <filtering>true</filtering>
    </resource>
</resources>

In the preceding code, the resources directive indicates the location of the features file we'll create for processing. Now, consider the following code:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-resources-plugin</artifactId>
    <executions>
        <execution>
            <id>filter</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>resources</goal>
            </goals>
        </execution>
    </executions>
</plugin>

In the preceding code, maven-resources-plugin is configured to process our resources. Now, consider the following code:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>build-helper-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>attach-artifacts</id>
            <phase>package</phase>
            <goals>
                <goal>attach-artifact</goal>
            </goals>
            <configuration>
                <artifacts>
                    <artifact>
                        <file>${project.build.directory}/classes/${features.file}</file>
                        <type>xml</type>
                        <classifier>features</classifier>
                    </artifact>
                </artifacts>
            </configuration>
        </execution>
    </executions>
</plugin>

Finally, build-helper-maven-plugin completes the build of our features.xml file as described in the preceding code.

The third step is creating a features.xml resource. In the src/main/resources folder, add a file named features.xml with the details of your bundles, as shown in the following code:

<?xml version="1.0" encoding="UTF-8"?>

<features>

  <feature name='moduleA' version='${project.version}'>
    <bundle>
      mvn:com.packt/moduleA/${project.version}
    </bundle>
  </feature>

  <feature name='moduleB' version='${project.version}'>
    <bundle>
      mvn:com.packt/moduleB/${project.version}
    </bundle>
  </feature>

  <feature name='recipe4-all-modules' version='${project.version}'>
    <feature version='${project.version}'>moduleA</feature>
    <feature version='${project.version}'>moduleB</feature>
  </feature>

</features>

We provide each feature with a name that Karaf will use as a reference to install each element specified in the named feature's configuration. Features may reference other features, thus providing fine-grained control over installation. In the preceding features file, we can see three named features: moduleA, moduleB, and recipe4-all-modules. The recipe4-all-modules feature includes the content of the other two features.

The final step is building and deploying our feature. Using our sample recipe project, we will build our feature by executing mvn install. This performs all of the feature file variable substitutions and installs a processed copy in your local m2 repository.

To make our feature available to Karaf, we'll add the feature file's Maven coordinates as follows:

karaf@root()>feature:repo-add mvn:com.packt/features-file/1.0.0-  SNAPSHOT/xml/features

Now, we can use Karaf's feature commands to install moduleA and moduleB, as shown in the following command-line snippet:

karaf@root()>feature:install recipe4-all-modules
Apache Karaf starting moduleA bundle
Apache Karaf starting moduleB bundle
karaf@root()>

Using feature:install in this fashion helps to promote repeatable deployments and avoid missing component installations that are not caught by the OSGi environment (if no bundle dependencies are missing, then as far as the container is concerned, all is well). We can verify whether our feature is installed by invoking the following command:

karaf@root()>feature:list | grep –i "recipe"

We can then observe whether our feature is listed or not.

The first step is editing the management configuration. Apache Karaf ships with a default management configuration. To make our modifications, we update the etc/org.apache.karaf.management.cfg file. Consider the following code:

#
# Port number for RMI registry connection
#
rmiRegistryPort = 11099

#
# Port number for RMI server connection
#
rmiServerPort = 44445

The default ports, 1099 and 44444, are usually fine for general deployment. Change these ports only if you are experiencing port conflicts on your deployment. Now, consider the following snippet:

#
# Role name used for JMX access authorization
# If not set, this defaults to the ${karaf.admin.role} configured in etc/system.properties
#
jmxRole=admin

Towards the bottom of the configuration file, there will be a commented-out entry for jmxRole; enable this by removing the hash character.

The next step is updating the user's file. We must now update the etc/users.properties file with the following code:

karaf = karaf,_g_:admingroup
_g_\:admingroup = group,admin,manager,viewer,jmxRole

The users.properties file is used to configure users, groups, and roles in Karaf. We append jmxRole to the admin group. The syntax for this file follows the Username = password, groups format.

The last step is testing our configuration. After making the previous configuration changes, we'll need to restart our Karaf instance. Now, we can test our JMX setup. Have a look at the following screenshot:

After restarting Karaf, use a JMX-based admin tool of your choice (the previous screenshot shows JConsole) to connect to the container. Due to image size restrictions, the full URL couldn't be displayed. The full URL is service:jmx:rmi://127.0.0.1:44445/jndi/rmi://127.0.0.1:11099/karaf-root. The syntax of the URL is service:jmx:rmi://host:${rmiServerPort}/jndi/rmi://host:${rmiRegistryPort}/${karaf-instance-name}.

The first step is editing the shell configuration. Apache Karaf ships with a default shell configuration file. It's a good practice to edit entries in the etc/org.apache.karaf.shell.cfg file to point to the non-default ports as a security precaution. Consider the following code:

#
# Via sshPort and sshHost you define the address you can login into Karaf.
#
sshPort = 8102
sshHost = 192.168.1.110

In the preceding sample configuration, we defined the port for SSH access to 8102 and set sshHost to an IP address of the host machine (the default value, 0.0.0.0, means the SSHD service is bound to all network interfaces). Restricting access to particular network interfaces can help reduce unwanted access.

The next step is restarting Karaf. After editing the configuration, we must restart Karaf. Once restarted, you'll be able to connect to Karaf using an SSH client command as follows:

ssh –p 8102 karaf@127.0.0.1

Upon connection, you'll be prompted for your password.

The first step is installing the service wrapper feature. Apache Karaf utilizes a service wrapper feature to handle gathering and deploying of the required resources for your host operating environment. We begin its installation by invoking the following command:

karaf@root()>feature:install service-wrapper

The service wrapper feature URL is included in Karaf by default; so, no additional step is required to make it available.

The next step is installing the wrapper service. Now, we must instruct the wrapper to configure and install the appropriate service scripts and resources for us. Consider the following command:

karaf@root()>wrapper:install –s AUTO_START –n Karaf3 –D "Apache Karaf Cookbook"

The preceding wrapper:install command invocation includes three flags: -s for the start type, -n for the service name, and –D for the service description. The start type can be one of two options: AUTO_START, to automatically start the service on boot, and DEMAND_START, to start only when manually invoked. The service name is used as an identifier in the host's service registry. The description provides system administrators with a brief description of your Karaf installation. After executing the install command, the Karaf console will display the libraries, scripts, and configuration files that the wrapper generates. You'll now need to exit Karaf to continue the service installation.

The final step is integrating it in to the host operating system. This step will require administrator level permissions to execute the generated Karaf service wrapper installation scripts.

The following command installs the service natively into Windows:

C:> C:\Path\To\apache-karaf-3.0.0\bin\Karaf3-service.bat install

The following net commands allow an administrator to start or stop the Karaf service:

C:> net start "Karaf3"
C:> net stop "Karaf3"

Linux integration will vary based on distribution. The following commands will work on Debian- or Ubuntu-based systems:

jgoodyear@ubuntu1204:~$ ln –s /Path/To/apache-karaf-3.0.0/bin/Karaf3-service /etc/init.d
jgoodyear@ubuntu1204:~$ update-rc.d Karaf3-service defaults
jgoodyear@ubuntu1204:~$ /etc/init.d/Karaf3-service start
jgoodyear@ubuntu1204:~$ /etc/init.d/Karaf3-service stop

The first command creates a symbolic link from the service script in Karaf's bin folder to the init.d directory and then updates the startup scripts to include the Karaf service to automatically start during boot. The remaining two commands can be used to manually start or stop the Karaf service.

The first step is editing the system properties file. To enable a Master/Slave failover, we edit the etc/system.properties file of two or more Karaf instances to include the following Karaf locking configuration:

##
## Sample lock configuration
##
karaf.lock=true
karaf.lock.class=org.apache.karaf.main.lock.SimpleFileLock
# specify path to lock directory
karaf.lock.dir=[PathToLockFileDirectory]
karaf.lock.delay=10

The previous configuration sample contains the essential entries for a file-based locking mechanism, that is, two or more Karaf instances attempt to gain exclusive ownership of a file over a shared filesystem.

The next step is providing locking resources. If using a shared locking file approach is suitable to your deployment, then all you must do at this time is mount the filesystem on each machine that'll host Karaf instances in the Master/Slave deployment.

Each Karaf instance will include the same lock directory location on a shared filesystem common to each Karaf installation. If a shared filesystem is not practical between systems, then a JDBC locking mechanism can be used. This is described in the following code:

karaf.lock=true
karaf.lock.class=org.apache.karaf.main.DefaultJDBCLock
karaf.lock.delay=10
karaf.lock.jdbc.url=jdbc:derby://dbserver:1527/sample
karaf.lock.jdbc.driver=org.apache.derby.jdbc.ClientDriver
karaf.lock.jdbc.user=user
karaf.lock.jdbc.password=password
karaf.lock.jdbc.table=KARAF_LOCK
karaf.lock.jdbc.clustername=karaf
karaf.lock.jdbc.timeout=30

The JDBC configuration is similar to the SimpleFileLock configuration. However, it is expanded to contain the JDBC url, driver, timeout, user, and password options. Two additional JDBC options are included to allow for multiple Master/Slave Karaf deployments to use a single database. These are the JDBC table and clustername options. The JDBC table property sets the database table to use for the lock, and the JDBC clustername property specifies which pairing group a Karaf instance belongs to (for example, hosts A and B belong to a cluster prod group, and hosts C and D belong to a cluster dev group).

When using the JDBC locking mechanism, you'll have to provide the relevant JDBC driver JAR file to Karaf's lib/ext folder. For specific database configurations, consult Karaf's user manual (http://karaf.apache.org/manual/latest/index.html).

The final step is verifying the lock behavior. Once you have configured each Karaf instance to be a participant of the Master/Slave deployment and ensured that any locking resources have been made available (mounted filesystems or database drivers/connectivity), you must now validate that it is all working as desired. The general test to perform is to start one instance of Karaf, allow it to gain the lock (you'll see this recorded in the logfile), and then start all additional instances. Only the first instance should be fully booted; the others should be trying to gain the lock. Stopping this first instance should result in another instance becoming the Master. This verification step is vital. Most Master/Slave deployment failures occur due to misconfigurations or shared resource permissions.