Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 31. Configuration

31.1. Files
Copy link

Apache Karaf stores and loads all configuration in files located in the etc folder.

By default, the etc folder is located relatively to the KARAF_BASE folder. You can define another location using the KARAF_ETC variable.

Each configuration is identified by a ID (the ConfigAdmin PID). The configuration files name follows the pid.cfg name convention.

For instance, etc/org.apache.karaf.shell.cfg means that this file is the file used by the configuration with org.apache.karaf.shell as PID.

A configuration file is a properties file containing key/value pairs: 

property=value

Properties can be referenced inside configuration files using the syntax ${<name>}. Default and alternate values can be specified using ${<name>:-<default_value>} and ${<name>:+<alternate_value>} syntaxes respectively. 

existing_property=baz
property1=${missing_property:-foo}   # "foo"
property2=${missing_property:+foo}   # empty string
property3=${existing_property:-bar}  # "baz"
property4=${existing_property:+bar}  # "bar"

Environment variables can be referenced inside configuration files using the syntax ${env:<name>} (e.g. property=${env:FOO} will set "property" to the value of the enviroment variable "FOO"). Default and alternate values can be defined for them as well using the same syntax as above.

In Apache Karaf, a configuration is PID with a set of properties attached.

Apache Karaf automatically loads all *.cfg files from the etc folder.

You can configure the behaviour of the configuration files using some dedicated properties in the etc/config.properties configuration file: 

...
#
# Configuration FileMonitor properties
#
felix.fileinstall.enableConfigSave = true
felix.fileinstall.dir    = ${karaf.etc}
felix.fileinstall.filter = .*\\.(cfg|config)
felix.fileinstall.poll   = 1000
felix.fileinstall.noInitialDelay = true
felix.fileinstall.log.level = 3
felix.fileinstall.log.default = jul
...
  • felix.fileinstall.enableConfigSave flush back in the configuration file the changes performed directly on the configuration service (ConfigAdmin). If true, any change (using config:* commands, MBeans, OSGi service) is persisted back in the configuration false. Default is true.
  • felix.fileinstall.dir is the directory where Apache Karaf is looking for configuration files. Default is ${karaf.etc} meaning the value of the KARAF_ETC variable.
  • felix.fileinstall.filter is the file name pattern used to load only some configuration files. Only files matching the pattern will be loaded. Default value is .*\\.(cfg|config) meaning *.cfg and *.config files.
  • felix.fileinstall.poll is the polling interval (in milliseconds). Default value is 1000 meaning that Apache Karaf "re-loads" the configuration files every second.
  • felix.fileinstall.noInitialDelay is a flag indicating if the configuration file polling starts as soon as Apache Karaf starts or wait for a certain time. If true, Apache Karaf polls the configuration files as soon as the configuration service starts.
  • felix.fileinstall.log.level is the log message verbosity level of the configuration polling service. More this value is high, more verbose the configuration service is.
  • felix.fileinstall.log.default is the logging framework to use, jul meaning Java Util Logging.

You can change the configuration at runtime by directly editing the configuration file.

You can also do the same using the config:* commands or the ConfigMBean.

31.1.1. config:* commands
Copy link

Apache Karaf provides a set of commands to manage the configuration.

31.1.1.1. config:list
Copy link

config:list displays the list of all configurations available, or the properties in a given configuration (PID).

Without the query argument, the config:list command display all configurations, with PID, attached bundle and properties defined in the configuration: 

karaf@root()> config:list
----------------------------------------------------------------
Pid:            org.apache.karaf.service.acl.command.system.start-level
BundleLocation: mvn:org.apache.karaf.shell/org.apache.karaf.shell.console/4.0.0
Properties:
   service.guard = (&(osgi.command.scope=system)(osgi.command.function=start-level))
   * = *
   start-level = admin                           # admin can set any start level, including < 100
   start-level[/[^0-9]*/] = viewer               # viewer can obtain the current start level
   execute[/.*/,/[^0-9]*/] = viewer               # viewer can obtain the current start level
   execute = admin                           # admin can set any start level, including < 100
   service.pid = org.apache.karaf.service.acl.command.system.start-level
   start-level[/.*[0-9][0-9][0-9]+.*/] = manager # manager can set startlevels above 100
   execute[/.*/,/.*[0-9][0-9][0-9]+.*/] = manager # manager can set startlevels above 100
