Interface ClientSession
-
- All Superinterfaces:
AttributeRepository
,AttributeStore
,java.lang.AutoCloseable
,java.nio.channels.Channel
,ChannelListenerManager
,ChannelStreamPacketWriterResolver
,ChannelStreamPacketWriterResolverManager
,ClientAuthenticationManager
,ClientProxyConnectorHolder
,java.io.Closeable
,Closeable
,ConnectionEndpointsIndicator
,FactoryManagerHolder
,KexExtensionHandlerManager
,KexFactoryManager
,KeyIdentityProviderHolder
,MutableUserHolder
,PacketWriter
,PortForwardingEventListenerManager
,PortForwardingInformationProvider
,PortForwardingManager
,PropertyResolver
,ReservedSessionMessagesManager
,Session
,SessionContext
,SessionDisconnectHandlerManager
,SessionHeartbeatController
,SessionListenerManager
,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.
-
-
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>
-
Nested classes/interfaces inherited from interface org.apache.sshd.common.session.SessionHeartbeatController
SessionHeartbeatController.HeartbeatType
-
-
Field Summary
Fields Modifier and Type Field Description static java.util.Set<ClientChannelEvent>
REMOTE_COMMAND_WAIT_EVENTS
-
Fields inherited from interface org.apache.sshd.common.channel.throttle.ChannelStreamPacketWriterResolver
NONE
-
Fields inherited from interface org.apache.sshd.client.ClientAuthenticationManager
DEFAULT_PASSWORD_PROMPTS, PASSWORD_PROMPTS, PREFERRED_AUTHS
-
Fields inherited from interface org.apache.sshd.common.Closeable
CLOSE_WAIT_TIMEOUT, DEFAULT_CLOSE_WAIT_TIMEOUT
-
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
-
Fields inherited from interface org.apache.sshd.common.session.SessionHeartbeatController
DEFAULT_CONNECTION_HEARTBEAT_INTERVAL, SESSION_HEARTBEAT_INTERVAL, SESSION_HEARTBEAT_TYPE
-
-
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(java.lang.String type)
Create a channel of the given type.ClientChannel
createChannel(java.lang.String type, java.lang.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(java.lang.String command)
Create a channel to execute a command using default PTY settings and environment.ChannelExec
createExecChannel(java.lang.String command, PtyChannelConfigurationHolder ptyConfig, java.util.Map<java.lang.String,?> env)
Create a channel to execute a command using specific PTY settings and/or environment.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, java.util.Map<java.lang.String,?> env)
Create a channel to start a shell using specific PTY settings and/or environment.ChannelSubsystem
createSubsystemChannel(java.lang.String subsystem)
Create a subsystem channel.default java.lang.String
executeRemoteCommand(java.lang.String command)
Execute a command that requires no input and returns its outputdefault void
executeRemoteCommand(java.lang.String command, java.io.OutputStream stdout, java.io.OutputStream stderr, java.nio.charset.Charset charset)
Execute a command that requires no input and redirects its STDOUT/STDERR streams to the user-provided onesdefault java.lang.String
executeRemoteCommand(java.lang.String command, java.io.OutputStream stderr, java.nio.charset.Charset charset)
Execute a command that requires no input and returns its outputjava.net.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()
java.util.Map<java.lang.Object,java.lang.Object>
getMetadataMap()
Access to the metadata.java.util.Set<ClientSession.ClientSessionEvent>
getSessionState()
static java.util.Iterator<java.lang.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.java.util.Set<ClientSession.ClientSessionEvent>
waitFor(java.util.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.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.ChannelStreamPacketWriterResolverManager
getChannelStreamPacketWriterResolver, resolveChannelStreamPacketWriter, resolveChannelStreamPacketWriterResolver, setChannelStreamPacketWriterResolver
-
Methods inherited from interface org.apache.sshd.client.ClientAuthenticationManager
addPasswordIdentity, addPublicKeyIdentity, getPasswordIdentityProvider, getRegisteredIdentities, getServerKeyVerifier, getUserInteraction, removePasswordIdentity, removePublicKeyIdentity, setPasswordIdentityProvider, 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.io.PacketWriter
writePacket
-
Methods inherited from interface org.apache.sshd.common.forward.PortForwardingEventListenerManager
addPortForwardingEventListener, getPortForwardingEventListenerProxy, removePortForwardingEventListener
-
Methods inherited from interface org.apache.sshd.common.forward.PortForwardingInformationProvider
getBoundLocalPortForward, getBoundRemotePortForward, getLocalForwardsBindings, getRemoteForwardsBindings, getStartedLocalPortForwards, getStartedRemotePortForwards, isLocalPortForwardingStartedForPort, isRemotePortForwardingStartedForPort
-
Methods inherited from interface org.apache.sshd.common.forward.PortForwardingManager
startDynamicPortForwarding, 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
-
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, resetAuthTimeout, resetIdleTimeout, resolveAttribute, sendDebugMessage, sendIgnoreMessage, setAuthenticated, startService, 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
-
Methods inherited from interface org.apache.sshd.common.session.SessionListenerManager
addSessionListener, getSessionListenerProxy, removeSessionListener
-
Methods inherited from interface org.apache.sshd.common.signature.SignatureFactoriesManager
getSignatureFactories, getSignatureFactoriesNameList, getSignatureFactoriesNames, 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 java.util.Set<ClientChannelEvent> REMOTE_COMMAND_WAIT_EVENTS
-
-
Method Detail
-
getConnectAddress
java.net.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 java.io.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:
java.io.IOException
- if failed to generate the future- See Also:
ClientAuthenticationManager.addPasswordIdentity(String)
,ClientAuthenticationManager.addPublicKeyIdentity(java.security.KeyPair)
-
createChannel
ClientChannel createChannel(java.lang.String type) throws java.io.IOException
Create a channel of the given type. Same as callingcreateChannel(type, null)
.- Parameters:
type
- The channel type- Returns:
- The created
ClientChannel
- Throws:
java.io.IOException
- If failed to create the requested channel
-
createChannel
ClientChannel createChannel(java.lang.String type, java.lang.String subType) throws java.io.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:
java.io.IOException
- If failed to create the requested channel
-
createShellChannel
default ChannelShell createShellChannel() throws java.io.IOException
Create a channel to start a shell using default PTY settings and environment.- Returns:
- The created
ChannelShell
- Throws:
java.io.IOException
- If failed to create the requested channel
-
createShellChannel
ChannelShell createShellChannel(PtyChannelConfigurationHolder ptyConfig, java.util.Map<java.lang.String,?> env) throws java.io.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:
java.io.IOException
- If failed to create the requested channel
-
createExecChannel
default ChannelExec createExecChannel(java.lang.String command) throws java.io.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:
java.io.IOException
- If failed to create the requested channel
-
createExecChannel
ChannelExec createExecChannel(java.lang.String command, PtyChannelConfigurationHolder ptyConfig, java.util.Map<java.lang.String,?> env) throws java.io.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:
java.io.IOException
- If failed to create the requested channel
-
executeRemoteCommand
default java.lang.String executeRemoteCommand(java.lang.String command) throws java.io.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:
java.io.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 java.lang.String executeRemoteCommand(java.lang.String command, java.io.OutputStream stderr, java.nio.charset.Charset charset) throws java.io.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:
java.io.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(java.lang.String command, java.io.OutputStream stdout, java.io.OutputStream stderr, java.nio.charset.Charset charset) throws java.io.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:
java.io.IOException
- If failed to execute the command or got a non-zero exit status- See Also:
validateCommandExitStatusCode
-
createSubsystemChannel
ChannelSubsystem createSubsystemChannel(java.lang.String subsystem) throws java.io.IOException
Create a subsystem channel.- Parameters:
subsystem
- The subsystem name- Returns:
- The created
ChannelSubsystem
- Throws:
java.io.IOException
- If failed to create the requested channel
-
createDirectTcpipChannel
ChannelDirectTcpip createDirectTcpipChannel(SshdSocketAddress local, SshdSocketAddress remote) throws java.io.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:
java.io.IOException
- If failed to create the requested channel
-
createLocalPortForwardingTracker
default ExplicitPortForwardingTracker createLocalPortForwardingTracker(SshdSocketAddress local, SshdSocketAddress remote) throws java.io.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:
java.io.IOException
- If failed to set up the requested forwarding- See Also:
PortForwardingManager.startLocalPortForwarding(SshdSocketAddress, SshdSocketAddress)
-
createRemotePortForwardingTracker
default ExplicitPortForwardingTracker createRemotePortForwardingTracker(SshdSocketAddress remote, SshdSocketAddress local) throws java.io.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:
java.io.IOException
- If failed to set up the requested forwarding- See Also:
PortForwardingManager.startRemotePortForwarding(SshdSocketAddress, SshdSocketAddress)
-
createDynamicPortForwardingTracker
default DynamicPortForwardingTracker createDynamicPortForwardingTracker(SshdSocketAddress local) throws java.io.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:
java.io.IOException
- If failed to set up the requested forwarding- See Also:
PortForwardingManager.startDynamicPortForwarding(SshdSocketAddress)
-
getSessionState
java.util.Set<ClientSession.ClientSessionEvent> getSessionState()
- Returns:
- A snapshot of the current session state
- See Also:
waitFor(Collection, long)
-
waitFor
java.util.Set<ClientSession.ClientSessionEvent> waitFor(java.util.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)
-
getMetadataMap
java.util.Map<java.lang.Object,java.lang.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 java.io.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:
java.io.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 java.util.Iterator<java.lang.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- Parameters:
session
- TheClientSession
- ignored ifnull
(i.e., empty iterator returned)- Returns:
- The wrapping iterator
- See Also:
ClientAuthenticationManager.getRegisteredIdentities()
,ClientAuthenticationManager.getPasswordIdentityProvider()
-
-