org.apache.sshd.client.session

Interface ClientSession

All Superinterfaces:

AttributeRepository, AttributeStore, AutoCloseable, Channel, ChannelListenerManager, ChannelStreamWriterResolver, ChannelStreamWriterResolverManager, ClientAuthenticationManager, ClientProxyConnectorHolder, Closeable, ConnectionEndpointsIndicator, FactoryManagerHolder, KexExtensionHandlerManager, KexFactoryManager, KeyIdentityProviderHolder, MutableUserHolder, PortForwardingEventListenerManager, PortForwardingInformationProvider, PortForwardingManager, PropertyResolver, ReservedSessionMessagesManager, Session, SessionContext, SessionDisconnectHandlerManager, SessionHeartbeatController, SessionListenerManager, SignatureFactoriesHolder, SignatureFactoriesManager, UnknownChannelReferenceHandlerManager, UserAuthFactoriesManager<ClientSession,UserAuth,UserAuthFactory>, UsernameHolder

All Known Implementing Classes:

AbstractClientSession, ClientSessionImpl

public interface ClientSession
extends Session, ClientProxyConnectorHolder, ClientAuthenticationManager, PortForwardingManager

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 ClientAuthenticationManager.addPasswordIdentity(String) or ClientAuthenticationManager.addPublicKeyIdentity(java.security.KeyPair) followed by a call to 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(Collection, 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

Modifier and Type	Interface and Description
static class	ClientSession.ClientSessionEvent

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

SessionHeartbeatController.HeartbeatType

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

AttributeRepository.AttributeKey<T>

Field Summary

Fields

Modifier and Type	Field and Description
static Set<ClientChannelEvent>	REMOTE_COMMAND_WAIT_EVENTS

Fields inherited from interface org.apache.sshd.common.session.SessionContext

DEFAULT_SSH_VERSION_PREFIX, FALLBACK_SSH_VERSION_PREFIX, MAX_VERSION_LINE_LENGTH

Fields inherited from interface org.apache.sshd.common.PropertyResolver

EMPTY

Fields inherited from interface org.apache.sshd.common.channel.throttle.ChannelStreamWriterResolver

NONE

Method Summary

Modifier and Type	Method and Description
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.
default DynamicPortForwardingTracker	createDynamicPortForwardingTracker(SshdSocketAddress local) Starts a dynamic port forwarding and returns a tracker that stops the forwarding when the close() method is called.
default ChannelExec	createExecChannel(String command) Create a channel to execute a command using default PTY settings and environment.
ChannelExec	createExecChannel(String command, PtyChannelConfigurationHolder ptyConfig, Map<String,?> env) Create a channel to execute a command using specific PTY settings and/or environment.
default ExplicitPortForwardingTracker	createLocalPortForwardingTracker(int localPort, SshdSocketAddress remote) Starts a local port forwarding and returns a tracker that stops the forwarding when the close() method is called.
default ExplicitPortForwardingTracker	createLocalPortForwardingTracker(SshdSocketAddress local, SshdSocketAddress remote) Starts a local port forwarding and returns a tracker that stops the forwarding when the close() method is called.
default ExplicitPortForwardingTracker	createRemotePortForwardingTracker(SshdSocketAddress remote, SshdSocketAddress local) Starts a remote port forwarding and returns a tracker that stops the forwarding when the close() method is called.
default ChannelShell	createShellChannel() Create a channel to start a shell using default PTY settings and environment.
ChannelShell	createShellChannel(PtyChannelConfigurationHolder ptyConfig, Map<String,?> env) Create a channel to start a shell using specific PTY settings and/or environment.
ChannelSubsystem	createSubsystemChannel(String subsystem) Create a subsystem channel.
default String	executeRemoteCommand(String command) Execute a command that requires no input and returns its output
default String	executeRemoteCommand(String command, OutputStream stderr, Charset charset) Execute a command that requires no input and returns its output
default void	executeRemoteCommand(String command, OutputStream stdout, OutputStream stderr, Charset charset) Execute a command that requires no input and redirects its STDOUT/STDERR streams to the user-provided ones
SocketAddress	getConnectAddress() Returns the original address (after having been translated through host configuration entries if any) that was request to connect.
AttributeRepository	getConnectionContext()
ClientFactoryManager	getFactoryManager()
Map<Object,Object>	getMetadataMap() Access to the metadata.
PublicKey	getServerKey() Retrieves the server's key
Set<ClientSession.ClientSessionEvent>	getSessionState()
static Iterator<String>	passwordIteratorOf(ClientSession session) Creates a "unified" Iterator of passwords out of the registered passwords and the extra available ones as a single iterator of passwords
static KeyIdentityProvider	providerOf(ClientSession session) Creates a "unified" KeyIdentityProvider of key pairs out of the registered KeyPair identities and the extra available ones as a single iterator of key pairs
KeyExchangeFuture	switchToNoneCipher() Switch to a none cipher for performance.
default Set<ClientSession.ClientSessionEvent>	waitFor(Collection<ClientSession.ClientSessionEvent> mask, Duration timeout) Wait for any one of a specific state to be signaled.
Set<ClientSession.ClientSessionEvent>	waitFor(Collection<ClientSession.ClientSessionEvent> mask, long timeout) Wait for any one of a specific state to be signaled.

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

createBuffer, createBuffer, disconnect, exceptionCaught, getAuthTimeout, getAuthTimeoutStart, getIdleTimeout, getIdleTimeoutStart, getIoSession, getKex, getLocalAddress, getRemoteAddress, getService, getTimeoutStatus, prepareBuffer, reExchangeKeys, request, request, request, resetAuthTimeout, resetIdleTimeout, resolveAttribute, resolveAttribute, sendDebugMessage, sendIgnoreMessage, setAuthenticated, startService, writePacket, writePacket, writePacket, writePacket

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

getCipherInformation, getClientKexProposals, getClientVersion, getCompressionInformation, getKexNegotiationResult, getKexState, getMacInformation, getNegotiatedKexParameter, getServerKexProposals, getServerVersion, getSessionId, isAuthenticated, isDataIntegrityTransport, isSecureSessionTransport, isServerSession, isValidVersionPrefix

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

disableSessionHeartbeat, getSessionHeartbeatInterval, getSessionHeartbeatType, setSessionHeartbeat, setSessionHeartbeat

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

getBoolean, getBooleanProperty, getCharset, getInteger, getIntProperty, getLong, getLongProperty, getObject, getParentPropertyResolver, getProperties, getString, getStringProperty, isEmpty, isEmpty

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

clearAttributes, computeAttributeIfAbsent, removeAttribute, setAttribute

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

attributeKeys, getAttribute, getAttributesCount, ofAttributesMap, ofKeyValuePair

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

addCloseFutureListener, close, close, close, getMaxCloseWaitTime, isClosed, isClosing, isOpen, removeCloseFutureListener

Methods inherited from interface org.apache.sshd.common.auth.MutableUserHolder

setUsername

Methods inherited from interface org.apache.sshd.common.auth.UsernameHolder

getUsername

Methods inherited from interface org.apache.sshd.common.kex.KexFactoryManager

getCipherFactories, getCipherFactoriesNameList, getCipherFactoriesNames, getCompressionFactories, getCompressionFactoriesNameList, getCompressionFactoriesNames, getKeyExchangeFactories, getMacFactories, getMacFactoriesNameList, getMacFactoriesNames, setCipherFactories, setCipherFactoriesNameList, setCipherFactoriesNames, setCipherFactoriesNames, setCompressionFactories, setCompressionFactoriesNameList, setCompressionFactoriesNames, setCompressionFactoriesNames, setKeyExchangeFactories, setMacFactories, setMacFactoriesNameList, setMacFactoriesNames, setMacFactoriesNames

Methods inherited from interface org.apache.sshd.common.signature.SignatureFactoriesManager

getSignatureFactories, resolveSignatureFactories, setSignatureFactories, setSignatureFactoriesNameList, setSignatureFactoriesNames, setSignatureFactoriesNames

Methods inherited from interface org.apache.sshd.common.signature.SignatureFactoriesHolder

getSignatureFactories, getSignatureFactoriesNameList, getSignatureFactoriesNames

Methods inherited from interface org.apache.sshd.common.kex.extension.KexExtensionHandlerManager

getKexExtensionHandler, setKexExtensionHandler

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

addSessionListener, getSessionListenerProxy, removeSessionListener

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

getReservedSessionMessagesHandler, setReservedSessionMessagesHandler

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

getSessionDisconnectHandler, setSessionDisconnectHandler

Methods inherited from interface org.apache.sshd.common.channel.ChannelListenerManager

addChannelListener, getChannelListenerProxy, removeChannelListener

Methods inherited from interface org.apache.sshd.common.channel.throttle.ChannelStreamWriterResolverManager

getChannelStreamWriterResolver, resolveChannelStreamWriter, resolveChannelStreamWriterResolver, setChannelStreamWriterResolver

Methods inherited from interface org.apache.sshd.common.forward.PortForwardingEventListenerManager

addPortForwardingEventListener, getPortForwardingEventListenerProxy, removePortForwardingEventListener

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

getUnknownChannelReferenceHandler, resolveUnknownChannelReferenceHandler, setUnknownChannelReferenceHandler

Methods inherited from interface org.apache.sshd.client.session.ClientProxyConnectorHolder

getClientProxyConnector, setClientProxyConnector

Methods inherited from interface org.apache.sshd.client.ClientAuthenticationManager

addPasswordIdentity, addPublicKeyIdentity, getHostBasedAuthenticationReporter, getPasswordAuthenticationReporter, getPasswordIdentityProvider, getPublicKeyAuthenticationReporter, getRegisteredIdentities, getServerKeyVerifier, getUserInteraction, removePasswordIdentity, removePublicKeyIdentity, setHostBasedAuthenticationReporter, setPasswordAuthenticationReporter, setPasswordIdentityProvider, setPublicKeyAuthenticationReporter, setServerKeyVerifier, setUserAuthFactoriesNames, setUserInteraction

Methods inherited from interface org.apache.sshd.common.auth.UserAuthFactoriesManager

getUserAuthFactories, getUserAuthFactoriesNameList, getUserAuthFactoriesNames, setUserAuthFactories, setUserAuthFactoriesNameList, setUserAuthFactoriesNames

Methods inherited from interface org.apache.sshd.common.keyprovider.KeyIdentityProviderHolder

getKeyIdentityProvider, setKeyIdentityProvider

Methods inherited from interface org.apache.sshd.common.forward.PortForwardingManager

startDynamicPortForwarding, startLocalPortForwarding, startLocalPortForwarding, startRemotePortForwarding, stopDynamicPortForwarding, stopLocalPortForwarding, stopRemotePortForwarding

Methods inherited from interface org.apache.sshd.common.forward.PortForwardingInformationProvider

getBoundLocalPortForwards, getBoundRemotePortForward, getLocalForwardsBindings, getRemoteForwardsBindings, getStartedLocalPortForwards, getStartedRemotePortForwards, isLocalPortForwardingStartedForPort, isRemotePortForwardingStartedForPort

Field Detail

REMOTE_COMMAND_WAIT_EVENTS

static final Set<ClientChannelEvent> REMOTE_COMMAND_WAIT_EVENTS

Method Detail

getConnectAddress

SocketAddress getConnectAddress()

Returns the original address (after having been translated through host configuration entries if any) that was request to connect. It contains the original host or address string that was used. Note: this may be different than the result of the Session.getIoSession() report of the remote peer

Returns:

The original requested address

getConnectionContext

AttributeRepository getConnectionContext()

Returns:

The "context" data provided when session connection was established - null if none.

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 ClientAuthenticationManager.addPasswordIdentity(String) or ClientAuthenticationManager.addPublicKeyIdentity(java.security.KeyPair).

Returns:

the authentication future

Throws:

IOException - if failed to generate the future

See Also:

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

getServerKey

PublicKey getServerKey()

Retrieves the server's key

Returns:

The server's PublicKey - null if KEX not started or not completed

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

default ChannelShell createShellChannel()
                                 throws IOException

Create a channel to start a shell using default PTY settings and environment.

Returns:

The created ChannelShell

Throws:

IOException - If failed to create the requested channel

createShellChannel

ChannelShell createShellChannel(PtyChannelConfigurationHolder ptyConfig,
                                Map<String,?> env)
                         throws IOException

Create a channel to start a shell using specific PTY settings and/or environment.

Parameters:

ptyConfig - The PTY configuration to use - if null then internal defaults are used

env - Extra environment configuration to be transmitted to the server - ignored if null/empty.

Returns:

The created ChannelShell

Throws:

IOException - If failed to create the requested channel

createExecChannel

default ChannelExec createExecChannel(String command)
                               throws IOException

Create a channel to execute a command using default PTY settings and environment.

Parameters:

command - The command to execute

Returns:

The created ChannelExec

Throws:

IOException - If failed to create the requested channel

createExecChannel

ChannelExec createExecChannel(String command,
                              PtyChannelConfigurationHolder ptyConfig,
                              Map<String,?> env)
                       throws IOException

Create a channel to execute a command using specific PTY settings and/or environment.

Parameters:

command - The command to execute

ptyConfig - The PTY configuration to use - if null then internal defaults are used

env - Extra environment configuration to be transmitted to the server - ignored if null/empty.

Returns:

The created ChannelExec

Throws:

IOException - If failed to create the requested channel

executeRemoteCommand

default String executeRemoteCommand(String command)
                             throws IOException

Execute a command that requires no input and returns its output

Parameters:

command - The command to execute

Returns:

The command's standard output result (assumed to be in US-ASCII)

Throws:

IOException - If failed to execute the command - including if anything was written to the standard error or a non-zero exit status was received. If this happens, then a RemoteException is thrown with a cause of ServerException containing the remote captured standard error - including CR/LF(s)

See Also:

executeRemoteCommand(String, OutputStream, Charset)

executeRemoteCommand

default String executeRemoteCommand(String command,
                                    OutputStream stderr,
                                    Charset charset)
                             throws IOException

Execute a command that requires no input and returns its output

Parameters:

command - The command to execute - without a terminating LF

stderr - Standard error output stream - if null then error stream data is ignored. Note: if the stream is not null then it will be left open when this method returns or exception is thrown

charset - The command Charset for input/output/error - if null then US_ASCII is assumed

Returns:

The command's standard output result

Throws:

IOException - If failed to manage the command channel - Note: the code does not check if anything was output to the standard error stream, but does check the reported exit status (if any) for non-zero value. If non-zero exit status received then a RemoteException is thrown with' a ServerException cause containing the exits value

See Also:

executeRemoteCommand(String, OutputStream, OutputStream, Charset)

executeRemoteCommand

default void executeRemoteCommand(String command,
                                  OutputStream stdout,
                                  OutputStream stderr,
                                  Charset charset)
                           throws IOException

Execute a command that requires no input and redirects its STDOUT/STDERR streams to the user-provided ones

Parameters:

command - The command to execute - without a terminating LF

stdout - Standard output stream - if null then stream data is ignored. Note: if the stream is not null then it will be left open when this method returns or exception is thrown

stderr - Error output stream - if null then stream data is ignored. Note: if the stream is not null then it will be left open when this method returns or exception is thrown

charset - The command Charset for output/error - if null then US_ASCII is assumed

Throws:

IOException - If failed to execute the command or got a non-zero exit status

See Also:

validateCommandExitStatusCode

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

createLocalPortForwardingTracker

default ExplicitPortForwardingTracker createLocalPortForwardingTracker(int localPort,
                                                                       SshdSocketAddress remote)
                                                                throws IOException

Starts a local port forwarding and returns a tracker that stops the forwarding when the close() method is called. This tracker can be used in a try-with-resource block to ensure cleanup of the set up forwarding.

Parameters:

localPort - The local port - if zero one is allocated

remote - The remote address

Returns:

The tracker instance

Throws:

IOException - If failed to set up the requested forwarding

See Also:

PortForwardingManager.startLocalPortForwarding(SshdSocketAddress, SshdSocketAddress)

createLocalPortForwardingTracker

default ExplicitPortForwardingTracker createLocalPortForwardingTracker(SshdSocketAddress local,
                                                                       SshdSocketAddress remote)
                                                                throws IOException

Starts a local port forwarding and returns a tracker that stops the forwarding when the close() method is called. This tracker can be used in a try-with-resource block to ensure cleanup of the set up forwarding.

Parameters:

local - The local address

remote - The remote address

Returns:

The tracker instance

Throws:

IOException - If failed to set up the requested forwarding

See Also:

PortForwardingManager.startLocalPortForwarding(SshdSocketAddress, SshdSocketAddress)

createRemotePortForwardingTracker

default ExplicitPortForwardingTracker createRemotePortForwardingTracker(SshdSocketAddress remote,
                                                                        SshdSocketAddress local)
                                                                 throws IOException

Starts a remote port forwarding and returns a tracker that stops the forwarding when the close() method is called. This tracker can be used in a try-with-resource block to ensure cleanup of the set up forwarding.

Parameters:

remote - The remote address

local - The local address

Returns:

The tracker instance

Throws:

IOException - If failed to set up the requested forwarding

See Also:

PortForwardingManager.startRemotePortForwarding(SshdSocketAddress, SshdSocketAddress)

createDynamicPortForwardingTracker

default DynamicPortForwardingTracker createDynamicPortForwardingTracker(SshdSocketAddress local)
                                                                 throws IOException

Starts a dynamic port forwarding and returns a tracker that stops the forwarding when the close() method is called. This tracker can be used in a try-with-resource block to ensure cleanup of the set up forwarding.

Parameters:

local - The local address

Returns:

The tracker instance

Throws:

IOException - If failed to set up the requested forwarding

See Also:

PortForwardingManager.startDynamicPortForwarding(SshdSocketAddress)

getSessionState

Set<ClientSession.ClientSessionEvent> getSessionState()

Returns:

A snapshot of the current session state

See Also:

waitFor(Collection, long)

waitFor

Set<ClientSession.ClientSessionEvent> waitFor(Collection<ClientSession.ClientSessionEvent> mask,
                                              long timeout)

Wait for any one of a specific state to be signaled.

Parameters:

mask - The request ClientSession.ClientSessionEvents mask

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

Returns:

The actual state that was detected either due to the mask yielding one of the states or due to timeout (in which case the ClientSession.ClientSessionEvent.TIMEOUT value is set)

waitFor

default Set<ClientSession.ClientSessionEvent> waitFor(Collection<ClientSession.ClientSessionEvent> mask,
                                                      Duration timeout)

Wait for any one of a specific state to be signaled.

Parameters:

mask - The request ClientSession.ClientSessionEvents mask

timeout - Wait time - null means forever

Returns:

The actual state that was detected either due to the mask yielding one of the states or due to timeout (in which case the ClientSession.ClientSessionEvent.TIMEOUT value is set)

getMetadataMap

Map<Object,Object> getMetadataMap()

Access to the metadata.

Returns:

The metadata Map - Note: access to the map is not synchronized in any way - up to the user to take care of mutual exclusion if necessary

getFactoryManager

ClientFactoryManager getFactoryManager()

Specified by:

getFactoryManager in interface FactoryManagerHolder

Returns:

The ClientFactoryManager for this session.

switchToNoneCipher

KeyExchangeFuture 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 KeyExchangeFuture that can be used to wait for the exchange to be finished

Throws:

IOException - if a key exchange is already running

providerOf

static KeyIdentityProvider providerOf(ClientSession session)

Creates a "unified" KeyIdentityProvider of key pairs out of the registered KeyPair identities and the extra available ones as a single iterator of key pairs

Parameters:

session - The ClientSession - ignored if null (i.e., empty iterator returned)

Returns:

The wrapping KeyIdentityProvider

See Also:

ClientAuthenticationManager.getRegisteredIdentities(), KeyIdentityProviderHolder.getKeyIdentityProvider()

passwordIteratorOf

static Iterator<String> passwordIteratorOf(ClientSession session)
                                    throws IOException,
                                           GeneralSecurityException

Creates a "unified" Iterator of passwords out of the registered passwords and the extra available ones as a single iterator of passwords

Parameters:

session - The ClientSession - ignored if null (i.e., empty iterator returned)

Returns:

The wrapping iterator

Throws:

IOException - If failed to load the passwords

GeneralSecurityException - If some security issue with the passwords

See Also:

ClientAuthenticationManager.getRegisteredIdentities(), ClientAuthenticationManager.getPasswordIdentityProvider()