In this post, you will learn how to expose Docker engines API for remote docker command execution through REST APIs
What is Docker remote API?
The primary use of a Docker remote API is to connect with the Docker engine remotely. Let’s say you are running the docker host on a remote server and you want to connect to it from your laptop. For this scenario, you can use the remote API and connect to it using the REST API’s as the docker engine accepts REST requests.
One more use case is that let’s say you have an application and you want to get the details of the containers in docker host. For this, you can use the remote API feature.
Docker Courses You Might Like
- Docker Mastery: The Complete Toolset From a Docker Captain
- Learn DevOps: The Complete Kubernetes Course
Enable Docker Remote API
All the docker configurations are present in the file/lib/systemd/system/docker.service. In that file, there is an ExecStart parameter.
Open the file/lib/systemd/system/docker.service, search for ExecStart and add value as shown below.
ExecStart=/usr/bin/dockerd -H tcp://0.0.0.0:4243 -H unix:///var/run/docker.sock
The above command will bind the docker engine server to the Unix socket as well as TCP port 4243. “0.0.0.0” means docker-engine accepts connections from all IP addresses.
Note: Also, please add necessary firewall rules for your server to accept connection on port 4243
Now for all the changes to take place, you need to restart the daemon and Docker service. Execute the following commands to do that.
sudo systemctl daemon-reload sudo service docker restart
Now, remote API is enabled on your docker host. To test this, there are a few ways.
How do I access Docker API?
You can use curl command-line utility or REST APIs to access the Docker API. Both ways are explained below.
Test using curl
Get the IP address of your Docker host where you enabled remote API and execute the following command from any terminal which supports curl. You can test with the localhost as well.
Note: replace the IP with your Docker host IP or localhost as shown below.
curl http://localhost:4243/version curl http://35.225.233.5:4243/version
The above command will output all the images in your docker host in JSON format.
You Might Like: Docker Useful Hacks
Test using a REST client
You can test the API using REST client like Postman. If you use the following URL in your REST client, you will get the JSON output in a prettified manner as shown in the image below.
http://192.168.5.5:4243/images/json
In this tutorial, you learned to enable Docker remote API. For better security, you can use certificates with the REST requests. That we will cover in another detailed post If you face any issues with this setup, let us know in the comments section.
[…] 2. Jenkins master connects to the docker host using REST API’s. So we need to enable the remote API for our docker host. Follow enabling docker remote API tutorial. […]
Instead of changing the Docker daemon configuration and restarting it, you can run Sherpa, a container that opens up a port to the unix socket via reverse-proxy. Check it out: https://hub.docker.com/r/djenriquez/sherpa/
For Ubuntu 16.04 you must edit `/lib/systemd/system/docker.service` and not `/etc/init/docker.conf`
https://www.ivankrizsan.se/2016/05/18/enabling-docker-remote-api-on-ubuntu-16-04/
The following advice worked for me, from https://www.campalus.com/enable-remote-tcp-connections-to-docker-host-running-ubuntu-15-04/
In linux distros running systemd, like Ubuntu 15.04, adding -H tcp://0.0.0.0:2375 to /etc/default/docker does not have the effect it used to.
Instead, create a file called /etc/systemd/system/docker-tcp.socket to make docker available on a TCP socket on port 2375:
[Unit]
Description=Docker Socket for the API
[Socket]
ListenStream=2375
BindIPv6Only=both
Service=docker.service
[Install]
WantedBy=sockets.target
Then enable this new socket:
systemctl enable docker-tcp.socket
systemctl enable docker.socket
systemctl stop docker
systemctl start docker-tcp.socket
systemctl start docker
Test that it’s working:
docker -H tcp://127.0.0.1:2375 ps
Well enough for an isolated lab, perhaps, but it amazes me that EVERY article I have found on this piece of the puzzle fails to mention that ‘-H tcp://0.0.0.0:4243’, just opened up that port on EVERY IP bound to EVERY interface on the physical host, and that a more narrowly drawn IP in this url,, along with firewalls and signed certificates are likely warranted if that machine is publicly routable.
I spent much of a day, perhaps a bit more on a 233 line-of-code bash script:
enable_secure_docker_api.sh.
Two grep’s of the script should give some sense of how much work is left, and the documentation I relied on to craft this script, incomplete still, and probably somewhat specific to our use:
# grep ^function enable_secure_docker_api.sh
function set_defaults () {
function sanity_checks () {
function configure_server_certificate () {
function generate_ca_certificate () {
function validate_ca_certificate () {
function generate_server_certificates () {
function validate_server_certificate () {
function install_server_certificates () {
function configure_client_certificate () {
function generate_client_certificates () {
function validate_client_certificate () {
function configure_docker_daemon_for_tls () {
function restart_dockerd () {
function validate_dockerd_restart () {
function main () {
# grep http enable_secure_docker_api.sh
# https://docs.docker.com/engine/security/https/#create-a-ca-server-and-client-keys-with-openssl
# http://tech.paulcz.net/2016/01/secure-docker-with-tls/
# See .
# https://jamielinux.com/docs/openssl-certificate-authority/appendix/root-configuration-file.html
Folks who grok openssl and its usage better than I will likely spend less time with this than I did. But this was the piece which puts it all together.
function configure_docker_daemon_for_tls () {
# ExecStart=/usr/bin/dockerd -H fd:// -H tcp://172.17.0.1:4243
cfg_file=’/lib/systemd/system/docker.service’
dockerd=’/usr/bin/dockerd’
tlscacert=”–tlscacert=${server_api_certs}/ca.pem”
tlscert=”–tlscert=${server_api_certs}/server-cert.pem”
tlskey=”–tlskey=${server_api_certs}/server-key.pem”
local_socket=’-H fd://’
tcp_connection=”-H tcp://172.17.0.1:${API_PORT}”
exec_start=”ExecStart=${dockerd} –tlsverify ${tlscacert} ${tlscert} ${tlskey} ${local_socket} ${tcp_connection}”
if [ ! $(grep “$exec_start” -q $cfg_file) ];
then sed -i” “s,ExecStart=.*$,$exec_start,” $cfg_file
fi
}
This is the file which will get read with `service docker restart`.
Did you mean to say, edit /etc/init.d/docker.conf ??