Document new DOCKER-USER iptables chain (docker#3554)

Misty Stanley-Jones · Misty Stanley-Jones · commit 7df267c9e39b · 2017-06-28T08:31:29.000-07:00
* Document new DOCKER-USER iptables chain

* Rewording
diff --git a/engine/userguide/networking/index.md b/engine/userguide/networking/index.md
@@ -1,6 +1,6 @@
 ---
 description: How do we connect docker containers within and across hosts ?
-keywords: Examples, Usage, network, docker, documentation, user guide, multihost, cluster
+keywords: network, networking, iptables, user-defined networks, bridge, firewall, ports
 redirect_from:
 - /engine/userguide/networking/dockernetworks/
 - /articles/networking/
@@ -12,6 +12,9 @@ including the type of networks created by default and how to create your own
 user-defined networks. It also describes the resources required to create
 networks on a single host or across a cluster of hosts.
 
+For details about how Docker interacts with `iptables` on Linux hosts, see
+[Docker and `iptables`](#docker-and-iptables).
+
 ## Default Networks
 
 When you install Docker, it creates three networks automatically. You can list
@@ -550,6 +553,34 @@ in default `bridge` network and the
 [linking containers in user-defined networks](work-with-networks.md#linking-containers-in-user-defined-networks)
 for links functionality in user-defined networks.
 
+## Docker and iptables
+
+Linux hosts use a kernel module called `iptables` to manage access to network
+devices, including routing, port forwarding, network address translation (NAT),
+and other concerns. Docker modifies `iptables` rules when you start or stop
+containers which publish ports, when you create or modify networks or attach
+containers to them, or for other network-related operations.
+
+Full discussion of `iptables` is out of scope for this topic. To see which
+`iptables` rules are in effect at any time, you can use `iptables -L`. Multiple
+tables exist, and you can list a specific table, such as `nat`, `prerouting`, or
+`postrouting`, using a command such as `iptables -t nat -L`. For full
+documentation about `iptables`, see
+[netflilter/iptables](https://netfilter.org/documentation/){: target="_blank" class="_" }.
+
+Typically, `iptables` rules are created by an initialization script or a daemon
+process such as `firewalld`. The rules do not persist across a system reboot, so
+the script or utility must run when the system boots, typically at run-level 3
+or directly after the network is initialized. Consult the networking
+documentation for your Linux distribution for suggestions about the appropriate
+way to make `iptables` rules persistent.
+
+Docker dynamically manages `iptables` rules for the daemon, as well as your
+containers, services, and networks. In Docker 17.06 and higher, you can add
+rules to a new table called `DOCKER-USER`, and these rules will be loaded before
+any rules Docker creates automatically. This can be useful if you need to
+pre-populate `iptables` rules that need to be in place before Docker runs.
+
 ## Related information
 
 - [Work with network commands](work-with-networks.md)
