Managing child instances

A child instance of Karaf is a copy that you can launch separately and deploy applications into. An instance does not contain the full copy of Karaf, but only a copy of the configuration files and data folder which contains all the runtime information, logs and temporary files.

Using the admin console commands

The admin console commands allow you to create and manage instances of Karaf on the same machine. Each new runtime is a child instance of the runtime that created it. You can easily manage the children using names instead of network addresses. For details on the admin commands, see the admin commands.

Creating child instances

You create a new runtime instance by typing admin:create in the Karaf console.

As shown in the following example, admin:create causes the runtime to create a new runtime installation in the active runtime's instances/name directory. The new instance is a new Karaf instance and is assigned an SSH port number based on an incremental count starting at 8101 and a RMI registry port number based on an incremental count starting at 1099/44444.

karaf@root> admin:create alpha 
Creating new instance on SSH port 8102 and RMI ports 1100/44445 at: /x3/karaf/test/apache-karaf-2.2.4/instances/alpha
Creating dir:  /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/bin
Creating dir:  /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/etc
Creating dir:  /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/system
Creating dir:  /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/deploy
Creating dir:  /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/data
Creating file: /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/etc/config.properties
Creating file: /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/etc/jre.properties
Creating file: /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/etc/custom.properties
Creating file: /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/etc/java.util.logging.properties
Creating file: /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/etc/org.apache.felix.fileinstall-deploy.cfg
Creating file: /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/etc/org.apache.karaf.log.cfg
Creating file: /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/etc/org.apache.karaf.features.cfg
Creating file: /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/etc/org.ops4j.pax.logging.cfg
Creating file: /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/etc/org.ops4j.pax.url.mvn.cfg
Creating file: /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/etc/startup.properties
Creating file: /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/etc/users.properties
Creating file: /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/etc/system.properties
Creating file: /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/etc/org.apache.karaf.shell.cfg
Creating file: /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/etc/org.apache.karaf.management.cfg
Creating file: /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/bin/karaf
Creating file: /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/bin/start
Creating file: /x3/karaf/test/apache-karaf-2.2.4/instances/alpha/bin/stop
karaf@root>

Changing a child's ports

You can change the SSH port number assigned to a child instance using the admin:change-ssh-port command. The syntax for the command is:

admin:change-ssh-port instance port

Note that the child instance has to be stopped in order to run this command.

In the same way, you can change the RMI registry port number assigned to a child instance using the admin:change-rmi-registry-port command. The syntax for the command is:

admin:change-rmi-registry-port instance port

Note that the child instance has to be stopped in order to run this command.

Starting child instances

New instances are created in a stopped state. To start a child instance and make it ready to host applications, use the admin:start command. This command takes a single argument instance-name that identifies the child you want started.

Listing all container instances

To see a list of all Karaf instances running under a particular installation, use the admin:list command.

karaf@root>admin:list
  SSH Port   RMI Port   State       Pid  Name
[    8107] [      1106] [Started ] [10628] harry
[    8101] [      1099] [Started ] [20076] root
[    8106] [      1105] [Stopped ] [15924] dick
[    8105] [      1104] [Started ] [18224] tom
karaf@root>

Connecting to a child instance

You can connect to a started child instance's remote console using the admin:connect command which takes three arguments:

admin:connect [-u username] instance [command]

NB: the password will be prompted.

NB: you can directly execute shell command on the target instance.

Once you are connected to the child instance, the Karaf prompt changes to display the name of the current instance, as shown:

karaf@harry>

Stopping a child instance

To stop a child instance from within the instance itself, type osgi:shutdown or simply shutdown.

To stop a child instance remotely, in other words, from a parent or sibling instance, use the admin:stop:

admin:stop instance

Destroying a child instance

You can permanently delete a stopped child instance using the admin:destroy command:

admin:destroy instance

Note that only stopped instances can be destroyed.

Using the admin script

You can also manage the local instances of Karaf. The admin script in the bin directory provides the same commands as the admin console commands, apart from admin:connect.

bin/admin
Available commands:
  change-ssh-port - Changes the secure shell port of an existing container instance.
  change-rmi-registry-port - Changes the RMI registry port (used by management layer) of an existing container instance.
  create - Creates a new container instance.
  destroy - Destroys an existing container instance.
  list - List all existing container instances.
  start - Starts an existing container instance.
  stop - Stops an existing container instance.
Type 'command --help' for more help on the specified command.

For example, to list all the instances of Karaf on the local machine, type:

bin/admin list