----------------------------------------------------------------
Pid:            org.apache.karaf.log
BundleLocation: mvn:org.apache.karaf.log/org.apache.karaf.log.core/4.0.0
Properties:
   service.pid = org.apache.karaf.log
   size = 500
   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
   felix.fileinstall.filename = file:/opt/apache-karaf-4.0.0/etc/org.apache.karaf.log.cfg
...

The query argument accepts a query using a LDAP syntax.

For instance, you can display details on one specific configuration using the following filter: 

karaf@root()> config:list "(service.pid=org.apache.karaf.log)"
----------------------------------------------------------------
Pid:            org.apache.karaf.log
BundleLocation: mvn:org.apache.karaf.log/org.apache.karaf.log.core/4.0.0
Properties:
   felix.fileinstall.filename = file:/opt/apache-karaf-4.0.0/etc/org.apache.karaf.log.cfg
   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
   service.pid = org.apache.karaf.log
   size = 500

31.1.1.2. config:edit
Copy link

config:edit is the first command to do when you want to change a configuration. config:edit command put you in edition mode for a given configuration.

For instance, you can edit the org.apache.karaf.log configuration: 

karaf@root()> config:edit org.apache.karaf.log

The config:edit command doesn’t display anything, it just puts you in configuration edit mode. You are now ready to use other config commands (like config:property-append, config:property-delete, config:property-set, …​).

If you provide a configuration PID that doesn’t exist yet, Apache Karaf will create a new configuration (and so a new configuration file) automatically.

All changes that you do in configuration edit mode are store in your console session: the changes are not directly applied in the configuration. It allows you to "commit" the changes (see config:update command) or "rollback" and cancel your changes (see config:cancel command).

31.1.1.3. config:property-list
Copy link

The config:property-list lists the properties for the currently edited configuration.

Assuming that you edited the org.apache.karaf.log configuration, you can do: 

karaf@root()> config:property-list
   felix.fileinstall.filename = file:/opt/apache-karaf-4.0.0/etc/org.apache.karaf.log.cfg
   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
   service.pid = org.apache.karaf.log
   size = 500

31.1.1.4. config:property-set
Copy link

The config:property-set command update the value of a given property in the currently edited configuration.

For instance, to change the value of the size property of previously edited org.apache.karaf.log configuration, you can do: 

karaf@root()> config:property-set size 1000
karaf@root()> config:property-list
   felix.fileinstall.filename = file:/opt/apache-karaf-4.0.0/etc/org.apache.karaf.log.cfg
   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
   service.pid = org.apache.karaf.log
   size = 1000

If the property doesn’t exist, the config:property-set command creates the property.

You can use config:property-set command outside the configuration edit mode, by specifying the -p (for configuration pid) option: 

karaf@root()> config:property-set -p org.apache.karaf.log size 1000
karaf@root()> config:list "(service.pid=org.apache.karaf.log)"
----------------------------------------------------------------
Pid:            org.apache.karaf.log
BundleLocation: mvn:org.apache.karaf.log/org.apache.karaf.log.core/4.0.0
Properties:
   service.pid = org.apache.karaf.log
   size = 1000
   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
   felix.fileinstall.filename = file:/opt/apache-karaf-4.0.0/etc/org.apache.karaf.log.cfg
Note

Using the pid option, you bypass the configuration commit and rollback mechanism.

31.1.1.5. config:property-append
Copy link

The config:property-append is similar to config:property-set command, but instead of completely replacing the property value, it appends a string at the end of the property value.

For instance, to add 1 at the end of the value of the size property in org.apache.karaf.log configuration (and so have 5001 for the value instead of 500), you can do: 

