Interface ClientSession
-
- All Superinterfaces:
AttributeRepository
,AttributeStore
,AutoCloseable
,Channel
,ChannelListenerManager
,ChannelStreamWriterResolver
,ChannelStreamWriterResolverManager
,ClientAuthenticationManager
,ClientProxyConnectorHolder
,Closeable
,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 eitherClientAuthenticationManager.addPasswordIdentity(String)
orClientAuthenticationManager.addPublicKeyIdentity(java.security.KeyPair)
followed by a call toauth()
.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
When a given session is no longer used, it must be closed using thewaitFor(Collection, long)
method can be used to listen to specific events such as the session being established, authenticated or closed.Closeable.close(boolean)
method.- Author:
- Apache MINA SSHD Project
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
ClientSession.ClientSessionEvent
-
Nested classes/interfaces inherited from interface org.apache.sshd.common.AttributeRepository
AttributeRepository.AttributeKey<T extends Object>
-
Nested classes/interfaces inherited from interface org.apache.sshd.common.session.SessionHeartbeatController
SessionHeartbeatController.HeartbeatType
-
-
Field Summary
Fields Modifier and Type Field Description static Set<ClientChannelEvent>
REMOTE_COMMAND_WAIT_EVENTS
-
Fields inherited from interface org.apache.sshd.common.channel.throttle.ChannelStreamWriterResolver
NONE
-
Fields inherited from interface org.apache.sshd.common.PropertyResolver
EMPTY
-
Fields inherited from interface org.apache.sshd.common.session.SessionContext
DEFAULT_SSH_VERSION_PREFIX, FALLBACK_SSH_VERSION_PREFIX, MAX_VERSION_LINE_LENGTH
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method 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 theclose()
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 theclose()
method is called.default ExplicitPortForwardingTracker
createLocalPortForwardingTracker(SshdSocketAddress local, SshdSocketAddress remote)
Starts a local port forwarding and returns a tracker that stops the forwarding when theclose()
method is called.default ExplicitPortForwardingTracker
createRemotePortForwardingTracker(SshdSocketAddress remote, SshdSocketAddress local)
Starts a remote port forwarding and returns a tracker that stops the forwarding when theclose()
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 outputdefault 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 onesdefault String
executeRemoteCommand(String command, OutputStream stderr, Charset charset)
Execute a command that requires no input and returns its outputSocketAddress
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 keySet<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 passwordsstatic KeyIdentityProvider
providerOf(ClientSession session)
Creates a "unified"KeyIdentityProvider
of key pairs out of the registeredKeyPair
identities and the extra available ones as a single iterator of key pairsKeyExchangeFuture
switchToNoneCipher()
Switch to a none cipher for performance.Set<ClientSession.ClientSessionEvent>
waitFor(Collection<ClientSession.ClientSessionEvent> mask, long timeout)
Wait for any one of a specific state to be signaled.default Set<ClientSession.ClientSessionEvent>
waitFor(Collection<ClientSession.ClientSessionEvent> mask, Duration timeout)
Wait for any one of a specific state to be signaled.-
Methods inherited from interface org.apache.sshd.common.AttributeRepository
attributeKeys, getAttribute, getAttributesCount
-
Methods inherited from interface org.apache.sshd.common.AttributeStore
clearAttributes, computeAttributeIfAbsent, removeAttribute, setAttribute
-
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.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.client.session.ClientProxyConnectorHolder
getClientProxyConnector, setClientProxyConnector
-
Methods inherited from interface org.apache.sshd.common.Closeable
addCloseFutureListener, close, close, isClosed, isClosing, isOpen, removeCloseFutureListener
-
Methods inherited from interface org.apache.sshd.common.kex.extension.KexExtensionHandlerManager
getKexExtensionHandler, setKexExtensionHandler
-
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.keyprovider.KeyIdentityProviderHolder
getKeyIdentityProvider, setKeyIdentityProvider
-
Methods inherited from interface org.apache.sshd.common.auth.MutableUserHolder
setUsername
-
Methods inherited from interface org.apache.sshd.common.forward.PortForwardingEventListenerManager
addPortForwardingEventListener, getPortForwardingEventListenerProxy, removePortForwardingEventListener
-
Methods inherited from interface org.apache.sshd.common.forward.PortForwardingInformationProvider
getBoundLocalPortForwards, getBoundRemotePortForward, getLocalForwardsBindings, getRemoteForwardsBindings, getStartedLocalPortForwards, getStartedRemotePortForwards, isLocalPortForwardingStartedForPort, isRemotePortForwardingStartedForPort
-
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.PropertyResolver
getBoolean, getBooleanProperty, getCharset, getInteger, getIntProperty, getLong, getLongProperty, getObject, getParentPropertyResolver, getProperties, getString, getStringProperty, isEmpty
-
Methods inherited from interface org.apache.sshd.common.session.ReservedSessionMessagesManager
getReservedSessionMessagesHandler, setReservedSessionMessagesHandler
-
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, request, resetAuthTimeout, resetIdleTimeout, 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, isServerSession
-
Methods inherited from interface org.apache.sshd.common.session.SessionDisconnectHandlerManager
getSessionDisconnectHandler, setSessionDisconnectHandler
-
Methods inherited from interface org.apache.sshd.common.session.SessionHeartbeatController
disableSessionHeartbeat, getSessionHeartbeatInterval, getSessionHeartbeatType, setSessionHeartbeat, setSessionHeartbeat
-
Methods inherited from interface org.apache.sshd.common.session.SessionListenerManager
addSessionListener, getSessionListenerProxy, removeSessionListener
-
Methods inherited from interface org.apache.sshd.common.signature.SignatureFactoriesHolder
getSignatureFactories, getSignatureFactoriesNameList, getSignatureFactoriesNames
-
Methods inherited from interface org.apache.sshd.common.signature.SignatureFactoriesManager
setSignatureFactories, setSignatureFactoriesNameList, setSignatureFactoriesNames, setSignatureFactoriesNames
-
Methods inherited from interface org.apache.sshd.common.session.UnknownChannelReferenceHandlerManager
getUnknownChannelReferenceHandler, resolveUnknownChannelReferenceHandler, setUnknownChannelReferenceHandler
-
Methods inherited from interface org.apache.sshd.common.auth.UserAuthFactoriesManager
getUserAuthFactories, getUserAuthFactoriesNameList, getUserAuthFactoriesNames, setUserAuthFactories, setUserAuthFactoriesNameList, setUserAuthFactoriesNames
-
Methods inherited from interface org.apache.sshd.common.auth.UsernameHolder
getUsername
-
-
-
-
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 theSession.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 usingClientAuthenticationManager.addPasswordIdentity(String)
orClientAuthenticationManager.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 callingcreateChannel(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 typesubType
- 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 - ifnull
then internal defaults are usedenv
- Extra environment configuration to be transmitted to the server - ignored ifnull
/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 executeptyConfig
- The PTY configuration to use - ifnull
then internal defaults are usedenv
- Extra environment configuration to be transmitted to the server - ignored ifnull
/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 aRemoteException
is thrown with a cause ofServerException
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 LFstderr
- Standard error output stream - ifnull
then error stream data is ignored. Note: if the stream is notnull
then it will be left open when this method returns or exception is throwncharset
- The commandCharset
for input/output/error - ifnull
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 aRemoteException
is thrown with' aServerException
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 LFstdout
- Standard output stream - ifnull
then stream data is ignored. Note: if the stream is notnull
then it will be left open when this method returns or exception is thrownstderr
- Error output stream - ifnull
then stream data is ignored. Note: if the stream is notnull
then it will be left open when this method returns or exception is throwncharset
- The commandCharset
for output/error - ifnull
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 addressremote
- 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 theclose()
method is called. This tracker can be used in atry-with-resource
block to ensure cleanup of the set up forwarding.- Parameters:
localPort
- The local port - if zero one is allocatedremote
- 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 theclose()
method is called. This tracker can be used in atry-with-resource
block to ensure cleanup of the set up forwarding.- Parameters:
local
- The local addressremote
- 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 theclose()
method is called. This tracker can be used in atry-with-resource
block to ensure cleanup of the set up forwarding.- Parameters:
remote
- The remote addresslocal
- 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 theclose()
method is called. This tracker can be used in atry-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 requestClientSession.ClientSessionEvent
s masktimeout
- 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 requestClientSession.ClientSessionEvent
s masktimeout
- 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 notsynchronized
in any way - up to the user to take care of mutual exclusion if necessary
-
getFactoryManager
ClientFactoryManager getFactoryManager()
- Specified by:
getFactoryManager
in interfaceFactoryManagerHolder
- 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 registeredKeyPair
identities and the extra available ones as a single iterator of key pairs- Parameters:
session
- TheClientSession
- ignored ifnull
(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
- TheClientSession
- ignored ifnull
(i.e., empty iterator returned)- Returns:
- The wrapping iterator
- Throws:
IOException
- If failed to load the passwordsGeneralSecurityException
- If some security issue with the passwords- See Also:
ClientAuthenticationManager.getRegisteredIdentities()
,ClientAuthenticationManager.getPasswordIdentityProvider()
-
-