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] [-p password] 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 karaf-install-dir/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