karaf@root()> config:property-append size 1
karaf@root()> config:property-list
   service.pid = org.apache.karaf.log
   size = 5001
   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
   felix.fileinstall.filename = file:/opt/apache-karaf-4.0.0/etc/org.apache.karaf.log.cfg

Like the config:property-set command, if the property doesn’t exist, the config:property-set command creates the property.

You can use the config:property-append command outside the configuration edit mode, by specifying the -p (for configuration pid) option: 

karaf@root()> config:property-append -p org.apache.karaf.log size 1
karaf@root()> config:list "(service.pid=org.apache.karaf.log)"
----------------------------------------------------------------
Pid:            org.apache.karaf.log
BundleLocation: mvn:org.apache.karaf.log/org.apache.karaf.log.core/4.0.0
Properties:
   service.pid = org.apache.karaf.log
   size = 5001
   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
   felix.fileinstall.filename = file:/opt/apache-karaf-4.0.0/etc/org.apache.karaf.log.cfg
Note

Using the pid option, you bypass the configuration commit and rollback mechanism.

31.1.1.6. config:property-delete
Copy link

The config:property-delete command delete a property in the currently edited configuration.

For instance, you previously added a test property in org.apache.karaf.log configuration. To delete this test property, you do: 

karaf@root()> config:property-set test test
karaf@root()> config:property-list
   service.pid = org.apache.karaf.log
   size = 500
   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
   felix.fileinstall.filename = file:/opt/apache-karaf-4.0.0/etc/org.apache.karaf.log.cfg
   test = test
karaf@root()> config:property-delete test
karaf@root()> config:property-list
   service.pid = org.apache.karaf.log
   size = 500
   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
   felix.fileinstall.filename = file:/opt/apache-karaf-4.0.0/etc/org.apache.karaf.log.cfg

You can use the config:property-delete command outside the configuration edit mode, by specifying the -p (for configuration pid) option: 

karaf@root()> config:property-delete -p org.apache.karaf.log test

31.1.1.7. config:update and config:cancel
Copy link

When you are in the configuration edit mode, all changes that you do using config:property* commands are stored in "memory" (actually in the console session).

Thanks to that, you can "commit" your changes using the config:update command. The config:update command will commit your changes, update the configuration, and (if possible) update the configuration files.

For instance, after changing org.apache.karaf.log configuration with some config:property* commands, you have to commit your change like this: 

karaf@root()> config:edit org.apache.karaf.log
karaf@root()> config:property-set test test
karaf@root()> config:update
karaf@root()> config:list "(service.pid=org.apache.karaf.log)"
----------------------------------------------------------------
Pid:            org.apache.karaf.log
BundleLocation: mvn:org.apache.karaf.log/org.apache.karaf.log.core/4.0.0
Properties:
   service.pid = org.apache.karaf.log
   size = 500
   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
   felix.fileinstall.filename = file:/opt/apache-karaf-4.0.0/etc/org.apache.karaf.log.cfg
   test = test

On the other hand, if you want to "rollback" your changes, you can use the config:cancel command. It will cancel all changes that you did, and return of the configuration state just before the config:edit command. The config:cancel exits from the edit mode.

For instance, you added the test property in the org.apache.karaf.log configuration, but it was a mistake: 

karaf@root()> config:edit org.apache.karaf.log
karaf@root()> config:property-set test test
karaf@root()> config:cancel
karaf@root()> config:list "(service.pid=org.apache.karaf.log)"
----------------------------------------------------------------
Pid:            org.apache.karaf.log
BundleLocation: mvn:org.apache.karaf.log/org.apache.karaf.log.core/4.0.0
Properties:
   service.pid = org.apache.karaf.log
   size = 500
   pattern = %d{ISO8601} | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
   felix.fileinstall.filename = file:/opt/apache-karaf-4.0.0/etc/org.apache.karaf.log.cfg

31.1.1.8. config:delete
Copy link

