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();
}
}
Note: the idea is to have one 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, statelogABORT_ON_INVALID_CERTIFICATE, CLIENT_IDENTIFICATION, DEFAULT_ABORT_ON_INVALID_CERTIFICATE, 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, setSessionHeartbeat, 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.