Readme.md

docker-java-transport-jsch

background

This module contains a docker-java transport, which supports ssh protocol. Since the PR #1440 was not accepted, the same code is released here as independant package. Also see #1130 for the original feature request.

The module uses a fork of jsch as java ssh implementation and okhttp as httpclient.

While native docker cli supports ssh connections since Host docker version 18.09 ¹, with different options it is possible to make it work for older versions. This library opens the ssh connection and then forwards the docker daemon socket to make it available to the http client.

The default ssh connection configuration relies on basic ssh config file in ~/.ssh/config.

usage

Its basically the same as described at getting_started from docker-java.

Once you have set up public key authentication and DOCKER_HOST you can

try(final JschDockerHttpClient httpClient=new JschDockerHttpClient.Builder()
        .connectTimeout(Duration.ofSeconds(20))
        .readTimeout(Duration.ofSeconds(20))
        .sslConfig(config.getSSLConfig())
        .dockerHost(config.getDockerHost())
        .build()
        ){
        ...
        }

connection variants

By setting flags in the builder, one can control how the connection is made.

• docker system dial-stdio (default)
• direct-streamlocal .useSocket() or .useSocket("/my/path/to/docker.socket")
• direct-tcpip .useTcp() or .useTcp(8765)
• socat .useSocat() or .useSocat("/my/path/to/docker.socket")

authentication variants

The SSH authentication relies on the Jsch mechanisms.

Configuration-guidance:

• Password:

   JschDockerHttpClient.Builder()
  ...
  .userInfo(new com.jcraft.jsch.UserInfo(){
  ...
  })
  .build();

• SSH-Agent:

  • *nix:
    • use java 16 and above or add junixsocket to the classpath

    IdentityRepository identityRepository = new AgentIdentityRepository(new SSHAgentConnector());
    new JschDockerHttpClient.Builder()
    ...
    .identityRepository(identityRepository)
    .build();

  • Windows with Pageant:
    • add dependency: put jna-platform into the classpath

    IdentityRepository identityRepository = new AgentIdentityRepository(new PageantConnector());
    new JschDockerHttpClient.Builder()
    ...
    .identityRepository(identityRepository)
    .build();

testing

reuse of integrations-tests from a docker-java by applying patches.

Always make sure, that you have set up a Docker Host available via ssh and that the host is set in DOCKER_HOST environment variable and that the ssh config to this host is setup in ~/ssh/config. (compare to what is done in CI environment in setup_ssh_config.sh).

For example in Github Codespaces as of 06/2023, the ssh port is 2222, not 22.

example maven command: DOCKER_HOST=ssh://junit-host mvn verify -Dit.test=JschDockerHttpClientIT

dockerd configurations

On the remote host, one can connect to the docker daemon in several ways:

• docker system dial-stdio
• unix:///var/run/docker.sock (default on linux) https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-socket-option
• npipe:////./pipe/docker_engine (default on Windows) https://docs.docker.com/docker-for-windows/faqs/#how-do-i-connect-to-the-remote-docker-engine-api
• unix:///var/run/docker.sock (default on macos) https://docs.docker.com/docker-for-mac/faqs/#how-do-i-connect-to-the-remote-docker-engine-api
• tcp 2375
• tcp with TLS

limitations

windows

Since forwarding socket of windows host is not supported, there is the workaround of starting socat to forward the docker socket to a local tcp port.

Compare OpenSSH tickets:

• PowerShell/Win32-OpenSSH#435
• PowerShell/openssh-portable#433

references

[1] docker ssh support docker/cli#1014