karaf-2.2.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|/commands/admin].
 
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] [-p password] instance 
{code}

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 {{[karaf-install-dir]/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}