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}
4.0.0
your.group.id
your.branding.artifact.id
1.0-SNAPSHOT
bundle
Your Branding Bundle Name
org.apache.felix
maven-bundle-plugin
2.2
true
${project.artifactId}
*
!*
org.apache.karaf.branding
*;public-context:=false
{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\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\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.