What’s the Docker Swarm “–advertise-addr”?

by Brandon Mitchell | Wednesday, Aug 17, 2016 | Docker

If you saw the presentations at DockerCon 2016, or read any blogs about the new Docker swarm capabilities in 1.12 before the GA release, you likely saw something about running docker swarm init or perhaps something like docker swarm init --listen-addr $(docker-machine ip):2377. If you've tried this with the GA release, there's a good chance you saw an error asking you to provide the --advertise-addr:

$ docker swarm init
Error response from daemon: could not choose an IP address to advertise since this system has multiple addresses - specify one with --advertise-addr

What is the --advertise-addr?

To put it simply, the --advertise-addr is the address other nodes in the Docker swarm use to connect into your node. You need to provide an IP address of your host, or a network interface which Docker will use to lookup your IP address, and a port number which defaults to 2377:

$ docker swarm init --advertise-addr 192.168.2.23:2377
Error response from daemon: interface eth0 has no usable IPv4 or IPv6 address
bmitch@bmitch-asusr556l:~/data/vm/bmitch-swarm-00$ docker swarm init --advertise-addr wlan0:2377
Swarm initialized: current node (******) is now a manager.

To add a worker to this swarm, run the following command:
    docker swarm join \
    --token SWMTKN-1-****-*** \
    192.168.2.23:2377

To add a manager to this swarm, run the following command:
    docker swarm join \
    --token SWMTKN-1-****-*** \
    192.168.2.23:2377

(Note that actual tokens and names were censored out, you'll have long strings of characters for those.)

From the above, you can see the 192.168.2.23 IP in the provided swarm join commands that you run on other nodes, the very same that was provided as the --advertise-addr. You can also see this address if you request the current join-token:

$ docker swarm join-token worker
To add a worker to this swarm, run the following command:
    docker swarm join \
    --token SWMTKN-1-****-*** \
    192.168.2.23:2377

So then what's the --listen-addr?

The --listen-addr is the address that the swarm service listens on for incoming connections. In early releases, this same flag did double duty as the only way to set the advertised address, so you'll find old videos and instructions where this was used. With the new --advertise-addr option, it's safe to ignore these instructions and only pass the --advertise-addr. The default for --listen-addr is to listen on all interfaces on TCP port 2377 (0.0.0.0:2377):

$ sudo lsof -i TCP:2377
COMMAND   PID USER   FD   TYPE  DEVICE SIZE/OFF NODE NAME
dockerd 22042 root   19u  IPv6 6627039      0t0  TCP *:2377 (LISTEN)
dockerd 22042 root   26u  IPv4 6623776      0t0  TCP localhost:33489->localhost:2377 (ESTABLISHED)
dockerd 22042 root   27u  IPv6 6627610      0t0  TCP localhost:2377->localhost:33489 (ESTABLISHED)

$ sudo netstat -lntp | grep 2377
tcp6       0      0 :::2377                 :::*                    LISTEN      22042/dockerd

Why still provide the --listen-addr? Depending on your network architecture, you may want your swarm management interface only accessible on a management network that could be separate from a data and/or public network that are each attached to a physical server. There are other potential reasons to isolate the swarm listening address to a specific network interface, but unless you know you need this feature, you most likely don't need to change it from the default.