The config:delete command completely delete an existing configuration. You don’t have to be in edit mode to delete a configuration.

For instance, you added my.config configuration: 

karaf@root()> config:edit my.config
karaf@root()> config:property-set test test
karaf@root()> config:update
karaf@root()> config:list "(service.pid=my.config)"
----------------------------------------------------------------
Pid:            my.config
BundleLocation: null
Properties:
   service.pid = my.config
   test = test

You can delete the my.config configuration (including all properties in the configuration) using the config:delete command: 

karaf@root()> config:delete my.config
karaf@root()> config:list "(service.pid=my.config)"
karaf@root()>

31.1.1.9. config:meta
Copy link

The config:meta command lists the meta type information related to a given configuration.

It allows you to get details about the configuration properties: key, name, type, default value, and description: 

karaf@root()> config:meta -p org.apache.karaf.log
Meta type informations for pid: org.apache.karaf.log
key     | name    | type   | default                                                              | description
---------------------------------------------------------------------------------------------------------------------------------------
size    | Size    | int    | 500                                                                  | size of the log to keep in memory
pattern | Pattern | String | %d{ABSOLUTE} | %-5.5p | %-16.16t | %-32.32c{1} | %-32.32C %4L | %m%n | Pattern used to display log entries

31.1.2. JMX ConfigMBean
Copy link

On the JMX layer, you have a MBean dedicated to the management of the configurations: the ConfigMBean.

The ConfigMBean object name is: org.apache.karaf:type=config,name=*.

31.1.2.1. Attributes
Copy link

The Configs attribute is a list of all configuration PIDs.

31.1.2.2. Operations
Copy link

  • listProperties(pid) returns the list of properties (property=value formatted) for the configuration pid.
  • deleteProperty(pid, property) deletes the property from the configuration pid.
  • appendProperty(pid, property, value) appends value at the end of the value of the property of the configuration pid.
  • setProperty(pid, property, value) sets value for the value of the property of the configuration pid.
  • delete(pid) deletes the configuration identified by the pid.
  • create(pid) creates an empty (without any property) configuration with pid.
  • update(pid, properties) updates a configuration identified with pid with the provided properties map.

31.2. Using the console
Copy link

31.2.1. Available commands
Copy link

To see a list of the available commands in the console, you can use the help: 

karaf@root()> help
bundle                            Enter the subshell
bundle:capabilities               Displays OSGi capabilities of a given bundles.
bundle:classes                    Displays a list of classes/resources contained in the bundle
bundle:diag                       Displays diagnostic information why a bundle is not Active
bundle:dynamic-import             Enables/disables dynamic-import for a given bundle.
bundle:find-class                 Locates a specified class in any deployed bundle
bundle:headers                    Displays OSGi headers of a given bundles.
bundle:id                         Gets the bundle ID.
...

You have the list of all commands with a short description.

You can use the tab key to get a quick list of all commands: 

karaf@root()> Display all 294 possibilities? (y or n)
...

31.2.2. Subshell and completion mode
Copy link

The commands have a scope and a name. For instance, the command feature:list has feature as scope, and list as name.

Karaf "groups" the commands by scope. Each scope form a subshell.

You can directly execute a command with its full qualified name (scope:name): 

karaf@root()> feature:list
...

or enter in a subshell and type the command contextual to the subshell: 

karaf@root()> feature
karaf@root(feature)> list

You can note that you enter in a subshell directly by typing the subshell name (here feature). You can "switch" directly from a subshell to another: 

karaf@root()> feature
karaf@root(feature)> bundle
karaf@root(bundle)>

The prompt displays the current subshell between ().

The exit command goes to the parent subshell: 

karaf@root()> feature
karaf@root(feature)> exit
karaf@root()>

The completion mode defines the behaviour of the tab key and the help command.

You have three different modes available:

  • GLOBAL
  • FIRST
  • SUBSHELL

You can define your default completion mode using the completionMode property in etc/org.apache.karaf.shell.cfg file. By default, you have: 

