manual/src/main/asciidoc/user-guide/instances.adoc

//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

=== Instances

A instance is a complete new Apache Karaf runtime, isolated from the other ones.

The purpose is to easily create and manage a new Apache Karaf runtime without installing a complete distribution.

A instance is a new instance that you can launch separately from the root one, and deploy applications into. It means that each instance is run on a different JVM.

A instance does not contain a full copy of the Apache Karaf distribution, but only a set of the configuration files and data folder which contains all the runtime information, logs and temporary files.

==== Using the instance commands

The *instance* commands allow you to create and manage instances.

===== Creating instances

You create a new runtime instance by typing [`instance:create`|/commands/instance-create] in the Karaf console.

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.

----
karaf@root()> instance:create test
----

The new instance is a fresh Apache Karaf instance. It uses the same default configuration files, as when you install a fresh Karaf distribution.

You can enable the verbose mode for the `instance:create` command using the `-v` option:

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

You can manually configure the different ports, the location of the instance, the Apache Karaf features URLs using different options of the `instance:create` command.
You can have details about these options using the `--help` option.

===== Cloning an instance

Instead of creating a fresh instance, you can clone an existing instance using `instance:clone`.

The `instance:clone` command reuse the files from the source instance:

----
karaf@root()> instance:clone root test
----

You can have details about the cloning options using the `--help` option.

===== Changing the instance location

By default, the new instances storage is in the `KARAF_HOME/instance` directory.
You find a directory with the name of the instance storing the different instance files.

You can change the location of the instance using the `-l` option to the `instance:create` and `instance:clone` commands:

----
karaf@root()> instance:create -v -l /tmp/test test
Creating new instance on SSH port 8102 and registry port 1100 / RMI server port 44445 at: /tmp/test
Creating dir: /tmp/test/bin
Creating dir: /tmp/test/etc
Creating dir: /tmp/test/system
Creating dir: /tmp/test/deploy
Creating dir: /tmp/test/data
Creating file: /tmp/test/etc/config.properties
Creating file: /tmp/test/etc/jre.properties
Creating file: /tmp/test/etc/custom.properties
Creating file: /tmp/test/etc/java.util.logging.properties
Creating file: /tmp/test/etc/org.apache.felix.fileinstall-deploy.cfg
Creating file: /tmp/test/etc/org.apache.karaf.features.obr.cfg
Creating file: /tmp/test/etc/org.apache.karaf.features.repos.cfg
Creating file: /tmp/test/etc/org.apache.karaf.log.cfg
Creating file: /tmp/test/etc/org.ops4j.pax.logging.cfg
Creating file: /tmp/test/etc/org.ops4j.pax.url.mvn.cfg
Creating file: /tmp/test/etc/users.properties
Creating file: /tmp/test/etc/keys.properties
Creating file: /tmp/test/etc/org.apache.karaf.features.cfg
Creating file: /tmp/test/etc/system.properties
Creating file: /tmp/test/etc/org.apache.karaf.shell.cfg
Creating file: /tmp/test/etc/org.apache.karaf.management.cfg
Creating file: /tmp/test/bin/karaf
Creating file: /tmp/test/bin/start
Creating file: /tmp/test/bin/stop
----

Careful, it's not possible to change the location of an instance once it has been created.

[NOTE]
====
`instance:destroy` will remove the instance location for you. You don't have to remove the instance location "by hand".
====

===== Changing instance ports

You can change the SSH port number assigned to an instance using the `instance:ssh-port-change` command:

----
karaf@root()> instance:ssh-port-change test 8104
----

where test is the instance name and 8104 is the new SSH port number to use for the test instance.

You can change the RMI Registry port number (used by JMX) of an instance using the `instance:rmi-registry-port-change` command:

----
karaf@root()> instance:rmi-registry-port-change test 1102
----

where test is the instance name and 1102 is the new RMI Registry port number to use for the test instance.

You can also change the RMI Server port number (used by JMX too) of an instance using the `instance:rmi-server-port-change` command:

----
karaf@root()> instance:rmi-server-port-change test 44447
----

where test is the instance name and 44447 is the new RMI Server port number to use for the test instance.

[NOTE]
====
The instance has to be stopped to be able to change the port numbers.
====

===== Starting instances

New instances are created in a stopped state.

To start an instance, you can use the `instance:start` command:

----
karaf@root()> instance:start test
----

where test is the instance name.

===== Listing instances

To list the instances and their current status, you can use the `instance:list` command:

----
karaf@root()> instance:list
SSH Port | RMI Registry | RMI Server | State   | PID   | Name
-------------------------------------------------------------
    8101 |         1099 |      44444 | Started | 19652 | root
    8104 |         1101 |      44446 | Stopped | 0     | test
----

An instance can be in the following status:

- Stopped: the instance is stopped.
- Starting: the instance is starting.
- Started: the instance is up and running. You can connect and use it.

===== Status of an instance

You can get directly the status of a given instance using the `instance:status` command:

----
karaf@root()> instance:status test
Started
----

where test is the instance name.

===== Connecting to an instance

You can connect to a running instance directly from the root one using the `instance:connect` command:

----
karaf@root()> instance:connect test
----

where 'test' is the instance name where to connect to.

By default, this command will use the same username used on the root instance, and the password will be prompted.

You can use a different username using the `-u` or `--username` option. You can also provide the password using the
`-p` or `--password` option.

If you don't provide any argument, you will logon on the instance:

----
karaf@test()>
----

Note the name of instance in the shell prompt (@test).

You can logoff from the instance and return back to the root instance using the `logout` command or CTRL-D key binding:

----
karaf@test()> logout
karaf@root()>
----

