diff options
authorBIN HU <>2018-10-13 17:36:22 -0700
committerBin Hu <>2018-10-14 00:46:00 +0000
commit848b80c1882a33b949aee2565cfa34fe13795ef3 (patch)
parentb694e061d19bf856f9e8b3df10e6e6ed22d0cdc1 (diff)
Docker IPv6 NAT
Change-Id: I1abf48d46feb721cde0dda0326ece36f14e88214 Signed-off-by: BIN HU <> (cherry picked from commit 55527a22b102703d66efda61e44054af26ff16ed)
-rw-r--r--docs/release/userguide/images/global-unicast.jpgbin0 -> 7793 bytes
-rw-r--r--docs/release/userguide/images/link-local.jpgbin0 -> 8675 bytes
-rw-r--r--docs/release/userguide/images/unicast-scope.jpgbin0 -> 18425 bytes
-rw-r--r--docs/release/userguide/images/unique-local.jpgbin0 -> 12513 bytes
6 files changed, 133 insertions, 1 deletions
diff --git a/docs/release/userguide/docker-ipv6-nat.rst b/docs/release/userguide/docker-ipv6-nat.rst
new file mode 100644
index 0000000..314e4ec
--- /dev/null
+++ b/docs/release/userguide/docker-ipv6-nat.rst
@@ -0,0 +1,130 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. (c) Prakash Ramchandran
+Docker IPv6 NAT
+What is the Issue with Using IPv6 with Containers?
+Initially Docker was not created with IPv6 in mind. It was added later. As a
+result, there are still several unresolved issues as to how IPv6 should be used
+in a containerized world.
+Currently, you can let Docker give each container an IPv6 address from your
+(public) pool, but this has disadvantages (Refer to [1]_):
+* Giving each container a publicly routable address means all ports (even
+ unexposed / unpublished ports) are suddenly reachable by everyone, if no
+ additional filtering is done.
+* By default, each container gets a random IPv6 address, making it impossible
+ do DNS properly. An alternative is to assign a specific IPv6 address to each
+ container, but it is still an administrative hassle.
+* Published ports won't work on IPv6, unless you have the userland proxy
+ enabled (which, for now, is enabled by default in Docker)
+* The userland proxy, however, seems to be on its way out and has various
+ issues, such as:
+ * It can use a lot of RAM.
+ * Source IP addresses are rewritten, making it completely unusable for many
+ purposes, e.g. mail servers.
+IPv6 for Docker can (depending on your setup) be pretty much unusable and
+completely inconsistent with the way how IPv4 works. Docker images are mostly
+designed with IPv4 NAT in mind. NAT provides a layer of security allowing only
+published ports through. Letting container link to user-defined networks
+provide inter-container communication. This does not go hand in hand with the
+way Docker IPv6 works, requiring image maintainers to rethink/adapt their
+images with IPv6 in mind.
+Why not IPv6 with NAT?
+So why not try resolve above issues by managing ``ip6tables`` to setup IPv6 NAT
+for your containers, like how it is done by the Docker daemon for IPv4. This
+requires a locally reserved address like we do for private IP in IPv4. These
+are called in IPv6 as local unicast Ipv6 address. Let’s first understand IPv6
+addressing scheme.
+We note that there are 3 types of IPv6 addresses, and all use last or least
+significant 64 bits as Interface ID derived by splitting 48-bit MAC address
+into 24 bits + 24 bits and insert an FE00 hexadecimal number in between those
+two and inverting the most significant bit to create an equivalent 64-bit MAC
+called EUI-64 bit. Refer to [2]_ for details.
+**1. Global Unicast Address**
+This is equivalent to IPv4’s public address with always 001 as Most
+Significant bits of Global Routing Prefix. Subnets are 16 opposed to 8 bits
+in IPv4.
+.. figure:: images/global-unicast.jpg
+ :name: docker-ipv6-nat-figure1
+ :width: 100%
+**2. Link-Local Address**
+Link-local addresses are used for communication among IPv6 hosts on a link
+(broadcast segment) only. These addresses are not routable. This address always
+starts with FE80. These are used for generating IPv6 addresses and 48 bits
+following FE80 are always set to 0. Interface ID is usual EUI-64 generated from
+MAC address on the NIC.
+.. figure:: images/link-local.jpg
+ :name: docker-ipv6-nat-figure2
+ :width: 100%
+**3. Unique-Local Address**
+This type of IPv6 address is globally unique & used only in site local
+communication. The second half of this address contain Interface ID and the
+first half is divided among Prefix, Local Bit, Global ID and Subnet ID.
+.. figure:: images/unique-local.jpg
+ :name: docker-ipv6-nat-figure3
+ :width: 100%
+Prefix is always set to 1111 110. L bit, is set to 1 if the address is locally
+assigned. So far, the meaning of L bit to 0 is not defined. Therefore, Unique
+Local IPv6 address always starts with ‘FD’.
+IPv6 addresses of all types are assigned to interfaces, not nodes (hosts). An
+IPv6 unicast address refers to a single interface. Since each interface belongs
+to a single node (host), any of that node's interfaces' unicast addresses may
+be used as an identifier for the node(host). For IPv6 NAT we prefer site scope
+to be within site scope using unique local address, so that they remain private
+within the organization.
+.. figure:: images/unicast-scope.jpg
+ :name: docker-ipv6-nat-figure4
+ :width: 100%
+ Figure 1: Scope of IPv6 Unicast Addresses
+Based on the IPv6 scope now question arises as what is needed to be mapped to
+what? Is it IPv6 to IPv4 or IPv6 to IPv6 with post? Thus, we land up with are
+we talking NAT64 with dual stack or just NAT66. Is it a standard that is agreed
+upon in IETF RFCs? Dwelling into questions bring us back to should we
+complicate life with another docker-ipv6nat?
+The conclusion is simple: it is not worth it and it is highly recommended that
+you go through the blog listed below [3]_.
+As IPv6 Project team in OPNFV, we recommend that IPv6 NAT is not worth the
+effort and should be discouraged. As part of our conclusion, we recommend that
+please do not use IPv6 NAT for containers for any NFV use cases.
+.. [1]
+.. [2]
+.. [3]
diff --git a/docs/release/userguide/images/global-unicast.jpg b/docs/release/userguide/images/global-unicast.jpg
new file mode 100644
index 0000000..2eedf73
--- /dev/null
+++ b/docs/release/userguide/images/global-unicast.jpg
Binary files differ
diff --git a/docs/release/userguide/images/link-local.jpg b/docs/release/userguide/images/link-local.jpg
new file mode 100644
index 0000000..e0f00aa
--- /dev/null
+++ b/docs/release/userguide/images/link-local.jpg
Binary files differ
diff --git a/docs/release/userguide/images/unicast-scope.jpg b/docs/release/userguide/images/unicast-scope.jpg
new file mode 100644
index 0000000..e518e68
--- /dev/null
+++ b/docs/release/userguide/images/unicast-scope.jpg
Binary files differ
diff --git a/docs/release/userguide/images/unique-local.jpg b/docs/release/userguide/images/unique-local.jpg
new file mode 100644
index 0000000..351f081
--- /dev/null
+++ b/docs/release/userguide/images/unique-local.jpg
Binary files differ
diff --git a/docs/release/userguide/index.rst b/docs/release/userguide/index.rst
index f4012a7..e215d40 100644
--- a/docs/release/userguide/index.rst
+++ b/docs/release/userguide/index.rst
@@ -28,7 +28,8 @@ The IPv6 Setup in Container Networking serves as feature specific user guides
and references when as a user you may want to explore IPv6 in Docker container
environment. The use of NDP Proxying is explored to connect IPv6-only
containers to external network. The Docker IPv6 simple cluster topology is
-studied with two Hosts, each with 2 Docker containers.
+studied with two Hosts, each with 2 Docker containers. Docker IPv6 NAT topic
+is also explored.
For more information, please find `Neutron's IPv6 document for Queens Release
@@ -42,3 +43,4 @@ For more information, please find `Neutron's IPv6 document for Queens Release
+ ./docker-ipv6-nat.rst