org.apache.sshd.client.session

Interface ClientSession

All Superinterfaces:

AutoCloseable, Channel, Closeable, Session

All Known Implementing Classes:

ClientSessionImpl

public interface ClientSession
extends Session

An authenticated session to a given SSH server

A client session is established using the SshClient. Once the session has been created, the user has to authenticate using either addPasswordIdentity(String) or addPublicKeyIdentity(java.security.KeyPair) followed by a call to {$link #auth()}.

From this session, channels can be created using the createChannel(String) method. Multiple channels can be created on a given session concurrently.

When using the client in an interactive mode, the waitFor(int, long) method can be used to listen to specific events such as the session being established, authenticated or closed.

When a given session is no longer used, it must be closed using the Closeable.close(boolean) method.

Author:

Apache MINA SSHD Project

Nested Class Summary

Nested classes/interfaces inherited from interface org.apache.sshd.common.session.Session

Session.AttributeKey<T>, Session.TimeoutStatus

Field Summary

Fields

Modifier and Type	Field and Description
static int	AUTHED
static int	CLOSED
static int	TIMEOUT
static int	WAIT_AUTH

Method Summary

Modifier and Type	Method and Description
void	addPasswordIdentity(String password)
void	addPublicKeyIdentity(KeyPair key)
AuthFuture	auth() Starts the authentication process.
ClientChannel	createChannel(String type) Create a channel of the given type.
ClientChannel	createChannel(String type, String subType) Create a channel of the given type and sub-type.
ChannelDirectTcpip	createDirectTcpipChannel(SshdSocketAddress local, SshdSocketAddress remote) Create a direct tcp-ip channel which can be used to stream data to a remote port from the server.
ChannelExec	createExecChannel(String command) Create a channel to execute a command.
ScpClient	createScpClient() Create an SCP client from this session.
ScpClient	createScpClient(ScpTransferEventListener listener) Create an SCP client from this session.
SftpClient	createSftpClient() Create an SFTP client from this session.
SftpClient	createSftpClient(SftpVersionSelector selector)
FileSystem	createSftpFileSystem()
FileSystem	createSftpFileSystem(int readBufferSize, int writeBufferSize)
FileSystem	createSftpFileSystem(SftpVersionSelector selector)
FileSystem	createSftpFileSystem(SftpVersionSelector selector, int readBufferSize, int writeBufferSize)
ChannelShell	createShellChannel() Create a channel to start a shell.
ChannelSubsystem	createSubsystemChannel(String subsystem) Create a subsystem channel.
ClientFactoryManager	getFactoryManager()
Map<Object,Object>	getMetadataMap() Access to the metadata.
ScpTransferEventListener	getScpTransferEventListener()
UserInteraction	getUserInteraction()
String	removePasswordIdentity(String password)
KeyPair	removePublicKeyIdentity(KeyPair kp)
void	setScpTransferEventListener(ScpTransferEventListener listener)
void	setUserInteraction(UserInteraction userInteraction)
SshdSocketAddress	startDynamicPortForwarding(SshdSocketAddress local) Start dynamic local port forwarding using a SOCKS proxy.
SshdSocketAddress	startLocalPortForwarding(SshdSocketAddress local, SshdSocketAddress remote) Start forwarding the given local address on the client to the given address on the server.
SshdSocketAddress	startRemotePortForwarding(SshdSocketAddress remote, SshdSocketAddress local) Start forwarding tcpip from the given address on the server to the given address on the client.
void	stopDynamicPortForwarding(SshdSocketAddress local) Stop a previously started dynamic port forwarding.
void	stopLocalPortForwarding(SshdSocketAddress local) Stop forwarding the given local address.
void	stopRemotePortForwarding(SshdSocketAddress remote) Stop forwarding of the given remote address.
SshFuture	switchToNoneCipher() Switch to a none cipher for performance.
int	waitFor(int mask, long timeout) Wait for a specific state.

Methods inherited from interface org.apache.sshd.common.session.Session

addListener, createBuffer, createBuffer, disconnect, exceptionCaught, getAttribute, getAuthTimeout, getClientVersion, getIdleTimeout, getIntProperty, getIoSession, getKex, getNegotiatedKexParameter, getServerVersion, getService, getSessionId, getTimeoutStatus, getUsername, isAuthenticated, reExchangeKeys, removeListener, request, resetIdleTimeout, setAttribute, setAuthenticated, setUsername, startService, writePacket, writePacket

Methods inherited from interface org.apache.sshd.common.Closeable

close, isClosed, isClosing

Methods inherited from interface java.nio.channels.Channel

close, isOpen

Field Detail

TIMEOUT

static final int TIMEOUT

See Also:

Constant Field Values

CLOSED

static final int CLOSED

See Also:

Constant Field Values

WAIT_AUTH

static final int WAIT_AUTH

See Also:

Constant Field Values

AUTHED

static final int AUTHED

See Also:

Constant Field Values

Method Detail

addPasswordIdentity

void addPasswordIdentity(String password)

Parameters:

password - Password to be added - may not be null/empty

removePasswordIdentity

String removePasswordIdentity(String password)

Parameters:

password - The password to remove - ignored if null/empty

Returns:

The removed password - same one that was added via addPasswordIdentity(String) - or null if no match found

addPublicKeyIdentity

void addPublicKeyIdentity(KeyPair key)

Parameters:

key - The KeyPair to add - may not be null

removePublicKeyIdentity

KeyPair removePublicKeyIdentity(KeyPair kp)

Parameters:

kp - The KeyPair to remove - ignored if null

Returns:

The removed KeyPair - same one that was added via addPublicKeyIdentity(KeyPair) - or null if no match found

getUserInteraction

UserInteraction getUserInteraction()

setUserInteraction

void setUserInteraction(UserInteraction userInteraction)

auth

AuthFuture auth()
         throws IOException

Starts the authentication process. User identities will be tried until the server successfully authenticate the user. User identities must be provided before calling this method using addPasswordIdentity(String) or addPublicKeyIdentity(java.security.KeyPair).

Returns:

the authentication future

Throws:

IOException - if failed to generate the future

See Also:

addPasswordIdentity(String), addPublicKeyIdentity(java.security.KeyPair)

createChannel

ClientChannel createChannel(String type)
                     throws IOException

Create a channel of the given type. Same as calling createChannel(type, null).

Parameters:

type - The channel type

Returns:

The created ClientChannel

Throws:

IOException - If failed to create the requested channel

createChannel

ClientChannel createChannel(String type,
                            String subType)
                     throws IOException

Create a channel of the given type and sub-type.

Parameters:

type - The channel type

subType - The channel sub-type

Returns:

The created ClientChannel

Throws:

IOException - If failed to create the requested channel

createShellChannel

ChannelShell createShellChannel()
                         throws IOException

Create a channel to start a shell.

Returns:

The created ChannelShell

Throws:

IOException - If failed to create the requested channel

createExecChannel

ChannelExec createExecChannel(String command)
                       throws IOException

Create a channel to execute a command.

Parameters:

command - The command to execute

Returns:

The created ChannelExec

Throws:

IOException - If failed to create the requested channel

createSubsystemChannel

ChannelSubsystem createSubsystemChannel(String subsystem)
                                 throws IOException

Create a subsystem channel.

Parameters:

subsystem - The subsystem name

Returns:

The created ChannelSubsystem

Throws:

IOException - If failed to create the requested channel

createDirectTcpipChannel

ChannelDirectTcpip createDirectTcpipChannel(SshdSocketAddress local,
                                            SshdSocketAddress remote)
                                     throws IOException

Create a direct tcp-ip channel which can be used to stream data to a remote port from the server.

Parameters:

local - The local address

remote - The remote address

Returns:

The created ChannelDirectTcpip

Throws:

IOException - If failed to create the requested channel

createScpClient

ScpClient createScpClient()

Create an SCP client from this session.

Returns:

An ScpClient instance. Note: uses the currently registered ScpTransferEventListener if any

See Also:

setScpTransferEventListener(ScpTransferEventListener)

createScpClient

ScpClient createScpClient(ScpTransferEventListener listener)

Create an SCP client from this session.

Parameters:

listener - A ScpTransferEventListener that can be used to receive information about the SCP operations - may be null to indicate no more events are required. Note: this listener is used instead of any listener set via setScpTransferEventListener(ScpTransferEventListener)

Returns:

An ScpClient instance

getScpTransferEventListener

ScpTransferEventListener getScpTransferEventListener()

Returns:

The last ScpTransferEventListener set via setScpTransferEventListener(ScpTransferEventListener)

setScpTransferEventListener

void setScpTransferEventListener(ScpTransferEventListener listener)

Parameters:

listener - A default ScpTransferEventListener that can be used to receive information about the SCP operations - may be null to indicate no more events are required

See Also:

createScpClient(ScpTransferEventListener)

createSftpClient

SftpClient createSftpClient()
                     throws IOException

Create an SFTP client from this session.

Returns:

The created SftpClient

Throws:

IOException - if failed to create the client

createSftpClient

SftpClient createSftpClient(SftpVersionSelector selector)
                     throws IOException

Parameters:

selector - The SftpVersionSelector to use - Note: if the server does not support versions re-negotiation then the selector will be presented with only one "choice" - the current version

Returns:

The created SftpClient

Throws:

IOException - If failed to create the client or re-negotiate

createSftpFileSystem

FileSystem createSftpFileSystem()
                         throws IOException

Throws:

IOException

createSftpFileSystem

FileSystem createSftpFileSystem(SftpVersionSelector selector)
                         throws IOException

Throws:

IOException

createSftpFileSystem

FileSystem createSftpFileSystem(int readBufferSize,
                                int writeBufferSize)
                         throws IOException

Throws:

IOException

createSftpFileSystem

FileSystem createSftpFileSystem(SftpVersionSelector selector,
                                int readBufferSize,
                                int writeBufferSize)
                         throws IOException

Throws:

IOException

startLocalPortForwarding

SshdSocketAddress startLocalPortForwarding(SshdSocketAddress local,
                                           SshdSocketAddress remote)
                                    throws IOException

Start forwarding the given local address on the client to the given address on the server.

Parameters:

local - The local address

remote - The remote address

Returns:

The bound SshdSocketAddress

Throws:

IOException - If failed to create the requested binding

stopLocalPortForwarding

void stopLocalPortForwarding(SshdSocketAddress local)
                      throws IOException

Stop forwarding the given local address.

Parameters:

local - The local address

Throws:

IOException - If failed to cancel the requested binding

startRemotePortForwarding

SshdSocketAddress startRemotePortForwarding(SshdSocketAddress remote,
                                            SshdSocketAddress local)
                                     throws IOException

Start forwarding tcpip from the given address on the server to the given address on the client.

The remote host name is the address to bind to on the server:

• "" means that connections are to be accepted on all protocol families supported by the SSH implementation
• "0.0.0.0" means to listen on all IPv4 addresses
• "::" means to listen on all IPv6 addresses
• "localhost" means to listen on all protocol families supported by the SSH implementation on loopback addresses only, [RFC3330] and RFC3513]
• "127.0.0.1" and "::1" indicate listening on the loopback interfaces for IPv4 and IPv6 respectively

