Red Hat Training

A Red Hat training course is available for Red Hat Fuse

8.2. Connecting and Disconnecting Remotely

Abstract

There are two alternative ways of connecting to a remote container. If you are already running an Red Hat JBoss Fuse command shell, you can 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.

8.2.1. Connecting to a Standalone Container from a Remote Container

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.

Using the ssh:ssh console command

You connect to a remote container's console using the ssh:ssh console command.

Example 8.2. ssh:ssh Command Syntax

ssh:ssh { -l username } { -P password } { -p port } { hostname }

-l username: The username used to connect to the remote container. Use valid JAAS login credentials that have admin privileges (see Chapter 14, Configuring JAAS Security).
-P password: The password used to connect to the remote container.
-p port: The SSH port used to access the desired container's remote console.
By default this value is 8101. See the section called “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 the section called “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. See Chapter 14, Configuring JAAS Securityfor details.

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 the section called “Configuring a standalone container for remote access”.

Example 8.3. Connecting to a Remote Console

JBossFuse:karaf@root>ssh:ssh -l smx -P smx -p 8108 hostname

To confirm that you have connected to the correct container, type shell:info at the prompt. Information about the currently connected instance is returned, as shown in Example 8.4, “Output of the shell:info Command”.

Example 8.4. Output of the shell:info Command

Karaf Karaf version 2.4.0.redhat-630187 Karaf home /home/jboss-fuse-6.3.0.redhat-187 Karaf base /home/jboss-fuse-6.3.0.redhat-187 OSGi Framework org.apache.felix.framework - 4.4.1 JVM Java Virtual Machine Java HotSpot(TM) Server VM version 25.121-b13 Version 1.8.0_121 Vendor Oracle Corporation Pid 4647 Uptime 32.558 seconds Total compile time 45.154 seconds Threads Live threads 87 Daemon threads 69 Peak 88 Total started 113 Memory Current heap size 206,941 kbytes Maximum heap size 932,096 kbytes Committed heap size 655,360 kbytes Pending objects 0 Garbage collector Name = 'PS Scavenge', Collections = 13, Time = 0.343 seconds Garbage collector Name = 'PS MarkSweep', Collections = 2, Time = 0.272 seconds Classes Current classes loaded 10,152 Total classes loaded 10,152 Total classes unloaded 0 Operating system Name Linux version 4.8.14-100.fc23.x86_64 Architecture i386 Processors 4

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.

8.2.2. Connecting to a Fabric Container From another Fabric Container

Overview

When containers are deployed into a fabric, they are all connected to each other. You can easily connect to any container's command console from any of its peers. When connecting using fabric, you do not need to know any of the location details for the container you want to connect to. The fabric's runtime registry stores all of the location details needed to establish the remote connection.

Using the fabric:container-connect command

In the context of a fabric, you should connect to a remote runtime's console using the fabric:container-connect command.

Example 8.5. fabric:container-connect Command Syntax

fabric:container-connect { -u username } { -p password } { containerName }

-u username: The username used to connect to the remote console. The default value is admin.
-p password: The password used to connect to the remote console. The default value is admin.
containerName: The name of the container.

Warning

We recommend that you change the default administrator username and password. See Chapter 14, Configuring JAAS Security for details.

Example 8.6. Connecting to a Remote Container

JBossFuse:karaf@root>fabric:container-connect -u admin -p admin containerName

Example 8.7. Output of the shell:info Command

 Karaf Karaf version 2.4.0.redhat-630187 Karaf home /home/aaki/Downloads/jboss-fuse-6.3.0.redhat-187 Karaf base /home/aaki/Downloads/jboss-fuse-6.3.0.redhat-187 OSGi Framework org.apache.felix.framework - 4.4.1 JVM Java Virtual Machine Java HotSpot(TM) Server VM version 25.121-b13 Version 1.8.0_121 Vendor Oracle Corporation Pid 4647 Uptime 32.558 seconds Total compile time 45.154 seconds Threads Live threads 87 Daemon threads 69 Peak 88 Total started 113 Memory Current heap size 206,941 kbytes Maximum heap size 932,096 kbytes Committed heap size 655,360 kbytes Pending objects 0 Garbage collector Name = 'PS Scavenge', Collections = 13, Time = 0.343 seconds Garbage collector Name = 'PS MarkSweep', Collections = 2, Time = 0.272 seconds Classes Current classes loaded 10,152 Total classes loaded 10,152 Total classes unloaded 0 Operating system Name Linux version 4.8.14-100.fc23.x86_64 Architecture i386 Processors 4

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.

8.2.3. Connecting to a Container Using the Client Command-Line Utility

Using the remote client

The remote client allows you to securely connect to a remote Red Hat JBoss Fuse container without having to launch a full JBoss Fuse container locally.

For example, to quickly connect to a JBoss 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:

client

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:

client -a 8101 -h hostname -u username -p password shell:info

Alternatively, if you omit the -p option, you will be prompted to enter a password.

For a standalone container, use any valid JAAS user credentials that have admin privileges.

