manual/src/main/asciidoc/user-guide/start-stop.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.
//

=== Start, stop, restart, connect

==== Start

Apache Karaf supports different start modes:

* the "regular" mode starts Apache Karaf in the foreground, including the shell console.
* the "server" mode starts Apache Karaf in the foreground, without the shell console.
* the "background" mode starts Apache Karaf in the background.

You can also manage Apache Karaf as a system service (see link:wrapper[System Service] section).

===== Regular mode

The regular mode uses the `bin/karaf` Unix script (`bin\karaf.bat` on Windows). It's the default start process.

It starts Apache Karaf as a foreground process, and displays the shell console.

On Unix:

----
bin/karaf
        __ __                  ____
       / //_/____ __________ _/ __/
      / ,<  / __ `/ ___/ __ `/ /_
     / /| |/ /_/ / /  / /_/ / __/
    /_/ |_|\__,_/_/   \__,_/_/

  Apache Karaf (4.0.0)

Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit '<ctrl-d>' or type 'system:shutdown' or 'logout' to shutdown Karaf.

karaf@root()>
----

On Windows:

----
bin\karaf.bat
        __ __                  ____
       / //_/____ __________ _/ __/
      / ,<  / __ `/ ___/ __ `/ /_
     / /| |/ /_/ / /  / /_/ / __/
    /_/ |_|\__,_/_/   \__,_/_/

  Apache Karaf (4.0.0)

Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit '<ctrl-d>' or type 'system:shutdown' or 'logout' to shutdown Karaf.

karaf@root()>
----

[NOTE]
====
Closing the console or shell window will cause Apache Karaf to terminate.
====

===== Server mode

The server mode starts Apache Karaf as a foreground process, but it doesn't start the shell console.

To use this mode, you use the `server` argument to the `bin/karaf` Unix script (`bin\karaf.bat` on Windows).

On Unix:

----
bin/karaf server

----

On Windows:

----
bin\karaf.bat server

----

[NOTE]
====
Closing the console or shell window will cause Apache Karaf to terminate.
====

You can connect to the shell console using SSH or client (see the Connect section in this page).

===== Background mode

The background mode starts Apache Karaf as a background process.

To start in background mode, you have to use `bin/start` Unix script (`bin\start.bat` on Windows).

On Unix:

----
bin/start
----

On Windows:

----
bin\start.bat
----

You can connect to the shell console using SSH or client (see the Connect section in this page).

===== Clean start

Apache Karaf stores all previously applications installed and changes that you did in the data folder.

If you want to start from a clean state, you can remove the data folder.

For convenience, you can use the `clean` argument to the `bin/karaf` Unix script (`bin\karaf.bat` on Windows).

On Unix:

----
bin/karaf clean
----

----
bin/start clean
----

On Windows:

----
bin\karaf.bat clean
----

----
bin\start.bat clean
----

===== Customize variables

Apache Karaf accepts environment variables:

* `JAVA_MIN_MEM`: minimum memory for the JVM (default is 128M).
* `JAVA_MAX_MEM`: maximum memory for the JVM (default is 512M).
* `JAVA_PERM_MEM`: minimum perm memory for the JVM (default is JVM default value).
* `JAVA_MAX_PERM_MEM`: maximum perm memory for the JVM (default is JVM default value).
* `KARAF_HOME`: the location of your Apache Karaf installation (default is found depending on where you launch the startup script).
* `KARAF_BASE`: the location of your Apache Karaf base (default is `KARAF_HOME`).
* `KARAF_DATA`: the location of your Apache Karaf data folder (default is `KARAF_BASE/data`).
* `KARAF_ETC`: the location of your Apache Karaf etc folder (default is `KARAF_BASE/etc`).
* `KARAF_OPTS`: extra arguments passed to the Java command line (default is null).
* `KARAF_DEBUG`: if 'true', enable the debug mode (default is null). If debug mode is enabled, Karaf starts a JDWP socket on port 5005. You can plug your IDE to define breakpoints, and run step by step.

You can define these environment variables in `bin/setenv` Unix script (`bin\setenv.bat` on Windows).

