karaf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jbono...@apache.org
Subject svn commit: r1546148 - in /karaf/trunk/manual/src/main/webapp: update-notes.conf users-guide/index.conf users-guide/start-stop.conf
Date Wed, 27 Nov 2013 18:13:49 GMT
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



Mime
View raw message