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.
Closeable.close(boolean) method.| Modifier and Type | Interface and Description |
|---|---|
static class |
ClientSession.ClientSessionEvent |
SessionHeartbeatController.HeartbeatTypeAttributeRepository.AttributeKey<T>| Modifier and Type | Field and Description |
|---|---|
static Set<ClientChannelEvent> |
REMOTE_COMMAND_WAIT_EVENTS |
DEFAULT_SSH_VERSION_PREFIX, FALLBACK_SSH_VERSION_PREFIX, MAX_VERSION_LINE_LENGTHDEFAULT_CONNECTION_HEARTBEAT_INTERVAL, SESSION_HEARTBEAT_INTERVAL, SESSION_HEARTBEAT_TYPEEMPTYCLOSE_WAIT_TIMEOUT, DEFAULT_CLOSE_WAIT_TIMEOUTNONEDEFAULT_PASSWORD_PROMPTS, PASSWORD_PROMPTS, PREFERRED_AUTHS| 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(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.
|
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.
|
Set<ClientSession.ClientSessionEvent> |
waitFor(Collection<ClientSession.ClientSessionEvent> mask,
long timeout)
Wait for any one of a specific state to be signaled.
|
createBuffer, createBuffer, disconnect, exceptionCaught, getAuthTimeout, getAuthTimeoutStart, getIdleTimeout, getIdleTimeoutStart, getIoSession, getKex, getLocalAddress, getRemoteAddress, getService, getTimeoutStatus, prepareBuffer, reExchangeKeys, request, resetAuthTimeout, resetIdleTimeout, resolveAttribute, resolveAttribute, sendDebugMessage, sendIgnoreMessage, setAuthenticated, startService, writePacketgetCipherInformation, getClientKexProposals, getClientVersion, getCompressionInformation, getKexNegotiationResult, getKexState, getMacInformation, getNegotiatedKexParameter, getServerKexProposals, getServerVersion, getSessionId, isAuthenticated, isDataIntegrityTransport, isSecureSessionTransport, isServerSession, isValidVersionPrefixdisableSessionHeartbeat, getSessionHeartbeatInterval, getSessionHeartbeatType, setSessionHeartbeatgetBoolean, getBooleanProperty, getCharset, getInteger, getIntProperty, getLong, getLongProperty, getObject, getParentPropertyResolver, getProperties, getString, getStringPropertyclearAttributes, computeAttributeIfAbsent, removeAttribute, setAttributeattributeKeys, getAttribute, getAttributesCount, ofAttributesMap, ofKeyValuePairaddCloseFutureListener, close, close, close, getMaxCloseWaitTime, isClosed, isClosing, isOpen, removeCloseFutureListenersetUsernamegetUsernamegetCipherFactories, getCipherFactoriesNameList, getCipherFactoriesNames, getCompressionFactories, getCompressionFactoriesNameList, getCompressionFactoriesNames, getKeyExchangeFactories, getMacFactories, getMacFactoriesNameList, getMacFactoriesNames, setCipherFactories, setCipherFactoriesNameList, setCipherFactoriesNames, setCipherFactoriesNames, setCompressionFactories, setCompressionFactoriesNameList, setCompressionFactoriesNames, setCompressionFactoriesNames, setKeyExchangeFactories, setMacFactories, setMacFactoriesNameList, setMacFactoriesNames, setMacFactoriesNamesgetSignatureFactories, getSignatureFactories, getSignatureFactoriesNameList, getSignatureFactoriesNames, resolveSignatureFactories, setSignatureFactories, setSignatureFactoriesNameList, setSignatureFactoriesNames, setSignatureFactoriesNamesgetKexExtensionHandler, setKexExtensionHandleraddSessionListener, getSessionListenerProxy, removeSessionListenergetReservedSessionMessagesHandler, setReservedSessionMessagesHandlergetSessionDisconnectHandler, setSessionDisconnectHandleraddChannelListener, getChannelListenerProxy, removeChannelListenergetChannelStreamPacketWriterResolver, resolveChannelStreamPacketWriter, resolveChannelStreamPacketWriterResolver, setChannelStreamPacketWriterResolveraddPortForwardingEventListener, getPortForwardingEventListenerProxy, removePortForwardingEventListenergetUnknownChannelReferenceHandler, resolveUnknownChannelReferenceHandler, setUnknownChannelReferenceHandlercalculatePadLength, writePacketgetClientProxyConnector, setClientProxyConnectoraddPasswordIdentity, addPublicKeyIdentity, getPasswordIdentityProvider, getRegisteredIdentities, getServerKeyVerifier, getUserInteraction, removePasswordIdentity, removePublicKeyIdentity, setPasswordIdentityProvider, setServerKeyVerifier, setUserAuthFactoriesNames, setUserInteractiongetUserAuthFactories, getUserAuthFactoriesNameList, getUserAuthFactoriesNames, setUserAuthFactories, setUserAuthFactoriesNameList, setUserAuthFactoriesNamesgetKeyIdentityProvider, setKeyIdentityProviderstartDynamicPortForwarding, startLocalPortForwarding, startRemotePortForwarding, stopDynamicPortForwarding, stopLocalPortForwarding, stopRemotePortForwardinggetBoundLocalPortForward, getBoundRemotePortForward, getLocalForwardsBindings, getRemoteForwardsBindings, getStartedLocalPortForwards, getStartedRemotePortForwards, isLocalPortForwardingStartedForPort, isRemotePortForwardingStartedForPortstatic final Set<ClientChannelEvent> REMOTE_COMMAND_WAIT_EVENTS
SocketAddress getConnectAddress()
Session.getIoSession() report of the
remote peerAttributeRepository getConnectionContext()
null if none.AuthFuture auth() throws IOException
ClientAuthenticationManager.addPasswordIdentity(String) or ClientAuthenticationManager.addPublicKeyIdentity(java.security.KeyPair).IOException - if failed to generate the futureClientAuthenticationManager.addPasswordIdentity(String),
ClientAuthenticationManager.addPublicKeyIdentity(java.security.KeyPair)ClientChannel createChannel(String type) throws IOException
createChannel(type, null).type - The channel typeClientChannelIOException - If failed to create the requested channelClientChannel createChannel(String type, String subType) throws IOException
type - The channel typesubType - The channel sub-typeClientChannelIOException - If failed to create the requested channeldefault ChannelShell createShellChannel() throws IOException
ChannelShellIOException - If failed to create the requested channelChannelShell createShellChannel(PtyChannelConfigurationHolder ptyConfig, Map<String,?> env) throws IOException
ptyConfig - The PTY configuration to use - if null then
internal defaults are usedenv - Extra environment configuration to be transmitted to the server - ignored
if null/empty.ChannelShellIOException - If failed to create the requested channeldefault ChannelExec createExecChannel(String command) throws IOException
command - The command to executeChannelExecIOException - If failed to create the requested channelChannelExec createExecChannel(String command, PtyChannelConfigurationHolder ptyConfig, Map<String,?> env) throws IOException
command - The command to executeptyConfig - The PTY configuration to use - if null then
internal defaults are usedenv - Extra environment configuration to be transmitted to the server - ignored
if null/empty.ChannelExecIOException - If failed to create the requested channeldefault String executeRemoteCommand(String command) throws IOException
command - The command to executeIOException - 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)executeRemoteCommand(String, OutputStream, Charset)default String executeRemoteCommand(String command, OutputStream stderr, Charset charset) throws IOException
command - The command to execute - without a terminating LFstderr - 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 throwncharset - The command Charset for input/output/error - if
null then US_ASCII is assumedIOException - 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 valueexecuteRemoteCommand(String, OutputStream, OutputStream, Charset)default void executeRemoteCommand(String command, OutputStream stdout, OutputStream stderr, Charset charset) throws IOException
command - The command to execute - without a terminating LFstdout - 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 thrownstderr - 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 throwncharset - The command Charset for output/error - if
null then US_ASCII is assumedIOException - If failed to execute the command or got a non-zero exit statusvalidateCommandExitStatusCodeChannelSubsystem createSubsystemChannel(String subsystem) throws IOException
subsystem - The subsystem nameChannelSubsystemIOException - If failed to create the requested channelChannelDirectTcpip createDirectTcpipChannel(SshdSocketAddress local, SshdSocketAddress remote) throws IOException
local - The local addressremote - The remote addressChannelDirectTcpipIOException - If failed to create the requested channeldefault ExplicitPortForwardingTracker createLocalPortForwardingTracker(SshdSocketAddress local, SshdSocketAddress remote) throws IOException
close() method is called. This tracker can
be used in a try-with-resource block to ensure cleanup of the
set up forwarding.local - The local addressremote - The remote addressIOException - If failed to set up the requested forwardingPortForwardingManager.startLocalPortForwarding(SshdSocketAddress, SshdSocketAddress)default ExplicitPortForwardingTracker createRemotePortForwardingTracker(SshdSocketAddress remote, SshdSocketAddress local) throws IOException
close() method is called. This tracker can
be used in a try-with-resource block to ensure cleanup of the
set up forwarding.remote - The remote addresslocal - The local addressIOException - If failed to set up the requested forwardingPortForwardingManager.startRemotePortForwarding(SshdSocketAddress, SshdSocketAddress)default DynamicPortForwardingTracker createDynamicPortForwardingTracker(SshdSocketAddress local) throws IOException
close() method is called. This tracker can
be used in a try-with-resource block to ensure cleanup of the
set up forwarding.local - The local addressIOException - If failed to set up the requested forwardingPortForwardingManager.startDynamicPortForwarding(SshdSocketAddress)Set<ClientSession.ClientSessionEvent> getSessionState()
waitFor(Collection, long)Set<ClientSession.ClientSessionEvent> waitFor(Collection<ClientSession.ClientSessionEvent> mask, long timeout)
mask - The request ClientSession.ClientSessionEvents masktimeout - Wait time in milliseconds - non-positive means foreverClientSession.ClientSessionEvent.TIMEOUT value is set)Map<Object,Object> getMetadataMap()
Map - Note: access to the map
is not synchronized in any way - up to the user to take care
of mutual exclusion if necessaryClientFactoryManager getFactoryManager()
getFactoryManager in interface FactoryManagerHolderKeyExchangeFuture 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.
KeyExchangeFuture that can be used to wait for the exchange
to be finishedIOException - if a key exchange is already runningstatic KeyIdentityProvider providerOf(ClientSession session)
KeyIdentityProvider of key pairs out of the registered
KeyPair identities and the extra available ones as a single iterator
of key pairssession - The ClientSession - ignored if null (i.e., empty
iterator returned)ClientAuthenticationManager.getRegisteredIdentities(),
KeyIdentityProviderHolder.getKeyIdentityProvider()static Iterator<String> passwordIteratorOf(ClientSession session)
Iterator of passwords out of the registered
passwords and the extra available ones as a single iterator of passwordssession - The ClientSession - ignored if null (i.e., empty
iterator returned)ClientAuthenticationManager.getRegisteredIdentities(),
ClientAuthenticationManager.getPasswordIdentityProvider()Copyright © 2008–2020 The Apache Software Foundation. All rights reserved.