For a container in a fabric, the default username and password is admin and admin.

To display the available options for the client, type:

client --help

Example 8.8. Karaf 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 (optional, if not provided, the password is prompted) NB: this option is deprecated and will be removed in next Karaf version --help shows this help message -v raise verbosity -l set client logging level. Set to 0 for ERROR logging and up to 4 for TRACE. -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 -k [keyFile] specify the private keyFile location when using key login [commands] commands to run If no commands are specified, the client will be put in an interactive mode

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.
Red Hat Fuse does not use admin/admin as the remote default credential. When you log into the application, Fuse would try to use username/password of an item randomly chosen from the etc/users.properties file. However, it is recommended not to use bin/client script without -u option, when you need to use username/password.

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, JBoss 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.

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.

8.2.4. Connecting to a Container Using the SSH Command-Line Utility

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 JBoss 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:

ssh -p 8101 jdoe@localhost

Important

Key-based login is currently supported only on standalone containers, not on Fabric containers.

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 the section called “Creating a new SSH key pair”).
You must install the public key from the SSH key pair into the container (see the section called “Installing the SSH public key in the container”).

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:

~/.ssh/id_rsa
~/.ssh/id_rsa.pub

On a Windows operating system, the default locations for an RSA key pair are:

C:\Documents and Settings\Username\.ssh\id_rsa
C:\Documents and Settings\Username\.ssh\id_rsa.pub

Note

Red Hat JBoss Fuse supports only RSA keys. DSA keys do not work.

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:

ssh-keygen -t rsa -b 2048

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:

Generating public/private rsa key pair.
Enter file in which to save the key (/Users/Username/.ssh/id_rsa):

Type return to save the key pair in the default location. You will then be prompted for a pass phrase:

Enter passphrase (empty for no passphrase):

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.

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 InstallDir/etc/keys.properties file. Each user entry in this file appears on a single line, in the following format:

Username=PublicKey,Role1,Role2,...

For example, given that your public key file, ~/.ssh/id_rsa.pub, has the following contents:

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

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):

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,admin

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.

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:

Index Realm                Module Class                                                                    
    1 karaf                org.apache.karaf.jaas.modules.properties.PropertiesLoginModule                  
    2 karaf                org.apache.karaf.jaas.modules.publickey.PublickeyLoginModule

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.

Logging in using key-based SSH

You are now ready to login to the container using the key-based SSH utility. For example:

$ ssh -p 8101 jdoe@localhost
      _ ____                  ______
     | |  _ \                |  ____|             
     | | |_) | ___  ___ ___  | |__ _   _ ___  ___
 _   | |  _   / _ \/ __/ __| |  __| | | / __|/ _ \
| |__| | |_) | (_) \__ \__ \ | |  | |_| \__ \  __/
 \____/|____/ \___/|___/___/ |_|   \__,_|___/\___|


  JBoss Fuse (6.3.0.redhat-xxx)
  http://www.redhat.com/products/jbossenterprisemiddleware/fuse/

Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit '<ctrl-d>' or 'osgi:shutdown' to shutdown JBoss Fuse.

JBossFuse:karaf@root>

Note

If you are using an encrypted private key, the ssh utility will prompt you to enter the pass phrase.

Select Your Language

Language:

Language:

Red Hat Training

8.2. Connecting and Disconnecting Remotely

8.2.1. Connecting to a Standalone Container from a Remote Container

Overview

Using the ssh:ssh console command

Disconnecting from a remote console

8.2.2. Connecting to a Fabric Container From another Fabric Container

Overview

Using the fabric:container-connect command

Disconnecting from a remote console

8.2.3. Connecting to a Container Using the Client Command-Line Utility

Using the remote client

Remote client default credentials

Disconnecting from a remote client console

8.2.4. Connecting to a Container Using the SSH Command-Line Utility

Overview

Prerequisites

Default key location

Creating a new SSH key pair

Installing the SSH public key in the container

Checking that public key authentication is supported

Logging in using key-based SSH

Quick Links

Help

Site Info

Related Sites

About

Red Hat legal and privacy links

Red Hat legal and privacy links

Language:

Language and Page Formatting Options

Language:

Red Hat Training

8.2. Connecting and Disconnecting Remotely

8.2.1. Connecting to a Standalone Container from a Remote Container

Overview

Using the ssh:ssh console command

Disconnecting from a remote console

8.2.2. Connecting to a Fabric Container From another Fabric Container

Overview

Using the fabric:container-connect command

Disconnecting from a remote console

8.2.3. Connecting to a Container Using the Client Command-Line Utility

Using the remote client

Remote client default credentials

Disconnecting from a remote client console

8.2.4. Connecting to a Container Using the SSH Command-Line Utility

Overview

Prerequisites

Default key location

Creating a new SSH key pair

Installing the SSH public key in the container

Checking that public key authentication is supported

Logging in using key-based SSH

Quick Links

Help

Site Info

Related Sites

Systems Status

About

Red Hat legal and privacy links

Red Hat legal and privacy links