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 java.util.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(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 the
close() method is called. |
ChannelExec |
createExecChannel(java.lang.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(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 output
|
default 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 output
|
default 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 ones
|
java.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.
|
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 |
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.
|
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.
|
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 java.util.Set<ClientChannelEvent> REMOTE_COMMAND_WAIT_EVENTS
java.net.SocketAddress getConnectAddress()
Session.getIoSession()
report of the
remote peerAttributeRepository getConnectionContext()
null
if none.AuthFuture auth() throws java.io.IOException
ClientAuthenticationManager.addPasswordIdentity(String)
or ClientAuthenticationManager.addPublicKeyIdentity(java.security.KeyPair)
.java.io.IOException
- if failed to generate the futureClientAuthenticationManager.addPasswordIdentity(String)
,
ClientAuthenticationManager.addPublicKeyIdentity(java.security.KeyPair)
ClientChannel createChannel(java.lang.String type) throws java.io.IOException
createChannel(type, null)
.type
- The channel typeClientChannel
java.io.IOException
- If failed to create the requested channelClientChannel createChannel(java.lang.String type, java.lang.String subType) throws java.io.IOException
type
- The channel typesubType
- The channel sub-typeClientChannel
java.io.IOException
- If failed to create the requested channelChannelShell createShellChannel() throws java.io.IOException
ChannelShell
java.io.IOException
- If failed to create the requested channelChannelExec createExecChannel(java.lang.String command) throws java.io.IOException
command
- The command to executeChannelExec
java.io.IOException
- If failed to create the requested channeldefault java.lang.String executeRemoteCommand(java.lang.String command) throws java.io.IOException
command
- The command to executejava.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 a RemoteException
is
thrown with a cause of ServerException
containing the remote
captured standard error - including CR/LF(s)executeRemoteCommand(String, OutputStream, Charset)
default java.lang.String executeRemoteCommand(java.lang.String command, java.io.OutputStream stderr, java.nio.charset.Charset charset) throws java.io.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 assumedjava.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 a RemoteException
is thrown with'
a ServerException
cause containing the exits valueexecuteRemoteCommand(String, OutputStream, OutputStream, Charset)
default void executeRemoteCommand(java.lang.String command, java.io.OutputStream stdout, java.io.OutputStream stderr, java.nio.charset.Charset charset) throws java.io.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 assumedjava.io.IOException
- If failed to execute the command or got a non-zero exit statusvalidateCommandExitStatusCode
ChannelSubsystem createSubsystemChannel(java.lang.String subsystem) throws java.io.IOException
subsystem
- The subsystem nameChannelSubsystem
java.io.IOException
- If failed to create the requested channelChannelDirectTcpip createDirectTcpipChannel(SshdSocketAddress local, SshdSocketAddress remote) throws java.io.IOException
local
- The local addressremote
- The remote addressChannelDirectTcpip
java.io.IOException
- If failed to create the requested channeldefault ExplicitPortForwardingTracker createLocalPortForwardingTracker(SshdSocketAddress local, SshdSocketAddress remote) throws java.io.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 addressjava.io.IOException
- If failed to set up the requested forwardingPortForwardingManager.startLocalPortForwarding(SshdSocketAddress, SshdSocketAddress)
default ExplicitPortForwardingTracker createRemotePortForwardingTracker(SshdSocketAddress remote, SshdSocketAddress local) throws java.io.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 addressjava.io.IOException
- If failed to set up the requested forwardingPortForwardingManager.startRemotePortForwarding(SshdSocketAddress, SshdSocketAddress)
default DynamicPortForwardingTracker createDynamicPortForwardingTracker(SshdSocketAddress local) throws java.io.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 addressjava.io.IOException
- If failed to set up the requested forwardingPortForwardingManager.startDynamicPortForwarding(SshdSocketAddress)
java.util.Set<ClientSession.ClientSessionEvent> waitFor(java.util.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)java.util.Map<java.lang.Object,java.lang.Object> getMetadataMap()
Map
ClientFactoryManager getFactoryManager()
getFactoryManager
in interface FactoryManagerHolder
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.
KeyExchangeFuture
that can be used to wait for the exchange
to be finishedjava.io.IOException
- 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 java.util.Iterator<java.lang.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()