karaf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jbono...@apache.org
Subject svn commit: r1547554 - /karaf/trunk/manual/src/main/webapp/users-guide/remote.conf
Date Tue, 03 Dec 2013 19:50:07 GMT
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



Mime
View raw message