For instance, to set the minimum and maximum memory size for the JVM, you can define the following values:

On Unix:

----
# Content of bin/setenv
export JAVA_MIN_MEM=256M
export JAVA_MAX_MEM=1024M
----

On Windows:

----
rem Content of bin\setenv.bat
set JAVA_MIN_MEM=256M
set JAVA_MAX_MEM=1024M
----

===== Connect

Even if you start Apache Karaf without the console (using server or background modes), you can connect to the console.
This connection can be local or remote. It means that you can access to Karaf console remotely.

To connect to the console, you can use the `bin/client` Unix script (`bin\client.bat` on Windows).

On Unix:

----
bin/client
Logging in as karaf
360 [pool-2-thread-3] WARN org.apache.sshd.client.keyverifier.AcceptAllServerKeyVerifier - Server at /0.0.0.0:8101 presented unverified key:
        __ __                  ____
       / //_/____ __________ _/ __/
      / ,<  / __ `/ ___/ __ `/ /_
     / /| |/ /_/ / /  / /_/ / __/
    /_/ |_|\__,_/_/   \__,_/_/

  Apache Karaf (4.0.0)

Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit 'system:shutdown' to shutdown Karaf.
Hit '<ctrl-d>' or type 'logout' to disconnect shell from current session.

karaf@root()>
----

On Windows:

----
bin\client.bat
Logging in as karaf
360 [pool-2-thread-3] WARN org.apache.sshd.client.keyverifier.AcceptAllServerKeyVerifier - Server at /0.0.0.0:8101 presented unverified key:
        __ __                  ____
       / //_/____ __________ _/ __/
      / ,<  / __ `/ ___/ __ `/ /_
     / /| |/ /_/ / /  / /_/ / __/
    /_/ |_|\__,_/_/   \__,_/_/

  Apache Karaf (4.0.0-SNAPSHOT)

Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit 'system:shutdown' to shutdown Karaf.
Hit '<ctrl-d>' or type 'logout' to disconnect shell from current session.

karaf@root()>
----

By default, `client` tries to connect on localhost, on port 8101 (the default Apache Karaf SSH port).

`client` accepts different options to let you connect on a remote Apache Karaf instance. You can use `--help` to get details about the options:

On Unix:

----
bin/client --help
Apache Karaf client
  -a [port]     specify the port to connect to
  -h [host]     specify the host to connect to
  -u [user]     specify the user name
  --help        shows this help message
  -v            raise verbosity
  -r [attempts] retry connection establishment (up to attempts times)
  -d [delay]    intra-retry delay (defaults to 2 seconds)
  -b            batch mode, specify multiple commands via standard input
  -f [file]     read commands from the specified file
  [commands]    commands to run
If no commands are specified, the client will be put in an interactive mode
----

On Windows:

----
bin\client.bat --help
Apache Karaf client
  -a [port]     specify the port to connect to
  -h [host]     specify the host to connect to
  -u [user]     specify the user name
  --help        shows this help message
  -v            raise verbosity
  -r [attempts] retry connection establishment (up to attempts times)
  -d [delay]    intra-retry delay (defaults to 2 seconds)
  -b            batch mode, specify multiple commands via standard input
  -f [file]     read commands from the specified file
  [commands]    commands to run
If no commands are specified, the client will be put in an interactive mode
----

Actually, `client` is a SSH client. You can use any SSH client to connect, like OpenSSH (ssh command) on Unix, or Putty on Windows.

For instance, on Unix, you can do:

----
ssh karaf@localhost -p 8101
Authenticated with partial success.
Authenticated with partial success.
Authenticated with partial success.
Password authentication
Password:
        __ __                  ____
       / //_/____ __________ _/ __/
      / ,<  / __ `/ ___/ __ `/ /_
     / /| |/ /_/ / /  / /_/ / __/
    /_/ |_|\__,_/_/   \__,_/_/

  Apache Karaf (4.0.0-SNAPSHOT)

Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit 'system:shutdown' to shutdown Karaf.
Hit '<ctrl-d>' or type 'logout' to disconnect shell from current session.

