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/27 19:13:49 UTC
svn commit: r1546148 - in /karaf/trunk/manual/src/main/webapp:
update-notes.conf users-guide/index.conf users-guide/start-stop.conf
Author: jbonofre
Date: Wed Nov 27 18:13:48 2013
New Revision: 1546148
URL: http://svn.apache.org/r1546148
Log:
[KARAF-2511] Review of the start-stop page of the documentation
Modified:
karaf/trunk/manual/src/main/webapp/update-notes.conf
karaf/trunk/manual/src/main/webapp/users-guide/index.conf
karaf/trunk/manual/src/main/webapp/users-guide/start-stop.conf
Modified: karaf/trunk/manual/src/main/webapp/update-notes.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/update-notes.conf?rev=1546148&r1=1546147&r2=1546148&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/update-notes.conf (original)
+++ karaf/trunk/manual/src/main/webapp/update-notes.conf Wed Nov 27 18:13:48 2013
@@ -6,6 +6,8 @@ h2. Shell commands
h2. MBeans
+h2. Features
+
h2. Namespaces
h2. Classnames
Modified: karaf/trunk/manual/src/main/webapp/users-guide/index.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/index.conf?rev=1546148&r1=1546147&r2=1546148&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/index.conf (original)
+++ karaf/trunk/manual/src/main/webapp/users-guide/index.conf Wed Nov 27 18:13:48 2013
@@ -2,7 +2,7 @@ h1. Karaf Users Guide
* [Installation|installation]
* [Directory Structure|directory-structure]
-* [Starting and stopping Karaf|start-stop]
+* [Start, stop, restart, connect|start-stop]
* [Service Wrapper|wrapper]
* [Configuration|configuration]
* [Using the console|using-console]
Modified: karaf/trunk/manual/src/main/webapp/users-guide/start-stop.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/start-stop.conf?rev=1546148&r1=1546147&r2=1546148&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/start-stop.conf (original)
+++ karaf/trunk/manual/src/main/webapp/users-guide/start-stop.conf Wed Nov 27 18:13:48 2013
@@ -1,118 +1,419 @@
-h1. Starting and Stopping Karaf
+h1. Start, stop, restart, connect
-This chapter describes how to start and stop Apache Karaf from the command line as well as from the Karaf console.
+h2. Start
-h2. Starting Karaf
+Apache Karaf supports different start mode:
-h3. On Windows
+* the "regular" mode starts Apache Karaf in foreground, including the shell console.
+* the "server" mode starts Apache Karaf in foreground, without the shell console.
+* the "background" mode starts Apache Karaf in background.
+
+You can also manage Apache Karaf as a system service (see [System Service|wrapper] section of this manual).
+
+h3. 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:
-From a console window, change to the installation directory and run {{Karaf}}. For the binary distribution, go to
{code}
-cd [karaf_install_dir]
+bin/karaf
+ __ __ ____
+ / //_/____ __________ _/ __/
+ / ,< / __ `/ ___/ __ `/ /_
+ / /| |/ /_/ / / / /_/ / __/
+ /_/ |_|\__,_/_/ \__,_/_/
+
+ Apache Karaf (3.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()>
{code}
-where {{karaf_install_dir}} is the directory in which Karaf was installed, e.g., {{c:\Program Files\apache-karaf-x.y}}.
-Then type:
+On Windows:
+
{code}
bin\karaf.bat
+ __ __ ____
+ / //_/____ __________ _/ __/
+ / ,< / __ `/ ___/ __ `/ /_
+ / /| |/ /_/ / / / /_/ / __/
+ /_/ |_|\__,_/_/ \__,_/_/
+
+ Apache Karaf (3.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()>
{code}
-h3. On Unix
+{warning:title=Warning}
+Closing the console or shell window will cause Apache Karaf to terminate.
+{warning}
+
+h3. 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:
-From a command shell, change to the installation directory and run {{Karaf}}. For the binary distribution, go to
{code}
-cd [karaf_install_dir]
+bin/karaf server
+
{code}
-where {{karaf_install_dir}} is the directory in which Karaf was installed, e.g., {{/usr/local/apache-karaf-x.y}}.
-Then type:
+On Windows:
+
{code}
-bin/karaf
+bin\karaf.bat server
+
{code}
{warning:title=Warning}
-Closing the console or shell window will cause karaf to terminate.
+Closing the console or shell window will cause Apache Karaf to terminate.
{warning}
-h2. Starting Karaf without console
+You can connect to the shell console using SSH or client (see the Connect section in this page).
+
+h3. 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:
-Karaf can be started without the console if you don't intend to use it (one can always connect using the remote ssh access) using the following command:
{code}
-bin\karaf.bat server
+bin/start
{code}
-or, on Unix:
+
+On Windows:
+
{code}
-bin\karaf server
+bin\start.bat
{code}
-h2. Starting Karaf in the background
+You can connect to the shell console using SSH or client (see the Connect section in this page).
+
+h3. 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:
-Karaf can be easily started as a background process using the following command:
{code}
-bin\start.bat
+bin/karaf clean
{code}
-or, on Unix:
+
{code}
-bin\start
+bin/start clean
{code}
-h2. Starting Karaf from clean
+On Windows:
-Karaf can be reset to a clean state by simply deleting the {{data}} folder.
-For convenience, a parameter on the {{karaf}} and {{start}} scripts is available:
{code}
-bin/start clean
+bin\karaf.bat clean
+{code}
+
+{code}
+bin\start.bat clean
{code}
-In addition there might be situations where you need to restart the application from your application or dont have any
-access to the service starting and stopping karaf. In this case you can either put an empty clean_cache or clean_all file
-into the {{data}} folder. If you restart or start and stop Karaf then either the cache will be cleaned or the entire
-{{data}} folder will be deleted.
+h3. 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 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.
-h2. Restarting Karaf
+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:
-You can restart Karaf directly from the command line by using:
{code}
-system:shutdown -r
+# Content of bin/setenv
+export JAVA_MIN_MEM=256M
+exoprt JAVA_MAX_MEM=1024M
{code}
-Be careful since this does not start a new JVM but simply restarts the OSGi framework. If you want to clean your {{cache}}
-or {{data}} directory during the reboot add the -c or -cc params to your build. More detailed information about the
-restart parameters could be retrieved from the command line by using
+On Windows:
+
{code}
-system:shutdown --help
+rem Content of bin\setenv.bat
+set JAVA_MIN_MEM=256M
+set JAVA_MAX_MEM=1024M
{code}
-h2. Stopping Karaf
+h3. 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:
-For both Windows and Unix installations, you can perform a clean shutdown of Karaf by using the following command when inside a Karaf console:
{code}
-system:shutdown
+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 (3.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()>
{code}
-The shutdown command has several options you can use to change the behaviour. See [commands/shutdown].
+On Windows:
+
+{code}
+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:
+ __ __ ____
+ / //_/____ __________ _/ __/
+ / ,< / __ `/ ___/ __ `/ /_
+ / /| |/ /_/ / / / /_/ / __/
+ /_/ |_|\__,_/_/ \__,_/_/
-It's also possible to delay the shutdown using the time argument. 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, in which m is the number of minutes to wait. The work now is an alias for +0.
+ Apache Karaf (3.0.0-SNAPSHOT)
-The following command will shutdown Karaf at 10:35am:
+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()>
{code}
-system:shutdown 10:35
+
+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:
+
+{code}
+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
{code}
-The following command will shutdown Karaf in 10 minutes:
+On Windows:
{code}
-system:shutdown +10
+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
{code}
-If you're running from the main console, exiting the shell using {{logout}} or {{Ctrl+D}} will also terminate the Karaf instance.
+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:
-From a command shell, you can run the following command:
{code}
-bin\stop.bat
+ssh karaf@localhost -p 8101
+Authenticated with partial success.
+Authenticated with partial success.
+Authenticated with partial success.
+Password authentication
+Password:
+ __ __ ____
+ / //_/____ __________ _/ __/
+ / ,< / __ `/ ___/ __ `/ /_
+ / /| |/ /_/ / / / /_/ / __/
+ /_/ |_|\__,_/_/ \__,_/_/
+
+ Apache Karaf (3.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()>
+{code}
+
+h2. Stop
+
+When you start Apache Karaf in regular mode, the {{logout}} command or CTRL-D key binding logout from the console and shutdown Apache Karaf.
+
+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 work in any case.
+
+The {{shutdown}} command is very similar to the the {{shutdown}} Unix command.
+
+To shutdown Apache Karaf now, you can simple using {{shutdown}}:
+
+{code}
+karaf@root()> shutdown -h
+Confirm: halt instance root (yes/no):
+{code}
+
+The {{shutdown}} command asks for a confirmation. If you want to bypass the confirmation step, you can use the {{-f}} ({{--force}}) option:
+
+{code}
+karaf@root()> shutdown -f
+{code}
+
+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, 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:
+
+{code}
+karaf@root()> system:shutdown 10:35
+{code}
+
+Another example to shutdown Apache Karaf in 10 minutes:
+
+{code}
+karaf@root()> system:shutdown +10
+{code}
+
+Like for other commands, you can find details on the {{shutdown}} command man page:
+
+{code}
+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.
+{code}
+
+h2. 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).
+
+NB: the script returns 0 exit code if Apache Karaf is running, 1 exit code else.
+
+On Unix:
+
+{code}
+bin/status
+Not Running ...
+{code}
+
{code}
-or, on Unix:
+bin/status
+Running ...
{code}
-bin/stop
+
+On Windows:
+
{code}
+bin\status.bat
+Not Running ...
+{code}
+
+{code}
+bin\status.bat
+Running ...
+{code}
+
+h2. Restart
+
+The {{shutdown}} command accepts the {{-r}} ({{--restart}}) option to restart Apache Karaf:
+
+{code}
+karaf@root()> system:shutdown -r
+{code}
+
+{warning:title=Warning}
+This command does not start a new JVM. It simply restarts the OSGi framework.
+{warning}
+
+h2. 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.
\ No newline at end of file