Branding the Console

This chapter will show you how to customize the user interface of the Karaf console, making
changes such as a new welcome message and console prompt. This is what we refer to as "branding" Karaf.

There are 2 ways of branding the Karaf console: (1) adding a branding.properties file to etc, and (2) creating a branding bundle.

Adding a branding.properties file to etc

Create a etc/branding.properties file similar to:

{

}
welcome = \
\u001B[36m        __ __                  ____      \u001B[0m\r\n\
\u001B[36m       / //_/____ __________ _/ __/      \u001B[0m\r\n\
\u001B[36m      / ,<  / __ `/ ___/ __ `/ /_        \u001B[0m\r\n\
\u001B[36m     / /| |/ /_/ / /  / /_/ / __/        \u001B[0m\r\n\
\u001B[36m    /_/ |_|\\__,_/_/   \\__,_/_/         \u001B[0m\r\n\
\r\n\
\u001B[1m  Apache Karaf\u001B[0m (2.4.5-SNAPSHOT)\r\n\
\r\n\
Hit '\u001B[1m<tab>\u001B[0m' for a list of available commands\r\n\
   and '\u001B[1m[cmd] --help\u001B[0m' for help on a specific command.\r\n\
Hit '\u001B[1m<ctrl-d>\u001B[0m' or '\u001B[1mosgi:shutdown\u001B[0m' to shutdown Karaf.\r\n

prompt = \u001B[1m${USER}@${APPLICATION}\u001B[0m>
{

}

Start Karaf and you will see your branded Karaf console.

Creating and deploying a branding bundle

At startup, Karaf is looking for a bundle which exports the org.apache.karaf.branding package containing a branding.properties
file.

So you need to create a very simple bundle containing just a org/apache/karaf/branding/branding.properties file.

The Maven POM of your branding bundle should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <groupId>your.group.id</groupId>
    <artifactId>your.branding.artifact.id</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>bundle</packaging>
    <name>Your Branding Bundle Name</name>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <version>2.2</version>
                <extensions>true</extensions>
                <configuration>
                    <instructions>
                        <Bundle-SymbolicName>manual</bundle-SymbolicName>
                        <Import-Package>*</Import-Package>
                        <Private-Package>!*</Private-Package>
                        <Export-Package>
                            org.apache.karaf.branding
                        </Export-Package>
                        <Spring-Context>*;public-context:=false</Spring-Context>
                    </instructions>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

Now, add a src/main/resources/org/apache/karaf/branding/branding.properties similar to:

{

}
welcome = \
\u001B[36m        __ __                  ____      \u001B[0m\r\n\
\u001B[36m       / //_/____ __________ _/ __/      \u001B[0m\r\n\
\u001B[36m      / ,<  / __ `/ ___/ __ `/ /_        \u001B[0m\r\n\
\u001B[36m     / /| |/ /_/ / /  / /_/ / __/        \u001B[0m\r\n\
\u001B[36m    /_/ |_|\\__,_/_/   \\__,_/_/         \u001B[0m\r\n\
\r\n\
\u001B[1m  Apache Karaf\u001B[0m (2.4.5-SNAPSHOT)\r\n\
\r\n\
Hit '\u001B[1m<tab>\u001B[0m' for a list of available commands\r\n\
   and '\u001B[1m[cmd] --help\u001B[0m' for help on a specific command.\r\n\
Hit '\u001B[1m<ctrl-d>\u001B[0m' or '\u001B[1mosgi:shutdown\u001B[0m' to shutdown Karaf.\r\n

prompt = \u001B[1m${USER}@${APPLICATION}\u001B[0m>
{

}

As you can see, the branding.properties contains two properties:

• welcome is the welcome message displayed when you start Karaf.
• prompt is the string used to display the console prompt. This string supports variables:
  • $} defines the user name of the prompt. Caveat – the user name is presently static and hardcoded to "karaf",

    however you can override here with your own static user name.

  • ${{APPLICATION}} defines the Karaf instance name.

As you can see, both strings support ASCII escaped format. For instance \u001B[1m switches the foreground to bold and \u001B[0m
switches it back to normal.

Some examples of customized prompts:

# Define a user with fancy colors
prompt = \u001B[36mmy-karaf-user\u001B[0m\u001B[1m@\u001B[0m\u001B[34m${APPLICATION}\u001B[0m>

# Static sober prompt
prompt = my-user@my-karaf>

Configuring Karaf to use the branding bundle

In order for Karaf to pick up the branding jar please edit the
$KARAF_HOME/etc/custom.properties file to include the following:

org.osgi.framework.system.packages.extra = \
org.apache.karaf.branding

Installing the branding bundle

Build your branding bundle:

mvn install

and simply drop the generated jar file into the Karaf lib directory.

Start Karaf and you will see your branded Karaf console.