Chapter 17. Using Remote Connections to Manage a Container It does not always make sense to use a local console to manage a container. Red Hat Fuse has a number of ways of remotely managing a container. You can use a remote container's command console or start a remote client. 17.1. Configuring a Container for Remote Access 17.1.1. Overview When you start the Red Hat Fuse runtime in default mode or in Section 2.1.3, "Launching the runtime in server mode" , it enables a remote console that can be accessed over SSH from any other Fuse console. The remote console provides all of the functionality of the local console and allows a remote user complete control over the container and the services running inside of it. Note When run in Section 2.1.4, "Launching the runtime in client mode" the Fuse runtime disables the remote console. 17.1.2. Configuring a standalone container for remote access The SSH hostname and port number are configured in the INSTALL_DIR/etc/org.apache.karaf.shell.cfg configuration file. Changing the Port for Remote Access shows a sample configuration that changes the port used to 8102. Changing the Port for Remote Access 17.2. Connecting and Disconnecting Remotely There are two alternative ways of connecting to a remote container. If you are already running an Red Hat Fuse command shell, you must invoke a console command to connect to the remote container. Alternatively, you can run a utility directly on the command-line to connect to the remote container. 17.2.1. Connecting to a Standalone Container from a Remote Container 17.2.1.1. Overview Any container's command console can be used to access a remote container. Using SSH, the local container's console connects to the remote container and functions as a command console for the remote container. 17.2.1.2. Using the ssh:ssh console command You connect to a remote container's console using the ssh:ssh console command. ssh:ssh Command Syntax -l The username used to connect to the remote container. Use valid JAAS login credentials that have admin privileges. -P The password used to connect to the remote container. -p The SSH port used to access the desired container's remote console. By default this value is 8101 . See Section 17.1.2, "Configuring a standalone container for remote access" for details on changing the port number. hostname The hostname of the machine that the remote container is running on. See Section 17.1.2, "Configuring a standalone container for remote access" for details on changing the hostname. Warning We recommend that you customize the username and password in the etc/users.properties file. Note If your remote container is deployed on an Oracle VM Server for SPARC instance, it is likely that the default SSH port value, 8101 , is already occupied by the Logical Domains Manager daemon. In this case, you will need to reconfigure the container's SSH port, as described in Section 17.1.2, "Configuring a standalone container for remote access" . To confirm that you have connected to the correct container, type shell:info at the Karaf console prompt, which returns information about the currently connected instance. 17.2.1.3. Disconnecting from a remote console To disconnect from a remote console, enter logout or press Ctrl + D at the prompt. You will be disconnected from the remote container and the console will once again manage the local container. 17.2.2. Connecting to a Container Using the Client Command-Line Utility 17.2.2.1. Using the remote client The remote client allows you to securely connect to a remote Red Hat Fuse container without having to launch a full Fuse container locally. For example, to quickly connect to a Fuse instance running in server mode on the same machine, open a command prompt and run the client[.bat] script (which is located in the InstallDir/bin directory), as follows: More usually, you would provide a hostname, port, username, and password to connect to a remote instance. If you were using the client within a larger script, for example in a test suite, you could append console commands as follows: Alternatively, if you omit the -p option, you are prompted to enter a password. For a standalone container, use any valid JAAS user credentials that have admin privileges. To display the available options for the client, type: Karaf Client Help 17.2.2.2. Remote client default credentials You might be surprised to find that you can log into your Karaf container using bin/client , without supplying any credentials. This is because the remote client program is pre-configured to use default credentials. If no credentials are specified, the remote client automatically tries to use the following default credentials (in sequence): Default SSH key - tries to login using the default Apache Karaf SSH key. The corresponding configuration entry that would allow this login to succeed is commented out by default in the etc/keys.properties file. Default username/password credentials - tries to login using the admin / admin combination of username and password. The corresponding configuration entry that would allow this login to succeed is commented out by default in the etc/users.properties file. Hence, if you create a new user in the Karaf container simply by uncommenting the default admin / admin credentials in users.properties , you will find that the bin/client utility can log in without supplying credentials. Important For your security, Fuse has disabled the default credentials (by commenting out) when the Karaf container is first installed. If you simply uncomment these default credentials, however, without changing the default password or SSH public key, you will open up a security hole in your Karaf container. You must never do this in a production environment. If you find that you can login to your container using bin/client without supplying credentials, this shows that your container is insecure and you must take steps to fix this in a production environment . 17.2.2.3. Disconnecting from a remote client console If you used the remote client to open a remote console, as opposed to using it to pass a command, you will need to disconnect from it. To disconnect from the remote client's console, enter logout or press Ctrl-D at the prompt. The client will disconnect and exit. 17.2.3. Connecting to a Container Using the SSH Command-Line Utility 17.2.3.1. Overview You can also use the ssh command-line utility (a standard utility on UNIX-like operating systems) to log in to the Red Hat Fuse container, where the authentication mechanism is based on public key encryption (the public key must first be installed in the container). For example, given that the container is configured to listen on TCP port 8101, you could log in as follows: Important Key-based login is currently supported only on standalone containers, not on Fabric containers. 17.2.3.2. Prerequisites To use key-based SSH login, the following prerequisites must be satisfied: The container must be standalone (Fabric is not supported) with the PublickeyLoginModule installed. You must have created an SSH key pair (see Section 17.2.3.4, "Creating a new SSH key pair" ). You must install the public key from the SSH key pair into the container (see Section 17.2.3.5, "Installing the SSH public key in the container" ). 17.2.3.3. Default key location The ssh command automatically looks for the private key in the default key location. It is recommended that you install your key in the default location, because it saves you the trouble of specifying the location explicitly. On a *NIX operating system, the default locations for an RSA key pair are: On a Windows operating system, the default locations for an RSA key pair are: Note Red Hat Fuse supports only RSA keys. DSA keys do not work. 17.2.3.4. Creating a new SSH key pair Generate an RSA key pair using the ssh-keygen utility. Open a new command prompt and enter the following command: The preceding command generates an RSA key with a key length of 2048 bits. You will then be prompted to specify the file name for the key pair: Type return to save the key pair in the default location. You will then be prompted for a pass phrase: You can optionally enter a pass phrase here or type return twice to select no pass phrase. Note If you want to use the same key pair for running Fabric console commands, it is recommended that you select no pass phrase , because Fabric does not support using encrypted private keys. 17.2.3.5. Installing the SSH public key in the container To use the SSH key pair for logging into the Red Hat JBoss Fuse container, you must install the SSH public key in the container by creating a new user entry in the INSTALL_DIR/etc/keys.properties file. Each user entry in this file appears on a single line, in the following format: For example, given that your public key file, ~/.ssh/id_rsa.pub , has the following contents: You can create the jdoe user with the admin role by adding the following entry to the InstallDir/etc/keys.properties file (on a single line): Important Do not insert the entire contents of the id_rsa.pub file here. Insert just the block of symbols which represents the public key itself. 17.2.3.6. Checking that public key authentication is supported After starting the container, you can check whether public key authentication is supported by running the jaas:realms console command, as follows: You should see that the PublickeyLoginModule is installed. With this configuration you can log in to the container using either username/password credentials or public key credentials. 17.2.3.7. Adding the ssh Role to etc/keys.properties The admingroup defined in etc/keys.properties must include the ssh role, as shown in the following example: If the ssh role is not included in the definition of admingroup , you must edit the etc/keys.properties and add the ssh role. 17.2.3.8. Logging in using key-based SSH You are now ready to login to the container using the key-based SSH utility. For example: Note If you are using an encrypted private key, the ssh utility will prompt you to enter the pass phrase. 17.3. Stopping a Remote Container If you have connected to a remote console using the ssh:ssh command or the remote client, you can stop the remote instance using the osgi:shutdown command. Note Pressing Ctrl + D in a remote console simply closes the remote connection and returns you to the local shell.