karaf@root()>
----

==== Stop

When you start Apache Karaf in regular mode, the `logout` command or CTRL-D key binding logs out from the console and shuts Apache Karaf down.

When you start Apache Karaf in background mode (with the `bin/start` Unix script (`bin\start.bat` on Windows)), you can use the `bin/stop` Unix script (`bin\stop.bat` on Windows).

More generally, you can use the `shutdown` command (on the Apache Karaf console) that works for all cases.

The `shutdown` command is very similar to the the `shutdown` Unix command.

To shutdown Apache Karaf now, you can simply use `shutdown`:

----
karaf@root()> shutdown -h
Confirm: halt instance root (yes/no):
----

The `shutdown` command asks for a confirmation. If you want to bypass the confirmation step, you can use the `-f` (`--force`) option:

----
karaf@root()> shutdown -f
----

You can also use directly `halt` which is an alias to `shutdown -f -h`.

The `shutdown` command accepts a time argument. With this argument, you can define when you want to shutdown the Apache Karaf container.

The time argument can have different formats. First, it can be an absolute time in the format hh:mm, in which hh is the hour (1 or 2 digits) and mm is the minute of the hour
(in two digits). Second, it can be in the format m (or +m), in which m is the number of minutes to wait. The word `now` is an alias for 0.

For instance, the following command will shutdown Apache Karaf at 10:35am:

----
karaf@root()> system:shutdown 10:35
----

Another example to shutdown Apache Karaf in 10 minutes:

----
karaf@root()> system:shutdown 10
----

Like for other commands, you can find details on the `shutdown` command man page:

----
karaf@root()> shutdown --help
DESCRIPTION
        system:shutdown

        Shutdown Karaf.

SYNTAX
        system:shutdown [options] [time]

ARGUMENTS
        time
                Shutdown after a specified delay. The time argument can have different formats. First, it can be an abolute time in the format hh:mm, in which hh is the hour (1 or 2 digits) and mm is the minute of the hour (in two digits). Second, it can be in the format +m, in which m is the number of minutes to
                wait. The word now is an alias for +0.

OPTIONS
        -c, --clean, --clean-all, -ca
                Force a clean restart by deleting the data directory
        -f, --force
                Force the shutdown without confirmation message.
        -h, --halt
                Halt the Karaf container.
        --help
                Display this help message
        -cc, --clean-cache, -cc
                Force a clean restart by deleting the cache directory
        -r, --reboot
                Reboot the Karaf container.
----

==== Status

When you start Apache Karaf in background mode, you may want to check the current status.

To do so, you can use the `bin/status` Unix script (`bin\status.bat` on Windows).

[NOTE]
====
The status script returns 0 exit code if Apache Karaf is running, 1 exit code else.
====

On Unix:

----
bin/status
Not Running ...
----

----
bin/status
Running ...
----

On Windows:

----
bin\status.bat
Not Running ...
----

----
bin\status.bat
Running ...
----

==== Restart

The `shutdown` command accepts the `-r` (`--restart`) option to restart Apache Karaf:

----
karaf@root()> system:shutdown -r
----

[NOTE]
====
This command does not start a new JVM. It simply restarts the OSGi framework.
====

==== SystemMBean

Apache Karaf provides the JMX SystemMBean dedicated to control of the container itself.

The SystemMBean object name is `org.apache.karaf:type=system`.

The SystemMBean provides different attributes and operations, especially operations to halt or reboot the container:

* `reboot()` reboots Apache Karaf now (without cleaning the cache)
* `reboot(time)` reboots Apache Karaf at a given time (without cleaning the cache). The time format is the same as the time argument of the `shutdown` command.
* `rebootCleanCache(time)` reboots Apache Karaf at a given time, including the cleanup of the cache.
* `rebootCleanAll(time)` reboots Apache Karaf at a given time, including the cleanup of the whole data folder.
* `halt()` shutdown Apache Karaf now.
* `halt(time)` shutdown Apache Karaf at a given time. The time format is the same as the time argument of the `shutdown` command.