0 0 Share PDF

How do I change the docker gwbridge address?

Article ID: KB000299


The docker_gwbridge interface provides default gateway functionality for all containers and tasks which use a multi-host swarm overlay network. It is created on each Docker host when it joins a swarm cluster.

If the IP address of the interface docker_gwbridge conflicts with an address on your network, it can be changed on a host-by-host basis.


  • Docker swarm mode cluster


Warning: Modifying an existing member of a cluster involves stopping all swarm overlay attached containers on the host.

To alter the subnet of docker_gwbridge, stop any classic containers attached to overlay networks, drain the node or leave the swarm, remove the network, re-add it with the desired subnet, and restart classic containers as follows (must be done on a host-by-host basis):

  1. Save a list of any overlay-attached classic containers. This will be used to stop and start these containers before and after network reconfiguration.

      docker network inspect docker_gwbridge --format \
        '{{range $k, $v := .Containers}}{{$k}}{{printf "\n"}}{{end}}' |
        xargs -I{} docker container ls -f is-task=false \
          -f id={} --format {{.Names}} |
        tee /dev/stderr )
  2. Stop any classic containers using docker_gwbridge. Classic containers will not be rescheduled to other nodes.

    docker container stop ${gwbridge_containers}
  3. Stop swarm tasks and disable swarm multi-host overlay networking on the node by draining the node. Swarm service tasks will be rescheduled to other nodes if their constraints and resource limits allow. Drain the node using the UCP WebUI, or an administrative UCP client certificate bundle:

    docker node update --availabilty drain worker-1>
  4. Disconnect the ingress-sbox endpoint from the docker_gwbridge network, then remove the network itself:

    docker network disconnect -f docker_gwbridge gateway_ingress-sbox 1>/dev/null 2>&1
    docker network rm docker_gwbridge
  5. Engine versions 18.09 and later enable local IPAM configuration via the default-address-pools daemon config. On Engine 18.09 and later, edit or create /etc/docker/daemon.json, populating default-address-pools with the list of preferred pools and network sizes. If this file is empty or does not exist prior to editing, it should look like this when finished:

      "default-address-pools": [
        { "base": "", "size": 20 }

    Then restart the engine to pick up the new settings:

    sudo systemctl restart docker

    On Engine versions 18.03 and earlier where default-address-pools is not available, recreate the docker_gwbridge with default inter-container communication settings and interface name as well as the desired subnet configuration:

    docker network create  \
      -o com.docker.network.bridge.enable_icc=false \
      -o com.docker.network.bridge.name=docker_gwbridge \
      --subnet \
      --gateway \
  6. (Optional) Confirm the settings on docker_gwbridge:

    docker network inspect docker_gwbridge \
      --format '{{range $k, $v := index .IPAM.Config 0}}{{.| printf "%s: %s " $k}}{{end}}'
  7. Re-enable swarm multi-host overlay by setting node availability to active. Use the UCP WebUI or an administrative client certificate bundle to set its availability back to active

    docker node update --availability active worker-1>
  8. Restart any overlay-attached classic containers:

    docker container start ${gwbridge_containers}

What's Next

  • Plan your UCP installation naming and address considerations at docs.docker.com