manual/src/main/webapp/developers-guide/branding-console.conf

h1. 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.

h2. Create your 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:

{code:lang=xml}
<?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>${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>
{code}

Now, add a {{src/main/resources/org/apache/karaf/branding/branding.properties}} 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}}

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:
** ${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 to bold and \u001B[0m
switches it back to normal.

Some examples of customized prompts:

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

{code}
# Static sober prompt
prompt = my-user@my-karaf>
{code}

h2. 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


h2. Installing the branding bundle

Build your branding bundle:

{code}
mvn install
{code}

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

Start Karaf and you will see your branded Karaf console.