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

  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 (4.0.0)\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.

Adding a branding-ssh.properties file to etc

In a similar way, a etc/branding-ssh.properties file can be added. It should contain the same welcome and prompt entries but those will be used for external clients connecting through ssh. The values default to the ones in etc/branding.properties if this file is not defined.

Branding bundle

At startup, Apache Karaf is looking for a bundle which exports the org.apache.karaf.branding package, containing a branding.properties and/or branding-ssh.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-4.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.