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/12/03 20:50:07 UTC
svn commit: r1547554 -
/karaf/trunk/manual/src/main/webapp/users-guide/remote.conf
Author: jbonofre
Date: Tue Dec 3 19:50:06 2013
New Revision: 1547554
URL: http://svn.apache.org/r1547554
Log:
[KARAF-2511] Review and update the remove page of the user guide
Modified:
karaf/trunk/manual/src/main/webapp/users-guide/remote.conf
Modified: karaf/trunk/manual/src/main/webapp/users-guide/remote.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/remote.conf?rev=1547554&r1=1547553&r2=1547554&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/remote.conf (original)
+++ karaf/trunk/manual/src/main/webapp/users-guide/remote.conf Tue Dec 3 19:50:06 2013
@@ -1,107 +1,409 @@
-h1. Using remote instances
+h1. Remote
-h2. Configuring ssh access
+Apache Karaf supports a complete remote mechanism allowing you to remotely connect to a running Apache Karaf instance.
+More over, you can also browse, download, and upload files remotely to a running Apache Karaf instance.
-It does not always make sense to manage an instance of Karaf using its local console. You can manage Karaf remotely using a the ssh console.
+Apache Karaf embeds a complete SSHd server.
-When you start Karaf, it enables a remote console that can be accessed over SSH from any other Karaf console or plain SSH client. The remote console provides all the features of the local console and gives a remote user complete control over the container and services running inside of it.
+h2. SSHd server
-The SSH hostname and port number is configured in the {{etc/org.apache.karaf.shell.cfg}} configuration file with the following default values:
+When you start Apache Karaf, it enables a remote console that can be accessed over SSH.
+
+This remote console provides all the features of the "local" console, and gives a remote user complete control over the
+container and services running inside of it. As the "local" console, the remote console is secured by a RBAC mechanism
+(see the [Security section|security] of the user guide for details).
+
+In addition of the remote console, Apache Karaf also provides a remote filesystem. This remote filesystem can be accessed
+using a SCP/SFTP client.
+
+h3. Configuration
+
+The configuration of the SSHd server is stored in the {{etc/org.apache.karaf.shell.cfg}} file:
+
+{code}
+################################################################################
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You 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.
+#
+################################################################################
+
+#
+# These properties are used to configure Karaf's ssh shell.
+#
+
+#
+# Via sshPort and sshHost you define the address you can login into Karaf.
+#
+sshPort = 8101
+sshHost = 0.0.0.0
+
+#
+# The sshIdleTimeout defines the inactivity timeout to logout the SSH session.
+# The sshIdleTimeout is in milliseconds, and the default is set to 30 minutes.
+#
+sshIdleTimeout = 1800000
+
+#
+# sshRealm defines which JAAS domain to use for password authentication.
+#
+sshRealm = karaf
+
+#
+# The location of the hostKey file defines where the private/public key of the server
+# is located. If no file is at the defined location it will be ignored.
+#
+hostKey = ${karaf.etc}/host.key
+
+#
+# Role name used for SSH access authorization
+# If not set, this defaults to the ${karaf.admin.role} configured in etc/system.properties
+#
+# sshRole = admin
+
+#
+# Self defined key size in 1024, 2048, 3072, or 4096
+# If not set, this defaults to 1024.
+#
+# keySize = 1024
+
+#
+# Specify host key algorithm, defaults to DSA
+#
+# algorithm = DSA
+
+#
+# Defines the completion mode on the Karaf shell console. The possible values are:
+# - GLOBAL: it's the same behavior as in previous Karaf releases. The completion displays all commands and all aliases
+# ignoring if you are in a subshell or not.
+# - FIRST: the completion displays all commands and all aliases only when you are not in a subshell. When you are
+# in a subshell, the completion displays only the commands local to the subshell.
+# - SUBSHELL: the completion displays only the subshells on the root level. When you are in a subshell, the completion
+# displays only the commands local to the subshell.
+# This property define the default value when you use the Karaf shell console.
+# You can change the completion mode directly in the shell console, using shell:completion command.
+#
+completionMode = GLOBAL
+{code}
+
+The {{etc/org.apache.karaf.shell.cfg}} configuration file contains different properties to configure the SSHd server:
+
+* {{sshPort}} is the port number where the SSHd server is bound (by default, it's 8101).
+* {{sshHost}} is the address of the network interface where the SSHd server is bound. The default value is 0.0.0.0,
+ meaning that the SSHd server is bound on all network interfaces. You can bind on a target interface providing the IP
+ address of the network interface.
+* {{hostKey}} is the location of the {{host.key}} file. By defaut, it uses {{etc/host.key}}. This file stores the public
+ and private key pair of the SSHd server.
+* {{sshRole}} is the default role used for SSH access. The default value is the value of {{karaf.admin.role}} property
+ defined in {{etc/system.properties}}. See the [Security section|security] of this user guide for details.
+* {{keySize}} is the key size used by the SSHd server. The possible values are 1024, 2048, 3072, or 4096. The default
+ value is 1024.
+* {{algorithm}} is the host key algorithm used by the SSHd server. The possible values are DSA or RSA. The default
+ value is DSA.
+
+The SSHd server configuration can be changed at runtime:
+
+* by editing the {{etc/org.apache.karaf.shell.cfg}} configuration file
+* by using the {{config:*}} commands
+
+At runtime, when you change the SSHd server configuration, you have to restart the SSHd server to load the changes.
+You can do it with:
+
+{code}
+karaf@root()> bundle:restart -f org.apache.karaf.shell.ssh
+{code}
+
+The Apache Karaf SSHd server supports key/agent authentication and password authentication.
+
+h3. Console clients
+
+h4. System native clients
+
+The Apache Karaf SSHd server is a pure SSHd server, similar to OpenSSH daemon.
+
+It means that you can use directly a SSH client from your system.
+
+For instance, on Unix, you can directly use OpenSSH:
{code}
-sshPort=8101
-sshHost=0.0.0.0
-sshRealm=karaf
-hostKey=${karaf.base}/etc/host.key
-{code}
+~$ ssh -p 8101 karaf@localhost
+Authenticated with partial success.
+Authenticated with partial success.
+Authenticated with partial success.
+Password authentication
+Password:
+ __ __ ____
+ / //_/____ __________ _/ __/
+ / ,< / __ `/ ___/ __ `/ /_
+ / /| |/ /_/ / / / /_/ / __/
+ /_/ |_|\__,_/_/ \__,_/_/
-You can change this configuration using the [config commands|configuration] or by editing the above file, but you'll need to restart the ssh console in order for it to use the new parameters.
+ 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}
-config:property-set -p org.apache.karaf.shell sshPort 8102
-bundle:restart -f org.apache.karaf.shell.ssh
+
+On Windows, you can use Putty, Kitty, etc.
+
+If you don't have SSH client installed on your machine, you can use Apache Karaf client.
+
+h4. {{ssh:ssh}} command
+
+Apache Karaf itself provides a SSH client. When you are on the Apache Karaf console, you have the {{ssh:ssh}} command:
+
{code}
+karaf@root()> ssh:ssh --help
+DESCRIPTION
+ ssh:ssh
-h2. Connecting remotely
+ Connects to a remote SSH server
-h3. Using the {{ssh:ssh}} command
+SYNTAX
+ ssh:ssh [options] hostname [command]
-You can connect to a remote Karaf's console using the [{{ssh:ssh}}|/commands/ssh-ssh] command.
+ARGUMENTS
+ hostname
+ The host name to connect to via SSH
+ command
+ Optional command to execute
+
+OPTIONS
+ --help
+ Display this help message
+ -p, --port
+ The port to use for SSH connection
+ (defaults to 22)
+ -P, --password
+ The password for remote login
+ -q
+ Quiet Mode. Do not ask for confirmations
+ -l, --username
+ The user name for remote login
{code}
-karaf@root> ssh:ssh -l karaf -P karaf -p 8101 hostname
+
+Thanks to the {{ssh:ssh}} command, you can connect to another running Apache Karaf instance:
+
{code}
+karaf@root()> ssh:ssh -p 8101 karaf@192.168.134.2
+Connecting to host 192.168.134.2 on port 8101
+Connecting to unknown server. Add this server to known hosts ? (y/n)
+Storing the server key in known_hosts.
+Connected
+ __ __ ____
+ / //_/____ __________ _/ __/
+ / ,< / __ `/ ___/ __ `/ /_
+ / /| |/ /_/ / / / /_/ / __/
+ /_/ |_|\__,_/_/ \__,_/_/
-{warning}
-The default password is {{karaf}} but we recommend changing it. See the [security] section for more information.
-{warning}
+ Apache Karaf (3.0.0)
-To confirm that you have connected to the correct Karaf instance, type [{{shell:info}}|/commands/shell-info] at the {{karaf>}} prompt. Information about the currently connected instance is returned, as shown.
+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.
-{code}
-Karaf
- Karaf version 3.0.0-SNAPSHOT
- Karaf home C:\java\apache-karaf-3.0.0-SNAPSHOT
- Karaf base C:\java\apache-karaf-3.0.0-SNAPSHOT
- OSGi Framework org.apache.felix.framework - 4.0.3
- ...
+karaf@root()>
{code}
-h3. Using the Karaf client
+When you don't provide the {{command}} argument to the {{ssh:ssh}} command, you are in the interactive mode: you have
+a complete remote console available, where you can type commands, etc.
-The Karaf client allows to securely connect to a running local or remote Karaf instance.
+You can also provide directly a command to execute using the {{command}} argument. For instance, to remotely shutdown
+a Apache Karaf instance:
-For example, to quickly connect to a Karaf instance running in server mode on the same machine, run the following command:
{code}
-bin/client
+karaf@root()> ssh:ssh -p 8101 karaf@localhost system:shutdown -f
+Connecting to host localhost on port 8101
+Connected
{code}
-To connect to remote instances provide a hostname, port, username and password. It is also possible to append console commands as follows:
+As the {{ssh:ssh}} command is a pure SSH client, so it means that you can connect to a Unix OpenSSH daemon:
+
{code}
-bin/client -a 8101 -h hostname -u karaf -p karaf features:install wrapper
+karaf@root()> ssh:ssh user@localhost
+Connecting to host localhost on port 22
+Connecting to unknown server. Add this server to known hosts ? (y/n)
+Storing the server key in known_hosts.
+Agent authentication failed, falling back to password authentication.
+Password: Connected
+Last login: Sun Sep 8 19:21:12 2013
+user@server:~$
{code}
-To display the available options for the client, type:
+h4. Apache Karaf client
+
+The {{ssh:ssh}} command requires to be run into a running Apache Karaf console.
+
+For commodity, the {{ssh:ssh}} command is "wrapped" as a standalone client: the {{bin/client}} Unix script ({{bin\client.bat}} on Windows).
+
{code}
-> bin/client --help
+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
- -p [password] specify the password
--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}
-h3. Using a plain SSH client
+For instance, to connect to local Apache Karaf instance (on the default SSHd server 8101 port), you can directly use
+{{bin/client}} Unix script ({{bin\client.bat}} on Windows) without any argument or option:
-You can also connect using a plain SSH client from your *nix system or Windows SSH client like Putty.
{code}
-~$ ssh -p 8101 karaf@localhost
-karaf@localhost's password:
+bin/client
+Logging in as karaf
+343 [pool-2-thread-4] 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}
-h3. Disconnecting from a remote console
+When you don't provide the {{command}} argument to the {{bin/client}} Unix script ({{bin\client.bat}} on Windows), you are
+in the interactive mode: you have a complete remote console available, where you can type commands, etc.
-To disconnect from a remote console, press {{Ctrl+D}}, {{shell:logout}} or simply {{logout}} at the Karaf prompt.
+You can also provide directly a command to execute using the {{command}} argument. For instance, to remotely shutdown
+a Apache Karaf instance:
-h2. Stopping a remote instance
+{code}
+bin/client "system:shutdown -f"
+Logging in as karaf
+330 [pool-2-thread-3] WARN org.apache.sshd.client.keyverifier.AcceptAllServerKeyVerifier - Server at /0.0.0.0:8101 presented unverified key:
+{code}
-h3. Using the remote console
+As the Apache Karaf client is a pure SSH client, you can use to connect to any SSHd daemon (like Unix OpenSSH daemon):
-If you have connected to a remote console using the [{{ssh:ssh}}|/commands/ssh-ssh] command or the Karaf client, you can stop the remote instance using the [{{system:shutdown}}|/commands/osgi-shutdown] command.
+{code}
+bin/client -a 22 -h localhost -u user
+Logging in as user
+353 [pool-2-thread-2] WARN org.apache.sshd.client.keyverifier.AcceptAllServerKeyVerifier - Server at localhost/127.0.0.1:22 presented unverified key:
+Password:
+Welcome to Ubuntu 13.10 (GNU/Linux 3.11.0-13-generic x86_64)
-{info}
-Pressing {{Ctrl+D}} in a remote console simply closes the remote connection and returns you to the local shell.
-{info}
+ * Documentation: https://help.ubuntu.com/
-h3. Using the karaf client
+Last login: Tue Dec 3 18:18:31 2013 from localhost
+{code}
+
+h4. Logout
+
+When you are connected to a remote Apache Karaf console, you can logout using:
+
+* using CTRL-D key binding. Note that CTRL-D just logout from the remote console in this case, it doesn't shutdown
+ the Apache Karaf instance (as CTRL-D does when used on a local console).
+* using {{shell:logout}} command (or simply {{logout}})
+
+h3. Filsystem clients
+
+Apache Karaf SSHd server also provides complete fileystem access via SSH. For security reason, the available filesystem
+is limited to {{KARAF_BASE}} directory.
+
+You can use this remote filesystem with any SCP/SFTP compliant clients.
+
+h4. Native SCP/SFTP clients
+
+On Unix, you can directly use {{scp}} command to download/upload files to the Apache Karaf filesystem. For instance,
+to retrieve the {{karaf.log}} file remotely:
+
+{code}
+~$ scp -P 8101 karaf@localhost:/data/log/karaf.log .
+Authenticated with partial success.
+Authenticated with partial success.
+Authenticated with partial success.
+Password authentication
+Password:
+karaf.log
+{code}
+
+As you have access to the complete {{KARAF_BASE}} directory, you can remotely change the configuration file in the {{etc}}
+folder, retrieve log files, populate the {{system}} folder.
+
+On Windows, you can use WinSCP to access the Apache Karaf filesystem.
+
+It's probably easier to use a SFTP complient client.
+
+For instance, on Unix system, you can use {{lftp}} or {{ncftp}}:
-To stop a remote instance using the Karaf client, run the following from the {{lib}} directory:
{code}
-bin/client -u karaf -p karaf -a 8101 hostname system:shutdown
+$ lftp
+lftp :~> open -u karaf sftp://localhost:8101
+Password:
+lftp karaf@localhost:~> ls
+-rw-r--r-- 1 jbonofre jbonofre 27754 Oct 26 10:50 LICENSE
+-rw-r--r-- 1 jbonofre jbonofre 1919 Dec 3 05:34 NOTICE
+-rw-r--r-- 1 jbonofre jbonofre 3933 Aug 18 2012 README
+-rw-r--r-- 1 jbonofre jbonofre 101041 Dec 3 05:34 RELEASE-NOTES
+drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 12:51 bin
+drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 18:57 data
+drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 12:51 demos
+drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 13:02 deploy
+drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 17:59 etc
+drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 13:02 instances
+drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 13:02 lib
+-rw-r--r-- 1 jbonofre jbonofre 0 Dec 3 13:02 lock
+drwxr-xr-x 1 jbonofre jbonofre 4096 Dec 3 12:51 system
+lftp karaf@localhost:/>
{code}
+
+You can also use graphic client like {{filezilla}}, {{gftp}}, {{nautilus}}, etc.
+
+On Windows, you can use {{filezilla}}, {{WinSCP}}, etc.
+
+h4. Apache Maven
+
+Apache Karaf {{system}} folder is the Karaf repository, that use a Maven directory structure. It's where Apache Karaf
+looks for the artifacts (bundles, features, kars, etc).
+
+Using Apache Maven, you can populate the {{system}} folder using the {{deploy:deploy-file}} goal.
+
+For instance, you want to add the Apache ServiceMix facebook4j OSGi bundle, you can do:
+
+{code}
+mvn deploy:deploy-file -Dfile=org.apache.servicemix.bundles.facebook4j-2.0.2_1.jar -DgroupId=org.apache.servicemix.bundles -DartifactId=org.apache.servicemix.bundles.facebook4j -Dversion=2.0.2_1 -Dpackaging=jar -Durl=scp://localhost:8101/system
+{code}
+
+{tip}
+If you want to turn Apache Karaf as a simple Maven repository, you can use [Apache Karaf Cave|http://karaf.apache.org/index/subprojects/cave.html].
+{tip}
+
+h2. JMX MBeanServer
+
+Apache Karaf provides a JMX MBeanServer.
+
+This MBeanServer is available remotely, using any JMX client like {{jconsole}}.
+
+You can find details on the [Monitoring section|monitoring] of the user guide.
\ No newline at end of file