The `instance:connect` command accepts shell commands as argument. It allows you to directly execute commands or scripts on the instance:

----
karaf@root()> instance:connect test feature:list
Name                          | Version         | Installed | Repository                | Description
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
standard                      | 4.0.0           | x         | standard-4.0.0            | Karaf standard feature
aries-annotation              | 4.0.0           |           | standard-4.0.0            | Aries Annotations
wrapper                       | 4.0.0           |           | standard-4.0.0            | Provide OS integration
service-wrapper               | 4.0.0           |           | standard-4.0.0            | Provide OS integration (alias to wrapper feature)
obr                           | 4.0.0           |           | standard-4.0.0            | Provide OSGi Bundle Repository (OBR) support
config                        | 4.0.0           | x         | standard-4.0.0            | Provide OSGi ConfigAdmin support
region                        | 4.0.0           | x         | standard-4.0.0            | Provide Region Support
...
----

===== Stop an instance

To stop an instance, you can connect to the instance (using `instance:connect`) and execute the `system:shutdown`
command.

You can also use the `instance:stop` command:

----
karaf@root()> instance:stop test
----

where test is the instance name.

The instance will go to the "Stopped" state.

===== Destroy an instance

You can completely delete a stopped instance using the `instance:destroy` command:

----
karaf@root()> instance:destroy test
----

where test is the instance name.

[NOTE]
====
The `instance:destroy` deletes the instance store (the location where the instance files are stored).
====

===== Rename an instance

You can change the name of a stopped instance using the `instance:rename` command:

----
karaf@root()> instance:rename test newTest
----

where test is the current instance name, and newTest the new instance name.

==== Instance script

The `instance:*` commands require the root instance running.

But, you can also administrate directly instances without the root instance, using the `bin/instance` Unix script
(or `bin/instance.bat` script on Windows).

You find the same actions that you can do with the `instance:*` commands in the `instance[.bat]` script:

----
bin/instance
Available commands:
  clone - Clones an existing container instance.
  create - Creates a new container instance.
  destroy - Destroys an existing container instance.
  list - Lists all existing container instances.
  opts-change - Changes the Java options of an existing container instance.
  rename - Rename an existing container instance.
  rmi-registry-port-change - Changes the RMI registry port (used by management layer) of an existing container instance.
  rmi-server-port-change - Changes the RMI server port (used by management layer) of an existing instance.
  ssh-port-change - Changes the secure shell port of an existing container instance.
  start - Start an existing container instance.
  status - Check the current status of an instance.
  stop - Stop an existing container instance.
Type 'command --help' for more help on the specified command.
----

For instance, to list all the instances, you can use the `instance` script with the `list` command:

----
bin/instance list
SSH Port | RMI Registry | RMI Server | State   | PID | Name
-----------------------------------------------------------
    8101 |         1099 |      44444 | Stopped | 0   | root
    8102 |         1100 |      44445 | Stopped | 0   | test
----

It's exactly the same as executing `instance:list` in the root instance.

You can obtain details about commands options and arguments using the `--help` option. For instance:

----
bin/instance rename --help
DESCRIPTION
        instance:rename

        Rename an existing container instance.

SYNTAX
        instance:rename [options] name new-name

ARGUMENTS
        name
                The name of the container instance to rename
        new-name
                The new name of the container instance

OPTIONS
        --help
                Display this help message
        -v, --verbose
                Display actions performed by the command (disabled by default)

----

==== JMX InstanceMBean

On the JMX layer, you have a MBean dedicated to the management of the instances: the InstanceMBean.

The ObjectName to use is `org.apache.karaf:type=instance,name=*`.

===== Attributes

The `Instances` attribute is a tabular data attribute providing details about the instances:

* `Is Root` (boolean): if true, the instance is the root instance, false else.
* `JavaOpts` (string): it contains the JVM arguments used by the instance.
* `Location` (string): it's the path to the instance storage.
* `Name` (string): it's the name of the instance.
* `Pid` (long): it's the current system process ID (PID) of the instance process.
* `RMI Registry Port` (int): it's the port number of the instance RMI Registry (JMX).
* `RMI Server Port` (int): it's the port number of the instance RMI Server (JMX).
* `SSH Port` (int): it's the port number of the instance SSH Server.
* `State` (string): it's the current status of the instance (Stopped, Starting, Started).

===== Operations

The InstanceMBean provides the following operations, corresponding to the previous `instance:*` commands:

* `createInstance(instanceName, sshPort, rmiRegistryPort, rmiServerPort, location, javaOpts, features, featuresUrls)`: create a new instance.
* `changeSshPort(instanceName, port)`: change the SSH port of an instance.
* `changeRmiServerPort(instanceName, port)`: change the RMI server port of an instance.
* `changeRmiRegistry(instanceName, port)`: change the RMI registry port of an instance.
* `changeJavaOpts(instanceName, javaOpts)`: change the Java options of an instance.
* `destroyInstance(instanceName)`: destroy an instance.
* `startInstance(instanceName)`: start an instance.
* `startInstance(instanceName, options)`: start an instance with the given Java options.
* `startInstance(instanceName, options, wait, debug)`: start an instance with the given Java options.
 If wait is true, this operation is waiting for the instance is in "Started" state. If debug is true, the instance is started in debug mode.
* `stopInstance(instanceName)`: stop an instance.
* `renameInstance(instanceName, newInstanceName)`: rename an instance.
* `renameInstance(instanceName, newInstanceName, verbose)`: rename an instance. If verbose is true, this operation provides details in the log.
* `cloneInstance(instanceName, cloneName, sshPort, rmiRegistryPort, rmiServerPort, location, javaOpts)`: clone an existing instance.