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.HeartbeatType
AttributeRepository.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_LENGTH
EMPTY
NONE
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.
|
createBuffer, createBuffer, disconnect, exceptionCaught, getAuthTimeout, getAuthTimeoutStart, getIdleTimeout, getIdleTimeoutStart, getIoSession, getKex, getLocalAddress, getRemoteAddress, getService, getTimeoutStatus, prepareBuffer, reExchangeKeys, request, request, request, request, resetAuthTimeout, resetIdleTimeout, resolveAttribute, resolveAttribute, sendDebugMessage, sendIgnoreMessage, setAuthenticated, startService, writePacket, writePacket, writePacket, writePacket
getCipherInformation, getClientKexProposals, getClientVersion, getCompressionInformation, getKexNegotiationResult, getKexState, getMacInformation, getNegotiatedKexParameter, getServerKexProposals, getServerVersion, getSessionId, isAuthenticated, isDataIntegrityTransport, isSecureSessionTransport, isServerSession, isValidSessionPayloadSize, isValidVersionPrefix, validateSessionPayloadSize
disableSessionHeartbeat, getSessionHeartbeatInterval, getSessionHeartbeatType, setSessionHeartbeat, setSessionHeartbeat
getBoolean, getBooleanProperty, getCharset, getInteger, getIntProperty, getLong, getLongProperty, getObject, getParentPropertyResolver, getProperties, getString, getStringProperty, isEmpty, isEmpty
clearAttributes, computeAttributeIfAbsent, removeAttribute, setAttribute
attributeKeys, getAttribute, getAttributesCount, ofAttributesMap, ofKeyValuePair
addCloseFutureListener, close, close, close, getMaxCloseWaitTime, isClosed, isClosing, isOpen, removeCloseFutureListener
setUsername
getUsername
getCipherFactories, getCipherFactoriesNameList, getCipherFactoriesNames, getCompressionFactories, getCompressionFactoriesNameList, getCompressionFactoriesNames, getKeyExchangeFactories, getMacFactories, getMacFactoriesNameList, getMacFactoriesNames, setCipherFactories, setCipherFactoriesNameList, setCipherFactoriesNames, setCipherFactoriesNames, setCompressionFactories, setCompressionFactoriesNameList, setCompressionFactoriesNames, setCompressionFactoriesNames, setKeyExchangeFactories, setMacFactories, setMacFactoriesNameList, setMacFactoriesNames, setMacFactoriesNames
getSignatureFactories, resolveSignatureFactories, setSignatureFactories, setSignatureFactoriesNameList, setSignatureFactoriesNames, setSignatureFactoriesNames
getSignatureFactories, getSignatureFactoriesNameList, getSignatureFactoriesNames
getKexExtensionHandler, setKexExtensionHandler
addSessionListener, getSessionListenerProxy, removeSessionListener
getReservedSessionMessagesHandler, setReservedSessionMessagesHandler
getSessionDisconnectHandler, setSessionDisconnectHandler
addChannelListener, getChannelListenerProxy, removeChannelListener
getChannelStreamWriterResolver, resolveChannelStreamWriter, resolveChannelStreamWriterResolver, setChannelStreamWriterResolver
addPortForwardingEventListener, getPortForwardingEventListenerProxy, removePortForwardingEventListener
getUnknownChannelReferenceHandler, resolveUnknownChannelReferenceHandler, setUnknownChannelReferenceHandler
getClientProxyConnector, setClientProxyConnector
addPasswordIdentity, addPublicKeyIdentity, getHostBasedAuthenticationReporter, getPasswordAuthenticationReporter, getPasswordIdentityProvider, getPublicKeyAuthenticationReporter, getRegisteredIdentities, getServerKeyVerifier, getUserInteraction, removePasswordIdentity, removePublicKeyIdentity, setHostBasedAuthenticationReporter, setPasswordAuthenticationReporter, setPasswordIdentityProvider, setPublicKeyAuthenticationReporter, setServerKeyVerifier, setUserAuthFactoriesNames, setUserInteraction
getUserAuthFactories, getUserAuthFactoriesNameList, getUserAuthFactoriesNames, setUserAuthFactories, setUserAuthFactoriesNameList, setUserAuthFactoriesNames
getKeyIdentityProvider, setKeyIdentityProvider
startDynamicPortForwarding, startLocalPortForwarding, startLocalPortForwarding, startRemotePortForwarding, stopDynamicPortForwarding, stopLocalPortForwarding, stopRemotePortForwarding
getBoundLocalPortForwards, getBoundRemotePortForward, getLocalForwardsBindings, getRemoteForwardsBindings, getStartedLocalPortForwards, getStartedRemotePortForwards, isLocalPortForwardingStartedForPort, isRemotePortForwardingStartedForPort
static 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)
PublicKey getServerKey()
PublicKey
- null
if KEX not started or not completedClientChannel createChannel(String type) throws IOException
createChannel(type, null)
.type
- The channel typeClientChannel
IOException
- If failed to create the requested channelClientChannel createChannel(String type, String subType) throws IOException
type
- The channel typesubType
- The channel sub-typeClientChannel
IOException
- If failed to create the requested channeldefault ChannelShell createShellChannel() throws IOException
ChannelShell
IOException
- 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.ChannelShell
IOException
- If failed to create the requested channeldefault ChannelExec createExecChannel(String command) throws IOException
command
- The command to executeChannelExec
IOException
- 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.ChannelExec
IOException
- 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 statusvalidateCommandExitStatusCode
ChannelSubsystem createSubsystemChannel(String subsystem) throws IOException
subsystem
- The subsystem nameChannelSubsystem
IOException
- If failed to create the requested channelChannelDirectTcpip createDirectTcpipChannel(SshdSocketAddress local, SshdSocketAddress remote) throws IOException
local
- The local addressremote
- The remote addressChannelDirectTcpip
IOException
- If failed to create the requested channeldefault ExplicitPortForwardingTracker createLocalPortForwardingTracker(int localPort, 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.localPort
- The local port - if zero one is allocatedremote
- The remote addressIOException
- If failed to set up the requested forwardingPortForwardingManager.startLocalPortForwarding(SshdSocketAddress, SshdSocketAddress)
default 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.ClientSessionEvent
s masktimeout
- Wait time in milliseconds - non-positive means foreverClientSession.ClientSessionEvent.TIMEOUT
value is set)default Set<ClientSession.ClientSessionEvent> waitFor(Collection<ClientSession.ClientSessionEvent> mask, Duration timeout)
mask
- The request ClientSession.ClientSessionEvent
s masktimeout
- Wait time - null 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 FactoryManagerHolder
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.
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) throws IOException, GeneralSecurityException
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)IOException
- If failed to load the passwordsGeneralSecurityException
- If some security issue with the passwordsClientAuthenticationManager.getRegisteredIdentities()
,
ClientAuthenticationManager.getPasswordIdentityProvider()
Copyright © 2008–2024 The Apache Software Foundation. All rights reserved.