Parameters:

local - The local address

remote - The remote address

Returns:

The bound SshdSocketAddress

Throws:

IOException - If failed to create the requested binding

stopRemotePortForwarding

void stopRemotePortForwarding(SshdSocketAddress remote)
                       throws IOException

Stop forwarding of the given remote address.

Parameters:

remote - The remote address

Throws:

IOException - If failed to cancel the requested binding

startDynamicPortForwarding

SshdSocketAddress startDynamicPortForwarding(SshdSocketAddress local)
                                      throws IOException

Start dynamic local port forwarding using a SOCKS proxy.

Parameters:

local - The local address

Returns:

The bound SshdSocketAddress

Throws:

IOException - If failed to create the requested binding

stopDynamicPortForwarding

void stopDynamicPortForwarding(SshdSocketAddress local)
                        throws IOException

Stop a previously started dynamic port forwarding.

Parameters:

local - The local address

Throws:

IOException - If failed to cancel the requested binding

waitFor

int waitFor(int mask,
            long timeout)

Wait for a specific state.

Parameters:

mask - The request mask

timeout - Wait time in milliseconds - non-positive means forever

Returns:

The actual state that was detected either due to the mask yielding non-zero state or due to timeout (in which case the TIMEOUT bit is set)

getMetadataMap

Map<Object,Object> getMetadataMap()

Access to the metadata.

Returns:

The metadata Map

getFactoryManager

ClientFactoryManager getFactoryManager()

Specified by:

getFactoryManager in interface Session

Returns:

The ClientFactoryManager for this session.

switchToNoneCipher

SshFuture switchToNoneCipher()
                      throws IOException

Switch to a none cipher for performance.

This should be done after the authentication phase has been performed. After such a switch, interactive channels are not allowed anymore. Both client and server must have been configured to support the none cipher. If that's not the case, the returned future will be set with an exception.

Returns:

an SshFuture that can be used to wait for the exchange to be finished

Throws:

IOException - if a key exchange is already running