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