public class SshClient extends AbstractFactoryManager implements ClientFactoryManager, ClientSessionCreator, Closeable
Entry point for the client side of the SSH protocol.
The default configured client can be created using
the setUpDefaultClient(). The next step is to
configure and then start the client using the start() method.
Sessions can then be created using on of the
ClientSessionCreator.connect(String, String, int) or ClientSessionCreator.connect(String, java.net.SocketAddress)
methods.
The client can be stopped any time using the stop() method.
Following is an example of using the SshClient:
try (SshClient client = SshClient.setUpDefaultClient()) {
...further configuration of the client...
client.start();
try (ClientSession session = client.connect(login, host, port)
.verify(...timeout...)
.getSession()) {
session.addPasswordIdentity(password);
session.auth().verify(...timeout...);
try (ClientChannel channel = session.createChannel(ClientChannel.CHANNEL_SHELL)) {
channel.setIn(new NoCloseInputStream(System.in));
channel.setOut(new NoCloseOutputStream(System.out));
channel.setErr(new NoCloseOutputStream(System.err));
channel.open();
channel.waitFor(ClientChannel.CLOSED, 0);
} finally {
session.close(false);
}
} finally {
client.stop();
}
}
SshClient instance
for the entire application and re-use it repeatedly in order to create
as many sessions as necessary - possibly with different hosts, ports, users,
passwords, etc. - including concurrently. In other words, except for
exceptional cases, it is recommended to initialize one instance of SshClient
for the application and then use throughout - including for multi-threading.
As long as the SshClient is not re-configured it should be multi-thread safe
regardless of the target session being created.AbstractCloseable.StateAttributeRepository.AttributeKey<T>SessionHeartbeatController.HeartbeatType| Modifier and Type | Field and Description |
|---|---|
protected IoConnector |
connector |
static List<ServiceFactory> |
DEFAULT_SERVICE_FACTORIES |
static Factory<SshClient> |
DEFAULT_SSH_CLIENT_FACTORY |
static List<UserAuthFactory> |
DEFAULT_USER_AUTH_FACTORIES
Default user authentication preferences if not set
|
protected SessionFactory |
sessionFactory |
protected List<UserAuthFactory> |
userAuthFactories |
protected UserInteraction |
userInteraction |
agentFactory, channelFactories, channelListenerProxy, channelListeners, executor, fileSystemFactory, forwarderFactory, forwardingFilter, globalRequestHandlers, ioServiceFactory, ioServiceFactoryFactory, randomFactory, serviceFactories, sessionListenerProxy, sessionListeners, sessionTimeoutListener, shutdownExecutor, timeoutListenerFuture, tunnelListenerProxy, tunnelListenerscloseFuture, futureLock, statelogCLIENT_IDENTIFICATION, DEFAULT_HEARTBEAT_INTERVAL, DEFAULT_HEARTBEAT_REPLY_WAIT, DEFAULT_IGNORE_INVALID_IDENTITIES, DEFAULT_KEEP_ALIVE_HEARTBEAT_STRING, DEFAULT_SEND_IMMEDIATE_IDENTIFICATION, DEFAULT_SEND_KEXINIT, HEARTBEAT_INTERVAL, HEARTBEAT_REPLY_WAIT, HEARTBEAT_REQUEST, IGNORE_INVALID_IDENTITIES, SEND_IMMEDIATE_IDENTIFICATION, SEND_IMMEDIATE_KEXINITAGENT_FORWARDING_TYPE, AGENT_FORWARDING_TYPE_IETF, AGENT_FORWARDING_TYPE_OPENSSH, AUTH_TIMEOUT, CHANNEL_CLOSE_TIMEOUT, DEFAULT_AUTH_TIMEOUT, DEFAULT_CHANNEL_CLOSE_TIMEOUT, DEFAULT_DISCONNECT_TIMEOUT, DEFAULT_IDLE_TIMEOUT, DEFAULT_IGNORE_MESSAGE_FREQUENCY, DEFAULT_IGNORE_MESSAGE_SIZE, DEFAULT_IGNORE_MESSAGE_VARIANCE, DEFAULT_LIMIT_PACKET_SIZE, DEFAULT_MAX_IDENTIFICATION_SIZE, DEFAULT_MAX_PACKET_SIZE, DEFAULT_NIO_WORKERS, DEFAULT_NIO2_MIN_WRITE_TIMEOUT, DEFAULT_NIO2_READ_TIMEOUT, DEFAULT_REKEY_BYTES_LIMIT, DEFAULT_REKEY_PACKETS_LIMIT, DEFAULT_REKEY_TIME_LIMIT, DEFAULT_STOP_WAIT_TIME, DEFAULT_VERSION, DEFAULT_WINDOW_SIZE, DEFAULT_WINDOW_TIMEOUT, DISCONNECT_TIMEOUT, IDLE_TIMEOUT, IGNORE_MESSAGE_FREQUENCY, IGNORE_MESSAGE_SIZE, IGNORE_MESSAGE_VARIANCE, LIMIT_PACKET_SIZE, MAX_IDENTIFICATION_SIZE, MAX_PACKET_SIZE, NIO_WORKERS, NIO2_MIN_WRITE_TIMEOUT, NIO2_READ_BUFFER_SIZE, NIO2_READ_TIMEOUT, REKEY_BLOCKS_LIMIT, REKEY_BYTES_LIMIT, REKEY_PACKETS_LIMIT, REKEY_TIME_LIMIT, SOCKET_BACKLOG, SOCKET_KEEPALIVE, SOCKET_LINGER, SOCKET_RCVBUF, SOCKET_REUSEADDR, SOCKET_SNDBUF, STOP_WAIT_TIME, TCP_NODELAY, WINDOW_SIZE, WINDOW_TIMEOUTNONEDEFAULT_CONNECTION_HEARTBEAT_INTERVAL, SESSION_HEARTBEAT_INTERVAL, SESSION_HEARTBEAT_TYPEEMPTYDEFAULT_PASSWORD_PROMPTS, PASSWORD_PROMPTS, PREFERRED_AUTHSCLOSE_WAIT_TIMEOUT, DEFAULT_CLOSE_WAIT_TIMEOUT| Constructor and Description |
|---|
SshClient() |
addChannelListener, addPortForwardingEventListener, addSessionListener, attributeKeys, clearAttributes, computeAttributeIfAbsent, createSessionTimeoutListener, getAgentFactory, getAttribute, getAttributesCount, getChannelFactories, getChannelListenerProxy, getChannelStreamPacketWriterResolver, getFileSystemFactory, getForwarderFactory, getForwardingFilter, getGlobalRequestHandlers, getIoServiceEventListener, getIoServiceFactory, getIoServiceFactoryFactory, getNioWorkers, getParentPropertyResolver, getPortForwardingEventListenerProxy, getProperties, getRandomFactory, getReservedSessionMessagesHandler, getScheduledExecutorService, getServiceFactories, getSessionDisconnectHandler, getSessionListenerProxy, getUnknownChannelReferenceHandler, getVersion, removeAttribute, removeChannelListener, removePortForwardingEventListener, removeSessionListener, removeSessionTimeout, resolveUnknownChannelReferenceHandler, setAgentFactory, setAttribute, setChannelFactories, setChannelStreamPacketWriterResolver, setFileSystemFactory, setForwarderFactory, setForwardingFilter, setGlobalRequestHandlers, setIoServiceEventListener, setIoServiceFactoryFactory, setNioWorkers, setParentPropertyResolver, setRandomFactory, setReservedSessionMessagesHandler, setScheduledExecutorService, setScheduledExecutorService, setServiceFactories, setSessionDisconnectHandler, setUnknownChannelReferenceHandler, setupSessionTimeout, stopSessionTimeoutListenergetCipherFactories, getCompressionFactories, getDelegate, getKexExtensionHandler, getKeyExchangeFactories, getMacFactories, getSignatureFactories, resolveEffectiveFactories, resolveEffectiveProvider, setCipherFactories, setCompressionFactories, setKexExtensionHandler, setKeyExchangeFactories, setMacFactories, setSignatureFactoriesdoCloseGracefully, doCloseImmediatelyaddCloseFutureListener, builder, close, getFutureLock, isClosed, isClosing, preClose, removeCloseFutureListenergetSimplifiedLoggerclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitgetAgentFactory, getAgentForwardingFilter, getChannelFactories, getFileSystemFactory, getForwarderFactory, getForwardingFilter, getGlobalRequestHandlers, getIoServiceFactory, getRandomFactory, getScheduledExecutorService, getServiceFactories, getTcpForwardingFilter, getVersion, getX11ForwardingFilter, resolveAttribute, resolveAttributegetCipherFactories, 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, setChannelStreamPacketWriterResolvergetUnknownChannelReferenceHandler, resolveUnknownChannelReferenceHandler, setUnknownChannelReferenceHandleraddPortForwardingEventListener, getPortForwardingEventListenerProxy, removePortForwardingEventListenergetIoServiceEventListener, setIoServiceEventListenerclearAttributes, computeAttributeIfAbsent, removeAttribute, setAttributeattributeKeys, getAttribute, getAttributesCount, ofAttributesMap, ofKeyValuePairdisableSessionHeartbeat, getSessionHeartbeatInterval, getSessionHeartbeatType, setSessionHeartbeatgetBoolean, getBooleanProperty, getCharset, getInteger, getIntProperty, getLong, getLongProperty, getObject, getParentPropertyResolver, getProperties, getString, getStringPropertyproviderHolderOfloaderHolderOfsetUserAuthFactoriesNamesgetUserAuthFactoriesNameList, getUserAuthFactoriesNames, setUserAuthFactoriesNameList, setUserAuthFactoriesNamesconnect, connect, connect, connect, connect, connect, connect, connect, connectaddCloseFutureListener, close, close, close, getMaxCloseWaitTime, isClosed, isClosing, isOpen, removeCloseFutureListenerpublic static final List<UserAuthFactory> DEFAULT_USER_AUTH_FACTORIES
public static final List<ServiceFactory> DEFAULT_SERVICE_FACTORIES
protected IoConnector connector
protected SessionFactory sessionFactory
protected UserInteraction userInteraction
protected List<UserAuthFactory> userAuthFactories
public SessionFactory getSessionFactory()
public void setSessionFactory(SessionFactory sessionFactory)
public ClientProxyConnector getClientProxyConnector()
getClientProxyConnector in interface ClientProxyConnectorHolderpublic void setClientProxyConnector(ClientProxyConnector proxyConnector)
setClientProxyConnector in interface ClientProxyConnectorHolderpublic ServerKeyVerifier getServerKeyVerifier()
ClientAuthenticationManagergetServerKeyVerifier in interface ClientAuthenticationManagerServerKeyVerifier to use - never nullpublic void setServerKeyVerifier(ServerKeyVerifier serverKeyVerifier)
setServerKeyVerifier in interface ClientAuthenticationManagerpublic HostConfigEntryResolver getHostConfigEntryResolver()
getHostConfigEntryResolver in interface ClientFactoryManagerHostConfigEntryResolver to use in order to resolve the
effective session parameters - never nullpublic void setHostConfigEntryResolver(HostConfigEntryResolver resolver)
setHostConfigEntryResolver in interface ClientFactoryManagerpublic FilePasswordProvider getFilePasswordProvider()
getFilePasswordProvider in interface FilePasswordProviderHolderpublic void setFilePasswordProvider(FilePasswordProvider provider)
setFilePasswordProvider in interface FilePasswordProviderManagerpublic ClientIdentityLoader getClientIdentityLoader()
getClientIdentityLoader in interface ClientIdentityLoaderHolderpublic void setClientIdentityLoader(ClientIdentityLoader loader)
setClientIdentityLoader in interface ClientIdentityLoaderManagerpublic UserInteraction getUserInteraction()
getUserInteraction in interface ClientAuthenticationManagerUserInteraction object to communicate with the user
(may be null to indicate that no such communication is allowed)public void setUserInteraction(UserInteraction userInteraction)
setUserInteraction in interface ClientAuthenticationManagerpublic List<UserAuthFactory> getUserAuthFactories()
getUserAuthFactories in interface UserAuthFactoriesManager<ClientSession,UserAuth,UserAuthFactory>public void setUserAuthFactories(List<UserAuthFactory> userAuthFactories)
setUserAuthFactories in interface UserAuthFactoriesManager<ClientSession,UserAuth,UserAuthFactory>public AuthenticationIdentitiesProvider getRegisteredIdentities()
getRegisteredIdentities in interface ClientAuthenticationManagerAuthenticationIdentitiesProvider to be used for attempting
password or public key authenticationpublic PasswordIdentityProvider getPasswordIdentityProvider()
ClientAuthenticationManagerPasswordIdentityProvider used to provide password
candidatesgetPasswordIdentityProvider in interface ClientAuthenticationManagerPasswordIdentityProvider instance - ignored if null
(i.e., no passwords available).ClientAuthenticationManager.addPasswordIdentity(String)public void setPasswordIdentityProvider(PasswordIdentityProvider provider)
setPasswordIdentityProvider in interface ClientAuthenticationManagerpublic void addPasswordIdentity(String password)
addPasswordIdentity in interface ClientAuthenticationManagerpassword - Password to be added - may not be null/empty.
Note: this password is in addition to whatever passwords
are available via the PasswordIdentityProvider (if any)public String removePasswordIdentity(String password)
removePasswordIdentity in interface ClientAuthenticationManagerpassword - The password to remove - ignored if null/emptyClientAuthenticationManager.addPasswordIdentity(String) - or null if no
match foundpublic void addPublicKeyIdentity(KeyPair kp)
addPublicKeyIdentity in interface ClientAuthenticationManagerkp - The KeyPair to add - may not be null
Note: this key is in addition to whatever keys
are available via the KeyIdentityProvider (if any)public KeyPair removePublicKeyIdentity(KeyPair kp)
removePublicKeyIdentity in interface ClientAuthenticationManagerkp - The KeyPair to remove - ignored if nullKeyPair - same one that was added via
ClientAuthenticationManager.addPublicKeyIdentity(KeyPair) - or null if no
match foundpublic KeyIdentityProvider getKeyIdentityProvider()
getKeyIdentityProvider in interface KeyIdentityProviderHolderpublic void setKeyIdentityProvider(KeyIdentityProvider keyIdentityProvider)
setKeyIdentityProvider in interface KeyIdentityProviderHolderprotected void checkConfig()
checkConfig in class AbstractFactoryManagerpublic boolean isStarted()
public void start()
started.public void stop()
public void open()
throws IOException
IOExceptionprotected Closeable getInnerCloseable()
getInnerCloseable in class AbstractInnerCloseablepublic ConnectFuture connect(String username, String host, int port, AttributeRepository context, SocketAddress localAddress) throws IOException
ClientSessionCreatorHostConfigEntry and connects to itconnect in interface ClientSessionCreatorusername - The intended usernamehost - The target host name/address - never null/emptyport - The target portcontext - An optional "context" to be attached to the established
session if successfully connectedlocalAddress - The local address to use - if null an
automatic ephemeral port and bind address is usedConnectFutureIOException - If failed to resolve the effective target or
connect to itpublic ConnectFuture connect(String username, SocketAddress targetAddress, AttributeRepository context, SocketAddress localAddress) throws IOException
ClientSessionCreatorHostConfigEntry and connects to itconnect in interface ClientSessionCreatorusername - The intended usernametargetAddress - The intended target SocketAddress - never null.
If this is an InetSocketAddress then the effective
HostConfigEntry is resolved and used.context - An optional "context" to be attached to the established
session if successfully connectedlocalAddress - The local address to use - if null an
automatic ephemeral port and bind address is usedConnectFutureIOException - If failed to resolve the effective target or connect to itpublic ConnectFuture connect(HostConfigEntry hostConfig, AttributeRepository context, SocketAddress localAddress) throws IOException
connect in interface ClientSessionCreatorhostConfig - The effective HostConfigEntry to connect to - never nullcontext - An optional "context" to be attached to the established
session if successfully connectedlocalAddress - The local address to use - if null an
automatic ephemeral port and bind address is usedConnectFutureIOException - If failed to create the connection futureprotected KeyIdentityProvider preloadClientIdentities(Collection<? extends NamedResource> locations) throws IOException
IOExceptionprotected ConnectFuture doConnect(String username, SocketAddress targetAddress, AttributeRepository context, SocketAddress localAddress, KeyIdentityProvider identities, boolean useDefaultIdentities) throws IOException
IOExceptionprotected SshFutureListener<IoConnectFuture> createConnectCompletionListener(ConnectFuture connectFuture, String username, SocketAddress address, KeyIdentityProvider identities, boolean useDefaultIdentities)
protected void onConnectOperationComplete(IoSession ioSession, ConnectFuture connectFuture, String username, SocketAddress address, KeyIdentityProvider identities, boolean useDefaultIdentities)
protected void setupDefaultSessionIdentities(ClientSession session, KeyIdentityProvider extraIdentities)
protected IoConnector createConnector()
protected SessionFactory createSessionFactory()
public static SimpleClient setUpDefaultSimpleClient()
SimpleClientSimpleClient wrapper. Note: when the wrapper
is closed the client is also stoppedsetUpDefaultClient(),
wrapAsSimpleClient(SshClient)public static SimpleClient wrapAsSimpleClient(SshClient client)
SshClient instance as a SimpleClientclient - The client instance - never null. Note:
client must be started before the simple client wrapper is used.SimpleClient wrapper. Note: when the
wrapper is closed the client is also stoppedpublic static SshClient setUpDefaultClient()
SshClient with default configurationspublic static <C extends SshClient> C setKeyPairProvider(C client, boolean strict, boolean supportedOnly, FilePasswordProvider provider, LinkOption... options) throws IOException, GeneralSecurityException
C - The generic client classclient - The SshClient to updatedstrict - If true then files that do not have the required
access rights are excluded from considerationsupportedOnly - If true then ignore identities that are not
supported internallyprovider - A FilePasswordProvider - may be null
if the loaded keys are guaranteed not to be encrypted. The argument
to FilePasswordProvider#getPassword is the path of the
file whose key is to be loadedoptions - The LinkOptions to apply when checking
for existencenull
KeyPairProvider was generatedIOException - If failed to access the file systemGeneralSecurityException - If failed to load the keyssetKeyPairProvider(SshClient, Path, boolean, boolean, FilePasswordProvider, LinkOption...)public static <C extends SshClient> C setKeyPairProvider(C client, Path dir, boolean strict, boolean supportedOnly, FilePasswordProvider provider, LinkOption... options) throws IOException, GeneralSecurityException
C - The generic client classclient - The SshClient to updateddir - The folder to scan for the built-in identitiesstrict - If true then files that do not have the required
access rights are excluded from considerationsupportedOnly - If true then ignore identities that are not
supported internallyprovider - A FilePasswordProvider - may be null
if the loaded keys are guaranteed not to be encrypted. The argument
to FilePasswordProvider#getPassword is the path of the
file whose key is to be loadedoptions - The LinkOptions to apply when checking
for existencenull
KeyIdentityProvider was generatedIOException - If failed to access the file systemGeneralSecurityException - If failed to load the keysClientIdentity.loadDefaultKeyPairProvider(Path, boolean, boolean, FilePasswordProvider, LinkOption...)Copyright © 2008–2020 The Apache Software Foundation. All rights reserved.