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 |
Session.TimeoutStatus
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
CLOSE_WAIT_TIMEOUT, DEFAULT_CLOSE_WAIT_TIMEOUT
DEFAULT_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. |
ChannelExec |
createExecChannel(String command)
Create a channel to execute a command.
|
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. |
ChannelShell |
createShellChannel()
Create a channel to start a shell.
|
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.
|
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, getCipherInformation, getCompressionInformation, getIdleTimeout, getIdleTimeoutStart, getIoSession, getKex, getLocalAddress, getMacInformation, getNegotiatedKexParameter, getRemoteAddress, getService, getTimeoutStatus, prepareBuffer, reExchangeKeys, request, resetAuthTimeout, resetIdleTimeout, resolveAttribute, resolveAttribute, sendDebugMessage, sendIgnoreMessage, setAuthenticated, startService, writePacket
getClientVersion, getServerVersion, getSessionId, isAuthenticated, isValidVersionPrefix
getBoolean, getBooleanProperty, getInteger, getIntProperty, getLong, getLongProperty, getObject, getParentPropertyResolver, getProperties, getString, getStringProperty
clearAttributes, computeAttributeIfAbsent, removeAttribute, setAttribute
attributeKeys, getAttribute, getAttributesCount, ofAttributesMap, ofKeyValuePair
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, getSignatureFactories, getSignatureFactoriesNameList, getSignatureFactoriesNames, resolveSignatureFactories, setSignatureFactories, setSignatureFactoriesNameList, setSignatureFactoriesNames, setSignatureFactoriesNames
addSessionListener, getSessionListenerProxy, removeSessionListener
getReservedSessionMessagesHandler, setReservedSessionMessagesHandler
addChannelListener, getChannelListenerProxy, removeChannelListener
getChannelStreamPacketWriterResolver, resolveChannelStreamPacketWriter, resolveChannelStreamPacketWriterResolver, setChannelStreamPacketWriterResolver
addPortForwardingEventListener, getPortForwardingEventListenerProxy, removePortForwardingEventListener
getUnknownChannelReferenceHandler, resolveUnknownChannelReferenceHandler, setUnknownChannelReferenceHandler
writePacket
addCloseFutureListener, close, close, close, getMaxCloseWaitTime, isClosed, isClosing, isOpen, removeCloseFutureListener
getClientProxyConnector, setClientProxyConnector
addPasswordIdentity, addPublicKeyIdentity, getPasswordIdentityProvider, getRegisteredIdentities, getServerKeyVerifier, getUserAuthFactories, getUserAuthFactoriesNameList, getUserAuthFactoriesNames, getUserInteraction, removePasswordIdentity, removePublicKeyIdentity, setPasswordIdentityProvider, setServerKeyVerifier, setUserAuthFactories, setUserAuthFactoriesNameList, setUserAuthFactoriesNames, setUserAuthFactoriesNames, setUserInteraction
getKeyIdentityProvider, setKeyIdentityProvider
startDynamicPortForwarding, startLocalPortForwarding, startRemotePortForwarding, stopDynamicPortForwarding, stopLocalPortForwarding, stopRemotePortForwarding
getBoundLocalPortForward, 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)
ClientChannel 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 channelChannelShell createShellChannel() throws IOException
ChannelShell
IOException
- If failed to create the requested channelChannelExec createExecChannel(String command) throws IOException
command
- The command to executeChannelExec
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(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> 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)Map<Object,Object> getMetadataMap()
Map
ClientFactoryManager 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)
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–2022 The Apache Software Foundation. All rights reserved.