completionMode = GLOBAL

You can also change the completion mode “on the fly” (while using the Karaf shell console) using the shell:completion command: 

karaf@root()> shell:completion
GLOBAL
karaf@root()> shell:completion FIRST
karaf@root()> shell:completion
FIRST

shell:completion can inform you about the current completion mode used. You can also provide the new completion mode that you want.

GLOBAL completion mode is the default one in Karaf 4.0.0 (mostly for transition purpose).

GLOBAL mode doesn’t really use subshell: it’s the same behavior as in previous Karaf versions.

When you type the tab key, whatever in which subshell you are, the completion will display all commands and all aliases: 

karaf@root()> <TAB>
karaf@root()> Display all 273 possibilities? (y or n)
...
karaf@root()> feature
karaf@root(feature)> <TAB>
karaf@root(feature)> Display all 273 possibilities? (y or n)

FIRST completion mode is an alternative to the GLOBAL completion mode.

If you type the tab key on the root level subshell, the completion will display the commands and the aliases from all subshells (as in GLOBAL mode). However, if you type the tab key when you are in a subshell, the completion will display only the commands of the current subshell: 

karaf@root()> shell:completion FIRST
karaf@root()> <TAB>
karaf@root()> Display all 273 possibilities? (y or n)
...
karaf@root()> feature
karaf@root(feature)> <TAB>
karaf@root(feature)>
info install list repo-add repo-list repo-remove uninstall version-list
karaf@root(feature)> exit
karaf@root()> log
karaf@root(log)> <TAB>
karaf@root(log)>
clear display exception-display get log set tail

SUBSHELL completion mode is the real subshell mode.

If you type the tab key on the root level, the completion displays the subshell commands (to go into a subshell), and the global aliases. Once you are in a subshell, if you type the TAB key, the completion displays the commands of the current subshell: 

karaf@root()> shell:completion SUBSHELL
karaf@root()> <TAB>
karaf@root()>
* bundle cl config dev feature help instance jaas kar la ld lde log log:list man package region service shell ssh system
karaf@root()> bundle
karaf@root(bundle)> <TAB>
karaf@root(bundle)>
capabilities classes diag dynamic-import find-class headers info install list refresh requirements resolve restart services start start-level stop
uninstall update watch
karaf@root(bundle)> exit
karaf@root()> camel
karaf@root(camel)> <TAB>
karaf@root(camel)>
backlog-tracer-dump backlog-tracer-info backlog-tracer-start backlog-tracer-stop context-info context-list context-start context-stop endpoint-list route-info route-list route-profile route-reset-stats
route-resume route-show route-start route-stop route-suspend

31.2.3. Unix like environment
Copy link

Karaf console provides a full Unix like environment.

31.2.3.1. Help or man
Copy link

We already saw the usage of the help command to display all commands available.

But you can also use the help command to get details about a command or the man command which is an alias to the help command. You can also use another form to get the command help, by using the --help option to the command.

So these commands 

karaf@root()> help feature:list
karaf@root()> man feature:list
karaf@root()> feature:list --help

All produce the same help output: 

DESCRIPTION
        feature:list

        Lists all existing features available from the defined repositories.

SYNTAX
        feature:list [options]

OPTIONS
        --help
                Display this help message
        -o, --ordered
                Display a list using alphabetical order
        -i, --installed
                Display a list of all installed features only
        --no-format
                Disable table rendered output

31.2.3.2. Completion
Copy link

When you type the tab key, Karaf tries to complete:

  • subshell
  • commands
  • aliases
  • command arguments
  • command options

31.2.3.3. Alias
Copy link

An alias is another name associated to a given command.

The shell:alias command creates a new alias. For instance, to create the list-installed-features alias to the actual feature:list -i command, you can do: 

