Add missing documentation for static IP options

Signed-off-by: Alessandro Boch <aboch@docker.com>

docs/reference/api/docker_remote_api_v1.22.md

@@ -3032,7 +3032,7 @@ Content-Type: application/json
 
 {
   "Container":"3613f73ba0e4",
-  "endpoint_config": {
+  "EndpointConfig": {
     "test_nw": {
         "IPv4Address":"172.24.56.89",
         "IPv6Address":"2001:db8::5689"

docs/reference/commandline/create.md

@@ -46,6 +46,8 @@ Creates a new container.
       -h, --hostname=""             Container host name
       --help                        Print usage
       -i, --interactive             Keep STDIN open even if not attached
+      --ip=""                       Container IPv4 address (e.g. 172.30.100.104)
+      --ip6=""                      Container IPv6 address (e.g. 2001:db8::33)
       --ipc=""                      IPC namespace to use
       --isolation=""                Container isolation technology
       --kernel-memory=""            Kernel memory limit

docs/reference/commandline/network_connect.md

@@ -15,7 +15,7 @@ parent = "smn_cli"
     Connects a container to a network
 
       --help             Print usage
-      --ip               IP Address
+      --ip               IPv4 Address
       --ip6              IPv6 Address
       --link=[]          Add a link to another container
 
@@ -46,11 +46,22 @@ $ docker network connect --link container1:c1 multi-host-network container2
 ```
 
 You can pause, restart, and stop containers that are connected to a network.
-Paused containers remain connected and a revealed by a `network inspect`. When
-the container is stopped, it does not appear on the network until you restart
-it. The container's IP address is not guaranteed to remain the same when a
-stopped container rejoins the network, unless you specified one when you run
-`docker network connect` command.
+Paused containers remain connected and can be revealed by a `network inspect`.
+When the container is stopped, it does not appear on the network until you restart
+it. If specified, the container's IP address(es) will be reapplied (if still available)
+when a stopped container rejoins the network. One way to guarantee that the container
+will be assigned the same IP addresses when it rejoins the network after a stop
+or a disconnect, is to specify the `--ip-range` when creating the network, and choose
+the static IP address(es) from outside the range. This will ensure that the IP address
+will not be given to other dynamic containers while this container is not on the network.
+
+```bash
+$ docker network create --subnet 172.20.0.0/16 --ip-range 172.20.240.0/20 multi-host-network
+```
+
+```bash
+$ docker network connect --ip 172.20.128.2 multi-host-network container2
+```
 
 To verify the container is connected, use the `docker network inspect` command. Use `docker network disconnect` to remove a container from the network.
 

docs/reference/commandline/run.md

@@ -46,6 +46,8 @@ parent = "smn_cli"
       -h, --hostname=""             Container host name
       --help                        Print usage
       -i, --interactive             Keep STDIN open even if not attached
+      --ip=""                       Container IPv4 address (e.g. 172.30.100.104)
+      --ip6=""                      Container IPv6 address (e.g. 2001:db8::33)
       --ipc=""                      IPC namespace to use
       --isolation=""                Container isolation technology
       --kernel-memory=""            Kernel memory limit
@@ -56,8 +58,6 @@ parent = "smn_cli"
       --log-opt=[]                  Log driver specific options
       -m, --memory=""               Memory limit
       --mac-address=""              Container MAC address (e.g. 92:d0:c6:0a:29:33)
-      --ip=""                       Container IPv4 address (e.g. 172.30.100.104)
-      --ip6=""                      Container IPv6 address (e.g. 2001:db8::33)
       --memory-reservation=""       Memory soft limit
       --memory-swap=""              A positive integer equal to memory plus swap. Specify -1 to enable unlimited swap.
       --memory-swappiness=""        Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.
@@ -330,6 +330,13 @@ This adds the `busybox` container to the `mynet` network.
 $ docker run -itd --net=my-multihost-network busybox
 ```
 
+You can also choose the IP addresses for the container with `--ip` and `--ip6`
+flags when you start the container on a user-defined network.
+
+```bash
+$ docker run -itd --net=my-multihost-network --ip=10.10.9.75 busybox
+```
+
 If you want to add a running container to a network use the `docker network connect` subcommand.
 
 You can connect multiple containers to the same network. Once connected, the

docs/reference/run.md

@@ -276,7 +276,7 @@ of the containers.
     --add-host=""    : Add a line to /etc/hosts (host:IP)
     --mac-address="" : Sets the container's Ethernet device's MAC address
     --ip=""          : Sets the container's Ethernet device's IPv4 address
-    --ip6=""          : Sets the container's Ethernet device's IPv6 address
+    --ip6=""         : Sets the container's Ethernet device's IPv6 address
 
 By default, all containers have networking enabled and they can make any
 outgoing connections. The operator can completely disable networking

man/docker-create.1.md

@@ -35,6 +35,8 @@ docker-create - Create a new container
 [**-h**|**--hostname**[=*HOSTNAME*]]
 [**--help**]
 [**-i**|**--interactive**]
+[**--ip**[=*IPv4-ADDRESS*]]
+[**--ip6**[=*IPv6-ADDRESS*]]
 [**--ipc**[=*IPC*]]
 [**--isolation**[=*default*]]
 [**--kernel-memory**[=*KERNEL-MEMORY*]]
@@ -174,6 +176,16 @@ two memory nodes.
 **-i**, **--interactive**=*true*|*false*
    Keep STDIN open even if not attached. The default is *false*.
 
+**--ip**=""
+   Sets the container's interface IPv4 address (e.g. 172.23.0.9)
+
+   It can only be used in conjunction with **--net** for user-defined networks
+
+**--ip6**=""
+   Sets the container's interface IPv6 address (e.g. 2001:db8::1b99)
+
+   It can only be used in conjunction with **--net** for user-defined networks
+
 **--ipc**=""
    Default is to create a private IPC namespace (POSIX SysV IPC) for the container
                                'container:<name|id>': reuses another container shared memory, semaphores and message queues

man/docker-network-connect.1.md

@@ -22,14 +22,26 @@ $ docker network connect multi-host-network container1
 You can also use the `docker run --net=<network-name>` option to start a container and immediately connect it to a network.
 
 ```bash
-$ docker run -itd --net=multi-host-network busybox
+$ docker run -itd --net=multi-host-network --ip 172.20.88.22 --ip6 2001:db8::8822 busybox
 ```
 
 You can pause, restart, and stop containers that are connected to a network.
-Paused containers remain connected and a revealed by a `network inspect`. When
-the container is stopped, it does not appear on the network until you restart
-it. The container's IP address is not guaranteed to remain the same when a
-stopped container rejoins the network.
+Paused containers remain connected and can be revealed by a `network inspect`.
+When the container is stopped, it does not appear on the network until you restart
+it. If specified, the container's IP address(es) will be reapplied (if still available)
+when a stopped container rejoins the network. One way to guarantee that the container
+will be assigned the same IP addresses when it rejoins the network after a stop
+or a disconnect, is to specify the `--ip-range` when creating the network, and choose
+the static IP address(es) from outside the range. This will ensure that the IP address
+will not be given to other dynamic containers while this container is not on the network.
+
+```bash
+$ docker network create --subnet 172.20.0.0/16 --ip-range 172.20.240.0/20 multi-host-network
+```
+
+```bash
+$ docker network connect --ip 172.20.128.2 multi-host-network container2
+```
 
 To verify the container is connected, use the `docker network inspect` command. Use `docker network disconnect` to remove a container from the network.
 

man/docker-run.1.md

@@ -37,6 +37,8 @@ docker-run - Run a command in a new container
 [**-h**|**--hostname**[=*HOSTNAME*]]
 [**--help**]
 [**-i**|**--interactive**]
+[**--ip**[=*IPv4-ADDRESS*]]
+[**--ip6**[=*IPv6-ADDRESS*]]
 [**--ipc**[=*IPC*]]
 [**--isolation**[=*default*]]
 [**--kernel-memory**[=*KERNEL-MEMORY*]]
@@ -274,6 +276,16 @@ redirection on the host system.
 
    When set to true, keep stdin open even if not attached. The default is false.
 
+**--ip**=""
+   Sets the container's interface IPv4 address (e.g. 172.23.0.9)
+
+   It can only be used in conjunction with **--net** for user-defined networks
+
+**--ip6**=""
+   Sets the container's interface IPv6 address (e.g. 2001:db8::1b99)
+
+   It can only be used in conjunction with **--net** for user-defined networks
+
 **--ipc**=""
    Default is to create a private IPC namespace (POSIX SysV IPC) for the container
                                'container:<name|id>': reuses another container shared memory, semaphores and message queues