Commands:
sshPort=8102 sshHost=0.0.0.0
ssh:ssh -l username -P password -p port hostname
client
client -a 8101 -h hostname -u username -p password shell:info
client --help
Apache Felix 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) [commands] commands to run If no commands are specified, the client will be put in an interactive mode
ssh -p 8101 jdoe@localhost
~/.ssh/id_rsa ~/.ssh/id_rsa.pub
C:\Documents and Settings\Username\.ssh\id_rsa C:\Documents and Settings\Username\.ssh\id_rsa.pub
ssh-keygen -t rsa -b 2048
Generating public/private rsa key pair. Enter file in which to save the key (/Users/Username/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Username=PublicKey,Role1,Role2,
ssh-rsa AAAAB3NzaC1kc3MAAACBAP1/U4EddRIpUt9KnC7s5Of2EbdSPO9EAMMeP4C2USZpRV1AIlH7WT2NWPq/xfW6MPbLm1Vs14E7 gB00b/JmYLdrmVClpJ+f6AR7ECLCT7up1/63xhv4O1fnfqimFQ8E+4P208UewwI1VBNaFpEy9nXzrith1yrv8iIDGZ3RSAHHAAAAFQCX YFCPFSMLzLKSuYKi64QL8Fgc9QAAAnEA9+GghdabPd7LvKtcNrhXuXmUr7v6OuqC+VdMCz0HgmdRWVeOutRZT+ZxBxCBgLRJFnEj6Ewo FhO3zwkyjMim4TwWeotifI0o4KOuHiuzpnWRbqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog9/hWuWfBpKLZl6Ae1UlZAFMO/7PSSoAAACB AKKSU2PFl/qOLxIwmBZPPIcJshVe7bVUpFvyl3BbJDow8rXfskl8wO63OzP/qLmcJM0+JbcRU/53Jj7uyk31drV2qxhIOsLDC9dGCWj4 7Y7TyhPdXh/0dthTRBy6bqGtRPxGa7gJov1xm/UuYYXPIUR/3x9MAZvZ5xvE0kYXO+rx jdoe@doemachine.local
jdoe=AAAAB3NzaC1kc3MAAACBAP1/U4EddRIpUt9KnC7s5Of2EbdSPO9EAMMeP4C2USZpRV1AIlH7WT2NWPq/xfW6MPbLm1Vs14E7 gB00b/JmYLdrmVClpJ+f6AR7ECLCT7up1/63xhv4O1fnfqimFQ8E+4P208UewwI1VBNaFpEy9nXzrith1yrv8iIDGZ3RSAHHAAAAFQCX YFCPFSMLzLKSuYKi64QL8Fgc9QAAAnEA9+GghdabPd7LvKtcNrhXuXmUr7v6OuqC+VdMCz0HgmdRWVeOutRZT+ZxBxCBgLRJFnEj6Ewo FhO3zwkyjMim4TwWeotifI0o4KOuHiuzpnWRbqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog9/hWuWfBpKLZl6Ae1UlZAFMO/7PSSoAAACB AKKSU2PFl/qOLxIwmBZPPIcJshVe7bVUpFvyl3BbJDow8rXfskl8wO63OzP/qLmcJM0+JbcRU/53Jj7uyk31drV2qxhIOsLDC9dGCWj4 7Y7TyhPdXh/0dthTRBy6bqGtRPxGa7gJov1xm/UuYYXPIUR/3x9MAZvZ5xvE0kYXO+rx,g:admingroup
karaf@root()> jaas:realms Index │ Realm Name │ Login Module Class Name ──────┼────────────┼─────────────────────────────────────────────────────- 1 │ karaf │ org.apache.karaf.jaas.modules.properties.PropertiesLoginModule 2 │ karaf │ org.apache.karaf.jaas.modules.publickey.PublickeyLoginModule 3 │ karaf │ org.apache.karaf.jaas.modules.audit.FileAuditLoginModule 4 │ karaf │ org.apache.karaf.jaas.modules.audit.LogAuditLoginModule 5 │ karaf │ org.apache.karaf.jaas.modules.audit.EventAdminAuditLoginModule karaf@root()>
# For security reason, the default auto-signed key is disabled. The user guide describes how to generate/update the key. # #karaf=AAAAB3NzaC1kc3MAAACBAP1/U4EddRIpUt9KnC7s5Of2EbdSPO9EAMMeP4C2USZpRV1AIlH7WT2NWPq/xfW6MPbLm1Vs14E7gB00b/JmYLdrmVClpJ+f6AR7ECLCT7up1/63xhv4O1fnxqimFQ8E+4P208UewwI1VBNaFpEy9nXzrith1yrv8iIDGZ3RSAHHAAAAFQCXYFCPFSMLzLKSuYKi64QL8Fgc9QAAAIEA9+GghdabPd7LvKtcNrhXuXmUr7v6OuqC+VdMCz0HgmdRWVeOutRZT+ZxBxCBgLRJFnEj6EwoFhO3zwkyjMim4TwWeotUfI0o4KOuHiuzpnWRbqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog9/hWuWfBpKLZl6Ae1UlZAFMO/7PSSoAAACBAKKSU2PFl/qOLxIwmBZPPIcJshVe7bVUpFvyl3BbJDow8rXfskl8wO63OzP/qLmcJM0+JbcRU/53JjTuyk31drV2qxhIOsLDC9dGCWj47Y7TyhPdXh/0dthTRBy6bqGtRPxGa7gJov1xm/UuYYXPIUR/3x9MAZvZ5xvE0kYXO+rx,_g_:admingroup _g_\:admingroup = group,admin,manager,viewer,systembundles,ssh
ssh -p 8101 jdoe@localhost ____ _ _ _ _ _____ | _ \ ___ __| | | | | | __ _| |_ | ___| _ ___ ___ | |_) / _ \/ _` | | |_| |/ _` | __| | |_ | | | / __|/ _ | _ < __/ (_| | | _ | (_| | |_ | _|| |_| \__ \ __/ |_| \_\___|\__,_| |_| |_|\__,_|\__| |_| \__,_|___/___| Fuse (7.x.x.fuse-xxxxxx-redhat-xxxxx) http://www.redhat.com/products/jbossenterprisemiddleware/fuse/ Hit '<tab>' for a list of available commands and '[cmd] --help' for help on a specific command. Open a browser to http://localhost:8181/hawtio to access the management console Hit '<ctrl-d>' or 'shutdown' to shutdown Red Hat Fuse. karaf@root()>