karaf@root()> alias "list-features-installed = { feature:list -i }"
karaf@root()> list-features-installed
Name       | Version | Required | State   | Repository     | Description
------------------------------------------------------------------------------------------------------------------------------
feature    | 4.0.0   | x        | Started | standard-4.0.0 | Features Support
shell      | 4.0.0   | x        | Started | standard-4.0.0 | Karaf Shell
deployer   | 4.0.0   | x        | Started | standard-4.0.0 | Karaf Deployer
bundle     | 4.0.0   | x        | Started | standard-4.0.0 | Provide Bundle support
config     | 4.0.0   | x        | Started | standard-4.0.0 | Provide OSGi ConfigAdmin support
diagnostic | 4.0.0   | x        | Started | standard-4.0.0 | Provide Diagnostic support
instance   | 4.0.0   | x        | Started | standard-4.0.0 | Provide Instance support
jaas       | 4.0.0   | x        | Started | standard-4.0.0 | Provide JAAS support
log        | 4.0.0   | x        | Started | standard-4.0.0 | Provide Log support
package    | 4.0.0   | x        | Started | standard-4.0.0 | Package commands and mbeans
service    | 4.0.0   | x        | Started | standard-4.0.0 | Provide Service support
system     | 4.0.0   | x        | Started | standard-4.0.0 | Provide System support
kar        | 4.0.0   | x        | Started | standard-4.0.0 | Provide KAR (KARaf archive) support
ssh        | 4.0.0   | x        | Started | standard-4.0.0 | Provide a SSHd server on Karaf
management | 4.0.0   | x        | Started | standard-4.0.0 | Provide a JMX MBeanServer and a set of MBeans in

At login, the Apache Karaf console reads the etc/shell.init.script file where you can create your aliases. It’s similar to a bashrc or profile file on Unix. 

ld = { log:display $args } ;
lde = { log:exception-display $args } ;
la = { bundle:list -t 0 $args } ;
ls = { service:list $args } ;
cl = { config:list "(service.pid=$args)" } ;
halt = { system:shutdown -h -f $args } ;
help = { *:help $args | more } ;
man = { help $args } ;
log:list = { log:get ALL } ;

You can see here the aliases available by default:

  • ld is a short form to display log (alias to log:display command)
  • lde is a short form to display exceptions (alias to log:exception-display command)
  • la is a short form to list all bundles (alias to bundle:list -t 0 command)
  • ls is a short form to list all services (alias to service:list command)
  • cl is a short form to list all configurations (alias to config:list command)
  • halt is a short form to shutdown Apache Karaf (alias to system:shutdown -h -f command)
  • help is a short form to display help (alias to *:help command)
  • man is the same as help (alias to help command)
  • log:list displays all loggers and level (alias to log:get ALL command)

You can create your own aliases in the etc/shell.init.script file.

31.2.3.4. Key binding
Copy link

Like on most Unix environment, Karaf console support some key bindings:

  • the arrows key to navigate in the commands history
  • CTRL-D to logout/shutdown Karaf
  • CTRL-R to search previously executed command
  • CTRL-U to remove the current line

31.2.3.5. Pipe
Copy link

You can pipe the output of one command as input to another one. It’s a pipe, using the | character: 

karaf@root()> feature:list |grep -i war
pax-war                       | 4.1.4                            |          | Uninstalled | org.ops4j.pax.web-4.1.4  | Provide support of a full WebContainer
pax-war-tomcat                | 4.1.4                            |          | Uninstalled | org.ops4j.pax.web-4.1.4  |
war                           | 4.0.0                            |          | Uninstalled | standard-4.0.0           | Turn Karaf as a full WebContainer
blueprint-web                 | 4.0.0                            |          | Uninstalled | standard-4.0.0           | Provides an OSGI-aware Servlet ContextListener fo

31.2.3.6. Grep, more, find, …​
Copy link

