You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@karaf.apache.org by jb...@apache.org on 2013/11/08 07:32:34 UTC
svn commit: r1539929 -
/karaf/trunk/manual/src/main/webapp/users-guide/child-instances.conf
Author: jbonofre
Date: Fri Nov 8 06:32:34 2013
New Revision: 1539929
URL: http://svn.apache.org/r1539929
Log:
Improve documentation (updated for Karaf 3.0.0)
Modified:
karaf/trunk/manual/src/main/webapp/users-guide/child-instances.conf
Modified: karaf/trunk/manual/src/main/webapp/users-guide/child-instances.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/child-instances.conf?rev=1539929&r1=1539928&r2=1539929&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/child-instances.conf (original)
+++ karaf/trunk/manual/src/main/webapp/users-guide/child-instances.conf Fri Nov 8 06:32:34 2013
@@ -1,10 +1,14 @@
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.
+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 instance console commands
-The *instance* 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 *instance* commands, see the [{{instance}} commands|/commands/admin].
+The *instance* 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 *instance* commands, see the [{{instance}} commands|/commands/instance].
h2. Creating child instances
@@ -13,42 +17,73 @@ You create a new runtime instance by typ
As shown in the following example, {{instance: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.
{code}
-karaf@root> instance:create finn
-Creating new instance on SSH port 8106 and RMI port 1100 at: /home/user/instances/test
-Creating dir: /home/user/instances/test/bin
-Creating dir: /home/user/instances/test/etc
-Creating dir: /home/user/instances/test/system
-Creating dir: /home/user/instances/test/deploy
-Creating dir: /home/user/instances/test/data
-Creating file: /home/user/instances/test/etc/config.properties
-Creating file: /home/user/instances/test/etc/java.util.logging.properties
-Creating file: /home/user/instances/test/etc/org.apache.felix.fileinstall-deploy.cfg
-Creating file: /home/user/instances/test/etc/org.apache.karaf.log.cfg
-Creating file: /home/user/instances/test/etc/org.apache.karaf.features.cfg
-Creating file: /home/user/instances/test/etc/org.ops4j.pax.logging.cfg
-Creating file: /home/user/instances/test/etc/org.ops4j.pax.url.mvn.cfg
-Creating file: /home/user/instances/test/etc/startup.properties
-Creating file: /home/user/instances/test/etc/system.properties
-Creating file: /home/user/instances/test/etc/org.apache.karaf.shell.cfg
-Creating file: /home/user/instances/test/etc/org.apache.karaf.management.cfg
-Creating file: /home/user/instances/test/bin/karaf
-Creating file: /home/user/instances/test/bin/start
-Creating file: /home/user/instances/test/bin/stop
-karaf@root>
+karaf@root()> instance:create test
+{code}
+
+The new instance is fresh Karaf instance. It uses default configuration files set, as you install a fresh Karaf distribution.
+
+You can enable the verbose mode for the {{instance:create}} command using the {{-v}} option:
+
+{code}
+karaf@root()> instance:create -v test
+Creating new instance on SSH port 8103 and registry port 1101 / RMI server port 44446 at: /opt/karaf/instances/test
+Creating dir: /opt/karaf/instances/test/bin
+Creating dir: /opt/karaf/instances/test/etc
+Creating dir: /opt/karaf/instances/test/system
+Creating dir: /opt/karaf/instances/test/deploy
+Creating dir: /opt/karaf/instances/test/data
+Creating file: /opt/karaf/instances/test/etc/config.properties
+Creating file: /opt/karaf/instances/test/etc/jre.properties
+Creating file: /opt/karaf/instances/test/etc/custom.properties
+Creating file: /opt/karaf/instances/test/etc/java.util.logging.properties
+Creating file: /opt/karaf/instances/test/etc/org.apache.felix.fileinstall-deploy.cfg
+Creating file: /opt/karaf/instances/test/etc/org.apache.karaf.features.obr.cfg
+Creating file: /opt/karaf/instances/test/etc/org.apache.karaf.features.repos.cfg
+Creating file: /opt/karaf/instances/test/etc/org.apache.karaf.log.cfg
+Creating file: /opt/karaf/instances/test/etc/org.ops4j.pax.logging.cfg
+Creating file: /opt/karaf/instances/test/etc/org.ops4j.pax.url.mvn.cfg
+Creating file: /opt/karaf/instances/test/etc/users.properties
+Creating file: /opt/karaf/instances/test/etc/keys.properties
+Creating file: /opt/karaf/instances/test/etc/org.apache.karaf.features.cfg
+Creating file: /opt/karaf/instances/test/etc/system.properties
+Creating file: /opt/karaf/instances/test/etc/org.apache.karaf.shell.cfg
+Creating file: /opt/karaf/instances/test/etc/org.apache.karaf.management.cfg
+Creating file: /opt/karaf/instances/test/bin/karaf
+Creating file: /opt/karaf/instances/test/bin/start
+Creating file: /opt/karaf/instances/test/bin/stop
+{code}
+
+You can manually configure the different ports, the location of the instance, the Karaf features URLs using different options of the {{instance:create}} command.
+You can have details about these options using the {{--help}} option.
+
+h2. Cloning an instance
+
+Instead of creating a fresh instance, you can clone an existing instance using [{{instance:clone}}|/commands/instance-clone].
+
+The {{instance:clone}} command reuse the files from the source instance:
+
+{code}
+karaf@root()> instance:clone root test
{code}
+h2. Changing the instance location
+
h2. Changing a child's ports
You can change the SSH port number assigned to a child instance using the [{{instance:change-ssh-port}}|/commands/instance-change-port] command. The syntax for the command is:
+
{code}
-instance:change-ssh-port instance port
+karaf@root()> instance: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 [{{instance:change-rmi-registry-port}}|/commands/instance-change-rmi-registry-port] command. The syntax for the command is:
+
{code}
-instance:change-rmi-registry-port instance port
+karaf@root()> instance: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
@@ -60,13 +95,8 @@ h2. Listing all container instances
To see a list of all Karaf instances running under a particular installation, use the [{{instance:list}}|/commands/instance-list] command.
{code}
-karaf@root> instance: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>
+karaf@root()> instance:list
+
{code}
h2. Connecting to a child instance
@@ -74,7 +104,7 @@ h2. Connecting to a child instance
You can connect to a started child instance's remote console using the [{{instance:connect}}|/commands/instance-connect] command which takes three arguments:
{code}
-admin:connect [-u username] instance [command]
+karaf@root()> instance:connect [-u username] instance [command]
{code}
NB: the password will be prompted.
@@ -84,16 +114,19 @@ NB: you can directly execute shell comma
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>
+karaf@test()>
{code}
+You can go back to the root instance using CTRL-D or logout command.
+
h2. Stopping a child instance
To stop a child instance from within the instance itself, type {{system:shutdown}}.
To stop a child instance remotely, in other words, from a parent or sibling instance, use the [{{instance:stop}}|/commands/instance-stop]:
+
{code}
-karaf@root> instance:stop instance
+karaf@root()> instance:stop test
{code}
h2. Destroying a child instance
@@ -101,8 +134,9 @@ h2. Destroying a child instance
You can permanently delete a stopped child instance using the [{{instance:destroy}}|/commands/instance-destroy] command:
{code}
-karaf@root> instance:destroy instance
+karaf@root()> instance:destroy test
{code}
+
Note that only stopped instances can be destroyed.
h2. Renaming a child instance
@@ -110,20 +144,10 @@ h2. Renaming a child instance
You can easily change the name of an existing instance using the [{{instance:rename}}|/commands/instance-rename] command:
{code}
-karaf@root> instance:rename instance newName
+karaf@root()> instance:rename test newTest
{code}
-Note that only stopped instances can be renamed.
-h2. Cloning a child instance
-
-You can easily clone (copy) an existing instance using the [{{instance:clone}}|/commands/instance-clone] command:
-
-{code}
-karaf@root> instance:clone instance cloneName
-{code}
-Note that only stopped instances can be cloned.
-
-All instance files will be copied and the name and port numbers are changed in the cloned instance.
+Note that only stopped instances can be renamed.
h2. Using the instance script
@@ -136,11 +160,12 @@ bin/instance
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
+bin/instance
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.
+ clone - Clones a new container instance.
destroy - Destroys an existing container instance.
list - List all existing container instances.
start - Starts an existing container instance.