Branding

Console

You can "brand" the Apache Karaf console.

By branding, it means that you can define your own:

the welcome message (motd or Message Of The Day) displayed when you start the console
the prompt displayed to the users

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:

code 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 (${project.version})\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> code

Start Karaf and you will see your branded Karaf console.

Branding bundle

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

Basically, a branding bundle is a very simple bundle, just containing a org/apache/karaf/branding/branding.properties file.

It’s easy to create such branding bundle using Apache Maven.

The following pom.xml creates a branding bundle:

<?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.4.0</version>
                <extensions>true</extensions>
                <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>*;public-context:=false</Spring-Context>
                    </instructions>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

You can put your branding.properties file in the project resources (src/main/resources/org/apache/karaf/branding/branding.properties):

welcome = This is my Karaf brand\r\n
prompt = Hey ${USER}>

For instance, the default Apache Karaf branding properties file contains:

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 (${project.version})\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 type '\u001B[1msystem:shutdown\u001B[0m' or '\u001B[1mlogout\u001B[0m' to shutdown Karaf.\r\n

As you can see, the branding.properties contains two properties: * welcome is the welcome message displayed when you start Apache Karaf console. * prompt is the string used to display the console prompt. This string supports variables: ${USER` 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 in bold and \u001B[0m switch back to normal.

Some examples of customized prompt examples follow:

# 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>

Installing the branding bundle

Thanks to the pom.xml, we can use mvn to build the branding bundle:

mvn install

You just have to drop the file in the lib directory:

cp branding.jar /opt/apache-karaf-3.0.0/lib/karaf-branding.jar

You can now start Apache Karaf to see your branded console.

WebConsole

It’s also possible to brand the Apache Karaf WebConsole.

You have to create a bundle, fragment of the Apache Karaf WebConsole.

This WebConsole branding bundle contains a META-INF/webconsole.properties containing branding properties:

#
# This file contains branding properties to overwrite the default
# branding of the Apache Felix Web Console when deployed in an
# Apache Karaf application.


webconsole.brand.name = My Web Console

webconsole.product.name = My Karaf
webconsole.product.url = http://karaf.apache.org/
webconsole.product.image = /res/karaf/imgs/logo.png

webconsole.vendor.name = The Apache Software Foundation
webconsole.vendor.url = http://www.apache.org
webconsole.vendor.image = /res/karaf/imgs/logo.png

webconsole.favicon = /res/karaf/imgs/favicon.ico
webconsole.stylesheet = /res/karaf/ui/webconsole.css

The bundle also provides the css stylesheet and images defined in this properties file.

As for console, you can use the following pom.xml to create the WebConsole branding bundle:

<?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>my.group.id</groupId>
    <artifactId>branding</artifactId>
    <packaging>bundle</packaging>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <version>2.4.0</version>
                <extensions>true</extensions>
                <configuration>
                    <instructions>
                        <Bundle-DocURL>http://felix.apache.org/site/apache-karaf.html</Bundle-DocURL>
                        <Fragment-Host>org.apache.karaf.webconsole.console;bundle-version="[3,4)"</Fragment-Host>
                        <Export-Package>!*</Export-Package>
                        <Import-Package>
                            javax.servlet;version=2.4,
                            javax.servlet.http;version=2.4,
                            !org.apache.felix.webconsole*,
                            org.apache.aries.blueprint,
                            org.osgi.service.blueprint.container,
                            org.osgi.service.blueprint.reflect,
                            *
                        </Import-Package>
                    </instructions>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

With the webconsole feature installed, you can install this bundle (using bundle:install or by editing the etc/startup.properties), you will see the WebConsole with your branding.