Add --userland-proxy daemon flag

The `--userland-proxy` daemon flag makes it possible to rely on hairpin
NAT and additional iptables routes instead of userland proxy for port
publishing and inter-container communication.

Usage of the userland proxy remains the default as hairpin NAT is
unsupported by older kernels.

Signed-off-by: Arnaud Porterie <arnaud.porterie@docker.com>
Upstream-commit: f42348e18f73d1d775d77ac75bc96466aae56d7c
Component: engine

components/engine/docs/man/docker.1.md

@@ -53,6 +53,9 @@ To see the man page for a command run **man docker <command>**.
 **-e**, **--exec-driver**=""
   Force Docker to use specific exec driver. Default is `native`.
 
+**--exec-opt**=[]
+  Set exec driver options. See EXEC DRIVER OPTIONS.
+
 **--fixed-cidr**=""
   IPv4 subnet for fixed IPs (e.g., 10.20.0.0/16); this subnet must be nested in the bridge subnet (which is defined by \-b or \-\-bip)
 
@@ -111,6 +114,9 @@ unix://[/path/to/socket] to use.
 **-s**, **--storage-driver**=""
   Force the Docker runtime to use a specific storage driver.
 
+**--selinux-enabled**=*true*|*false*
+  Enable selinux support. Default is false. SELinux does not presently support the BTRFS storage driver.
+
 **--storage-opt**=[]
   Set storage driver options. See STORAGE DRIVER OPTIONS.
 
@@ -121,15 +127,12 @@ unix://[/path/to/socket] to use.
   Use TLS and verify the remote (daemon: verify client, client: verify daemon).
   Default is false.
 
+**--userland-proxy**=*true*|*false*
+    Rely on a userland proxy implementation for inter-container and outside-to-container loopback communications. Default is true.
+
 **-v**, **--version**=*true*|*false*
   Print version information and quit. Default is false.
 
-**--exec-opt**=[]
-  Set exec driver options. See EXEC DRIVER OPTIONS.
-
-**--selinux-enabled**=*true*|*false*
-  Enable selinux support. Default is false. SELinux does not presently support the BTRFS storage driver.
-
 # COMMANDS
 **attach**
   Attach to a running container

components/engine/docs/sources/articles/networking.md

@@ -93,6 +93,9 @@ server when it starts up, and cannot be changed once it is running:
  *  `--mtu=BYTES` — see
     [Customizing docker0](#docker0)
 
+ *  `--userland-proxy=true|false` — see
+    [Binding container ports](#binding-ports)
+
 There are two networking options that can be supplied either at startup
 or when `docker run` is invoked.  When provided at startup, set the
 default value that `docker run` will later use if the options are not
@@ -399,7 +402,7 @@ machine that the Docker server creates when it starts:
     ...
     Chain POSTROUTING (policy ACCEPT)
     target     prot opt source               destination
-    MASQUERADE  all  --  172.17.0.0/16       !172.17.0.0/16
+    MASQUERADE  all  --  172.17.0.0/16       0.0.0.0/0
     ...
 
 But if you want containers to accept incoming connections, you will need
@@ -452,6 +455,21 @@ address, you can edit your system-wide Docker server settings and add the
 option `--ip=IP_ADDRESS`.  Remember to restart your Docker server after
 editing this setting.
 
+> **Note**:
+> With hairpin NAT enabled (`--userland-proxy=false`), containers port exposure
+> is achieved purely through iptables rules, and no attempt to bind the exposed
+> port is ever made. This means that nothing prevents shadowing a previously
+> listening service outside of Docker through exposing the same port for a
+> container. In such conflicting situation, Docker created iptables rules will
+> take precedence and route to the container.
+
+The `--userland-proxy` parameter, true by default, provides a userland
+implementation for inter-container and outside-to-container communication. When
+disabled, Docker uses both an additional `MASQUERADE` iptable rule and the
+`net.ipv4.route_localnet` kernel parameter which allow the host machine to
+connect to a local container exposed port through the commonly used loopback
+address: this alternative is preferred for performance reason.
+
 Again, this topic is covered without all of these low-level networking
 details in the [Docker User Guide](/userguide/dockerlinks/) document if you
 would like to use that as your port redirection reference instead.

components/engine/docs/sources/reference/commandline/cli.md

@@ -149,6 +149,7 @@ expect an integer, and they can only be specified once.
       --default-gateway-v6=""                Container default gateway IPv6 address
       --dns=[]                               DNS server to use
       --dns-search=[]                        DNS search domains to use
+      --default-ulimit=[]                    Set default ulimit settings for containers
       -e, --exec-driver="native"             Exec driver to use
       --fixed-cidr=""                        IPv4 subnet for fixed IPs
       --fixed-cidr-v6=""                     IPv6 subnet for fixed IPs
@@ -177,8 +178,8 @@ expect an integer, and they can only be specified once.
       --tlscert="~/.docker/cert.pem"         Path to TLS certificate file
       --tlskey="~/.docker/key.pem"           Path to TLS key file
       --tlsverify=false                      Use TLS and verify the remote
+      --userland-proxy=true                  Use userland proxy for loopback traffic
       -v, --version=false                    Print version information and quit
-      --default-ulimit=[]                    Set default ulimit settings for containers.
 
 Options with [] may be specified multiple times.