karaf-2.3.x/manual/src/main/webapp/users-guide/child-instances.conf

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

h2. 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/admin] commands.
 
h2. Creating child instances

You create a new runtime instance by typing [{{admin:create}}|/commands/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.

{code}
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>
{code}

h2. Changing a child's ports

You can change the SSH port number assigned to a child instance using the [{{admin:change-ssh-port}}|/commands/admin-change-port] command.  The syntax for the command is:
{code}
admin:change-ssh-port instance port
{code}
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}}|/commands/admin-change-rmi-registry-port] command. The syntax for the command is:
{code}
admin:change-rmi-registry-port instance port
{code}
Note that the child instance has to be stopped in order to run this command.

h2. 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}}|/commands/admin-start] command.  This command takes a single argument {{[instance-name]}} that identifies the child you want started.

h2. Listing all container instances

To see a list of all Karaf instances running under a particular installation, use the [{{admin:list}}|/commands/admin-list] command.

{code}
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>
{code}

h2. Connecting to a child instance

You can connect to a started child instance's remote console using the [{{admin:connect}}|/commands/admin-connect] command which takes three arguments:

{code}
admin:connect [-u username] instance [command]
{code}

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:

{code}
karaf@harry>
{code}

h2. 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}}|/commands/admin-stop]:
{code}
admin:stop instance
{code}

h2. Destroying a child instance

You can permanently delete a stopped child instance using the [{{admin:destroy}}|/commands/admin-destroy] command:
{code}
admin:destroy instance
{code}
Note that only stopped instances can be destroyed.

h2. 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}}|/commands/admin-connect].
 
{code}
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.
{code}

For example, to list all the instances of Karaf on the local machine, type:
{code}
bin/admin list
{code}