Karaf console provides some core commands similar to Unix environment:

  • shell:alias creates an alias to an existing command
  • shell:cat displays the content of a file or URL
  • shell:clear clears the current console display
  • shell:completion displays or change the current completion mode
  • shell:date displays the current date (optionally using a format)
  • shell:each executes a closure on a list of arguments
  • shell:echo echoes and prints arguments to stdout
  • shell:edit calls a text editor on the current file or URL
  • shell:env displays or sets the value of a shell session variable
  • shell:exec executes a system command
  • shell:grep prints lines matching the given pattern
  • shell:head displays the first line of the input
  • shell:history prints the commands history
  • shell:if allows you to use conditions (if, then, else blocks) in script
  • shell:info prints various information about the current Karaf instance
  • shell:java executes a Java application
  • shell:less file pager
  • shell:logout disconnects shell from current session
  • shell:more is a file pager
  • shell:new creates a new Java object
  • shell:printf formats and prints arguments
  • shell:sleep sleeps for a bit then wakes up
  • shell:sort writes sorted concatenation of all files to stdout
  • shell:source executes commands contained in a script
  • shell:stack-traces-print prints the full stack trace in the console when the execution of a command throws an exception
  • shell:tac captures the STDIN and returns it as a string
  • shell:tail displays the last lines of the input
  • shell:threads prints the current thread
  • shell:watch periodically executes a command and refresh the output
  • shell:wc prints newline, words, and byte counts for each file
  • shell:while loop while the condition is true

You don’t have to use the fully qualified name of the command, you can directly use the command name as long as it is unique. So you can use 'head' instead of 'shell:head'

Again, you can find details and all options of these commands using help command or --help option.

31.2.3.7. Scripting
Copy link

The Apache Karaf Console supports a complete scripting language, similar to bash or csh on Unix.

The each (shell:each) command can iterate in a list: 

karaf@root()> list = [1 2 3]; each ($list) { echo $it }
1
2
3
Note

The same loop could be written with the shell:while command: 

karaf@root()> a = 0 ; while { %((a+=1) <= 3) } { echo $a }
1
2
3

You can create the list yourself (as in the previous example), or some commands can return a list too.

We can note that the console created a "session" variable with the name list that you can access with $list.

The $it variable is an implicit one corresponding to the current object (here the current iterated value from the list).

When you create a list with [], Apache Karaf console creates a Java ArrayList. It means that you can use methods available in the ArrayList objects (like get or size for instance): 

karaf@root()> list = ["Hello" world]; echo ($list get 0) ($list get 1)
Hello world

We can note here that calling a method on an object is directly using (object method argument). Here ($list get 0) means $list.get(0) where $list is the ArrayList.

The class notation will display details about the object: 

karaf@root()> $list class
...
ProtectionDomain     ProtectionDomain  null
 null
 <no principals>
 java.security.Permissions@6521c24e (
 ("java.security.AllPermission" "<all permissions>" "<all actions>")
)


Signers              null
SimpleName           ArrayList
TypeParameters       [E]

You can "cast" a variable to a given type. 

karaf@root()> ("hello world" toCharArray)
[h, e, l, l, o,  , w, o, r, l, d]

If it fails, you will see the casting exception: 

karaf@root()> ("hello world" toCharArray)[0]
Error executing command: [C cannot be cast to [Ljava.lang.Object;

You can "call" a script using the shell:source command: 

karaf@root> shell:source script.txt
True!

where script.txt contains: 

foo = "foo"
if { $foo equals "foo" } {
  echo "True!"
}
Note

The spaces are important when writing script. For instance, the following script is not correct: 

if{ $foo equals "foo" } ...

and will fail with: 

karaf@root> shell:source script.txt
Error executing command: Cannot coerce echo "true!"() to any of []

because a space is missing after the if statement.

As for the aliases, you can create init scripts in the etc/shell.init.script file. You can also named you script with an alias. Actually, the aliases are just scripts.

See the Scripting section of the developers guide for details.

31.2.4. Security
Copy link

The Apache Karaf console supports a Role Based Access Control (RBAC) security mechanism. It means that depending of the user connected to the console, you can define, depending of the user’s groups and roles, the permission to execute some commands, or limit the values allowed for the arguments.

Console security is detailed in the Security section of this user guide.

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top