Rename `--net` to `--network`

Add a `--network` flag which replaces `--net` without deprecating it
yet. The `--net` flag remains hidden and supported.

Add a `--network-alias` flag which replaces `--net-alias` without deprecating
it yet. The `--net-alias` flag remains hidden and supported.

Signed-off-by: Arnaud Porterie (icecrime) <arnaud.porterie@docker.com>
(cherry picked from commit c0c7d5e71586ec8e4d54aef9e061f061e9223cc4)
Signed-off-by: Tibor Vass <tibor@docker.com>

docs/examples/apt-cacher-ng.md

@@ -93,8 +93,8 @@ too.
 **Option 5** creates a custom network of APT proxy server and Debian-based containers:
 
     $ docker network create mynetwork
-    $ docker run -d -p 3142:3142 --net=mynetwork --name test_apt_cacher_ng eg_apt_cacher_ng
-    $ docker run --rm -it --net=mynetwork -e http_proxy=http://test_apt_cacher_ng:3142/ debian bash
+    $ docker run -d -p 3142:3142 --network=mynetwork --name test_apt_cacher_ng eg_apt_cacher_ng
+    $ docker run --rm -it --network=mynetwork -e http_proxy=http://test_apt_cacher_ng:3142/ debian bash
 
 Apt-cacher-ng has some tools that allow you to manage the repository,
 and they can be used by leveraging the `VOLUME`

docs/extend/plugins_network.md

@@ -46,7 +46,7 @@ Some network driver plugins are listed in [plugins](plugins.md)
 The `mynet` network is now owned by `weave`, so subsequent commands
 referring to that network will be sent to the plugin,
 
-    $ docker run --net=mynet busybox top
+    $ docker run --network=mynet busybox top
 
 
 ## Write a network plugin

docs/reference/commandline/create.md

@@ -72,13 +72,13 @@ Options:
       --memory-swap string          Swap limit equal to memory plus swap: '-1' to enable unlimited swap
       --memory-swappiness int       Tune container memory swappiness (0 to 100) (default -1)
       --name string                 Assign a name to the container
-      --net string                  Connect a container to a network (default "default")
+      --network-alias value         Add network-scoped alias for the container (default [])
+      --network string              Connect a container to a network (default "default")
                                     'bridge': create a network stack on the default Docker bridge
                                     'none': no networking
                                     'container:<name|id>': reuse another container's network stack
                                     'host': use the Docker host network stack
                                     '<network-name>|<network-id>': connect to a user-defined network
-      --net-alias value             Add network-scoped alias for the container (default [])
       --no-healthcheck              Disable any container-specified HEALTHCHECK
       --oom-kill-disable            Disable OOM Killer
       --oom-score-adj int           Tune host's OOM preferences (-1000 to 1000)

docs/reference/commandline/dockerd.md

@@ -921,7 +921,7 @@ This option will completely disable user namespace mapping for the container's u
 The following standard Docker features are currently incompatible when
 running a Docker daemon with user namespaces enabled:
 
- - sharing PID or NET namespaces with the host (`--pid=host` or `--net=host`)
+ - sharing PID or NET namespaces with the host (`--pid=host` or `--network=host`)
  - A `--read-only` container filesystem (this is a Linux kernel restriction against remounting with modified flags of a currently mounted filesystem when inside a user namespace)
  - external (volume or graph) drivers which are unaware/incapable of using daemon user mappings
  - Using `--privileged` mode flag on `docker run` (unless also specifying `--userns=host`)

docs/reference/commandline/network_connect.md

@@ -32,10 +32,10 @@ the same network.
 $ 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.
+You can also use the `docker run --network=<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 --network=multi-host-network busybox
 ```
 
 You can specify the IP address you want to be assigned to the container's interface.

docs/reference/commandline/network_create.md

@@ -82,11 +82,11 @@ name conflicts.
 
 ## Connect containers
 
-When you start a container, use the `--net` flag to connect it to a network.
+When you start a container, use the `--network` flag to connect it to a network.
 This example adds the `busybox` container to the `mynet` network:
 
 ```bash
-$ docker run -itd --net=mynet busybox
+$ docker run -itd --network=mynet busybox
 ```
 
 If you want to add a container to a network after the container is already

docs/reference/commandline/run.md

@@ -78,13 +78,13 @@ Options:
       --memory-swap string          Swap limit equal to memory plus swap: '-1' to enable unlimited swap
       --memory-swappiness int       Tune container memory swappiness (0 to 100) (default -1).
       --name string                 Assign a name to the container
-      --net string                  Connect a container to a network (default "default")
+      --network-alias value         Add network-scoped alias for the container (default [])
+      --network string              Connect a container to a network
                                     'bridge': create a network stack on the default Docker bridge
                                     'none': no networking
                                     'container:<name|id>': reuse another container's network stack
                                     'host': use the Docker host network stack
                                     '<network-name>|<network-id>': connect to a user-defined network
-      --net-alias value             Add network-scoped alias for the container (default [])
       --no-healthcheck              Disable any container-specified HEALTHCHECK
       --oom-kill-disable            Disable OOM Killer
       --oom-score-adj int           Tune host's OOM preferences (-1000 to 1000)
@@ -360,20 +360,20 @@ For additional information on working with labels, see [*Labels - custom
 metadata in Docker*](../../userguide/labels-custom-metadata.md) in the Docker User
 Guide.
 
-### Connect a container to a network (--net)
+### Connect a container to a network (--network)
 
-When you start a container use the `--net` flag to connect it to a network.
+When you start a container use the `--network` flag to connect it to a network.
 This adds the `busybox` container to the `my-net` network.
 
 ```bash
-$ docker run -itd --net=my-net busybox
+$ docker run -itd --network=my-net 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-net --ip=10.10.9.75 busybox
+$ docker run -itd --network=my-net --ip=10.10.9.75 busybox
 ```
 
 If you want to add a running container to a network use the `docker network connect` subcommand.
@@ -673,4 +673,4 @@ network namespace, run this command:
   `Network Namespace`:
       Sysctls beginning with net.*
 
-  If you use the `--net=host` option using these sysctls will not be allowed.
+  If you use the `--network=host` option using these sysctls will not be allowed.

docs/reference/run.md

@@ -259,7 +259,7 @@ $ strace -p 1
 
 The UTS namespace is for setting the hostname and the domain that is visible
 to running processes in that namespace.  By default, all containers, including
-those with `--net=host`, have their own UTS namespace.  The `host` setting will
+those with `--network=host`, have their own UTS namespace.  The `host` setting will
 result in the container using the same UTS namespace as the host.  Note that
 `--hostname` is invalid in `host` UTS mode.
 
@@ -289,13 +289,13 @@ of the containers.
 ## Network settings
 
     --dns=[]           : Set custom dns servers for the container
-    --net="bridge"     : Connect a container to a network
+    --network="bridge" : Connect a container to a network
                           'bridge': create a network stack on the default Docker bridge
                           'none': no networking
                           'container:<name|id>': reuse another container's network stack
                           'host': use the Docker host network stack
                           '<network-name>|<network-id>': connect to a user-defined network
-    --net-alias=[]     : Add network-scoped alias for the container
+    --network-alias=[] : Add network-scoped alias for the container
     --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
@@ -304,7 +304,7 @@ of the containers.
 
 By default, all containers have networking enabled and they can make any
 outgoing connections. The operator can completely disable networking
-with `docker run --net none` which disables all incoming and outgoing
+with `docker run --network none` which disables all incoming and outgoing
 networking. In cases like this, you would perform I/O through files or
 `STDIN` and `STDOUT` only.
 
@@ -404,14 +404,14 @@ docker daemon. It is recommended to run containers in this mode when their
 networking performance is critical, for example, a production Load Balancer
 or a High Performance Web Server.
 
-> **Note**: `--net="host"` gives the container full access to local system
+> **Note**: `--network="host"` gives the container full access to local system
 > services such as D-bus and is therefore considered insecure.
 
 #### Network: container
 
 With the network set to `container` a container will share the
 network stack of another container.  The other container's name must be
-provided in the format of `--net container:<name|id>`. Note that `--add-host`
+provided in the format of `--network container:<name|id>`. Note that `--add-host`
 `--hostname` `--dns` `--dns-search` `--dns-opt` and `--mac-address` are
 invalid in `container` netmode, and `--publish` `--publish-all` `--expose` are
 also invalid in `container` netmode.
@@ -422,7 +422,7 @@ running the `redis-cli` command and connecting to the Redis server over the
 
     $ docker run -d --name redis example/redis --bind 127.0.0.1
     $ # use the redis container's network stack to access localhost
-    $ docker run --rm -it --net container:redis example/redis-cli -h 127.0.0.1
+    $ docker run --rm -it --network container:redis example/redis-cli -h 127.0.0.1
 
 #### User-defined network
 
@@ -440,7 +440,7 @@ driver and running a container in the created network
 
 ```
 $ docker network create -d bridge my-net
-$ docker run --net=my-net -itd --name=container3 busybox
+$ docker run --network=my-net -itd --name=container3 busybox
 ```
 
 ### Managing /etc/hosts

docs/tutorials/networkingcontainers.md

@@ -198,9 +198,9 @@ To build web applications that act in concert but do so securely, create a
 network. Networks, by definition, provide complete isolation for containers. You
 can add containers to a network when you first run a container.
 
-Launch a container running a PostgreSQL database and pass it the `--net=my-bridge-network` flag to connect it to your new network:
+Launch a container running a PostgreSQL database and pass it the `--network=my-bridge-network` flag to connect it to your new network:
 
-    $ docker run -d --net=my-bridge-network --name db training/postgres
+    $ docker run -d --network=my-bridge-network --name db training/postgres
 
 If you inspect your `my-bridge-network` you'll see it has a container attached.
 You can also inspect your container to see where it is connected:

docs/userguide/networking/configure-dns.md

@@ -48,13 +48,13 @@ Various container options that affect container domain name services.
   <tr>
     <td>
     <p>
-    <code>--net-alias=ALIAS</code>
+    <code>--network-alias=ALIAS</code>
     </p>
     </td>
     <td>
     <p>
      In addition to <code>--name</code> as described above, a container is discovered by one or more 
-     of its configured <code>--net-alias</code> (or <code>--alias</code> in <code>docker network connect</code> command)
+     of its configured <code>--network-alias</code> (or <code>--alias</code> in <code>docker network connect</code> command)
      within the user-defined network. The embedded DNS server maintains the mapping between
      all of the container aliases and its IP address on a specific user-defined network.
      A container can have different aliases in different networks by using the <code>--alias</code>

docs/userguide/networking/default_network/container-communication.md

@@ -42,7 +42,7 @@ or to turn it on manually:
 ```
 
 > **Note**: this setting does not affect containers that use the host
-> network stack (`--net=host`).
+> network stack (`--network=host`).
 
 Many using Docker will want `ip_forward` to be on, to at least make
 communication _possible_ between containers and the wider world. May also be

docs/userguide/networking/dockernetworks.md

@@ -37,12 +37,12 @@ cf03ee007fb4        host                host
 ```
 
 Historically, these three networks are part of Docker's implementation. When
-you run a container you can use the `--net` flag to specify which network you
+you run a container you can use the `--network` flag to specify which network you
 want to run a container on. These three networks are still available to you.
 
 The `bridge` network represents the `docker0` network present in all Docker
 installations. Unless you specify otherwise with the `docker run
---net=<NETWORK>` option, the Docker daemon connects containers to this network
+--network=<NETWORK>` option, the Docker daemon connects containers to this network
 by default. You can see this bridge as part of a host's network stack by using
 the `ifconfig` command on the host.
 
@@ -352,10 +352,10 @@ c5ee82f76de3        isolated_nw         bridge
 
 ```
 
-After you create the network, you can launch containers on it using  the `docker run --net=<NETWORK>` option.
+After you create the network, you can launch containers on it using  the `docker run --network=<NETWORK>` option.
 
 ```
-$ docker run --net=isolated_nw -itd --name=container3 busybox
+$ docker run --network=isolated_nw -itd --name=container3 busybox
 
 8c1a0a5be480921d669a073393ade66a3fc49933f08bcc5515b37b8144f6d47c
 
@@ -473,7 +473,7 @@ provides complete isolation for the containers.
 
 Then, on each host, launch containers making sure to specify the network name.
 
-    $ docker run -itd --net=my-multi-host-network busybox
+    $ docker run -itd --network=my-multi-host-network busybox
 
 Once connected, each container has access to all the containers in the network
 regardless of which Docker host the container was launched on.

docs/userguide/networking/get-started-overlay.md

@@ -223,11 +223,11 @@ Once your network is created, you can start a container on any of the hosts and
 
 2. Start an Nginx web server on the `mhs-demo0` instance.
 
-		$ docker run -itd --name=web --net=my-net --env="constraint:node==mhs-demo0" nginx
+		$ docker run -itd --name=web --network=my-net --env="constraint:node==mhs-demo0" nginx
 
 4. Run a BusyBox instance on the `mhs-demo1` instance and get the contents of the Nginx server's home page.
 
-		$ docker run -it --rm --net=my-net --env="constraint:node==mhs-demo1" busybox wget -O- http://web
+		$ docker run -it --rm --network=my-net --env="constraint:node==mhs-demo1" busybox wget -O- http://web
 
 		Unable to find image 'busybox:latest' locally
 		latest: Pulling from library/busybox

docs/userguide/networking/work-with-networks.md

@@ -164,7 +164,7 @@ $ docker network inspect my-network
     }
 ]
 
-$ docker run -d -P --name redis --net my-network redis
+$ docker run -d -P --name redis --network my-network redis
 
 bafb0c808c53104b2c90346f284bda33a69beadcab4fc83ab8f2c5a4410cd129
 
@@ -244,10 +244,10 @@ $ docker network inspect isolated_nw
 You can see that the Engine automatically assigns an IP address to `container2`.
 Given we specified a `--subnet` when creating the network, Engine picked
 an address from that same subnet. Now, start a third container and connect it to
-the network on launch using the `docker run` command's `--net` option:
+the network on launch using the `docker run` command's `--network` option:
 
 ```bash
-$ docker run --net=isolated_nw --ip=172.25.3.3 -itd --name=container3 busybox
+$ docker run --network=isolated_nw --ip=172.25.3.3 -itd --name=container3 busybox
 
 467a7863c3f0277ef8e661b38427737f28099b61fa55622d6c30fb288d88c551
 ```
@@ -450,7 +450,7 @@ Continuing with the above example, create another container `container4` in
 for other containers in the same network.
 
 ```bash
-$ docker run --net=isolated_nw -itd --name=container4 --link container5:c5 busybox
+$ docker run --network=isolated_nw -itd --name=container4 --link container5:c5 busybox
 
 01b5df970834b77a9eadbaff39051f237957bd35c4c56f11193e0594cfd5117c
 ```
@@ -471,7 +471,7 @@ Now let us launch another container named `container5` linking `container4` to
 c4.
 
 ```bash
-$ docker run --net=isolated_nw -itd --name=container5 --link container4:c4 busybox
+$ docker run --network=isolated_nw -itd --name=container5 --link container4:c4 busybox
 
 72eccf2208336f31e9e33ba327734125af00d1e1d2657878e2ee8154fbb23c7a
 ```
@@ -629,7 +629,7 @@ Continuing with the above example, create another container in `isolated_nw`
 with a network alias.
 
 ```bash
-$ docker run --net=isolated_nw -itd --name=container6 --net-alias app busybox
+$ docker run --network=isolated_nw -itd --name=container6 --network-alias app busybox
 
 8ebe6767c1e0361f27433090060b33200aac054a68476c3be87ef4005eb1df17
 ```
@@ -702,7 +702,7 @@ network-scoped alias within the same network. For example, let's launch
 `container7` in `isolated_nw` with the same alias as `container6`
 
 ```bash
-$ docker run --net=isolated_nw -itd --name=container7 --net-alias app busybox
+$ docker run --network=isolated_nw -itd --name=container7 --network-alias app busybox
 
 3138c678c123b8799f4c7cc6a0cecc595acbdfa8bf81f621834103cd4f504554
 ```
@@ -859,7 +859,7 @@ endpoint from the network. Once the endpoint is cleaned up, the container can
 be connected to the network.
 
 ```bash
-$ docker run -d --name redis_db --net multihost redis
+$ docker run -d --name redis_db --network multihost redis
 
 ERROR: Cannot start container bc0b19c089978f7845633027aa3435624ca3d12dd4f4f764b61eac4c0610f32e: container already connected to network multihost
 
@@ -867,7 +867,7 @@ $ docker rm -f redis_db
 
 $ docker network disconnect -f multihost redis_db
 
-$ docker run -d --name redis_db --net multihost redis
+$ docker run -d --name redis_db --network multihost redis
 
 7d986da974aeea5e9f7aca7e510bdb216d58682faa83a9040c2f2adc0544795a
 ```

integration-cli/docker_cli_network_unix_test.go

@@ -1660,3 +1660,15 @@ func (s *DockerDaemonSuite) TestDaemonRestartRestoreBridgeNetwork(t *check.C) {
 		t.Fatal(err)
 	}
 }
+
+func (s *DockerNetworkSuite) TestDockerNetworkFlagAlias(c *check.C) {
+	dockerCmd(c, "network", "create", "user")
+	output, status := dockerCmd(c, "run", "--rm", "--network=user", "--network-alias=foo", "busybox", "true")
+	c.Assert(status, checker.Equals, 0, check.Commentf("unexpected status code %d (%s)", status, output))
+
+	output, status, _ = dockerCmdWithError("run", "--rm", "--net=user", "--network=user", "busybox", "true")
+	c.Assert(status, checker.Equals, 0, check.Commentf("unexpected status code %d (%s)", status, output))
+
+	output, status, _ = dockerCmdWithError("run", "--rm", "--network=user", "--net-alias=foo", "--network-alias=bar", "busybox", "true")
+	c.Assert(status, checker.Equals, 0, check.Commentf("unexpected status code %d (%s)", status, output))
+}

man/docker-create.1.md

@@ -52,8 +52,8 @@ docker-create - Create a new container
 [**--memory-swap**[=*LIMIT*]]
 [**--memory-swappiness**[=*MEMORY-SWAPPINESS*]]
 [**--name**[=*NAME*]]
-[**--net**[=*"bridge"*]]
-[**--net-alias**[=*[]*]]
+[**--network-alias**[=*[]*]]
+[**--network**[=*"bridge"*]]
 [**--oom-kill-disable**]
 [**--oom-score-adj**[=*0*]]
 [**-P**|**--publish-all**]
@@ -276,7 +276,7 @@ unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap.
                                'host': use the Docker host network stack.  Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure.
                                '<network-name>|<network-id>': connect to a user-defined network
 
-**--net-alias**=[]
+**--network-alias**=[]
    Add network-scoped alias for the container
 
 **--oom-kill-disable**=*true*|*false*

man/docker-run.1.md

@@ -54,8 +54,8 @@ docker-run - Run a command in a new container
 [**--memory-swap**[=*LIMIT*]]
 [**--memory-swappiness**[=*MEMORY-SWAPPINESS*]]
 [**--name**[=*NAME*]]
-[**--net**[=*"bridge"*]]
-[**--net-alias**[=*[]*]]
+[**--network-alias**[=*[]*]]
+[**--network**[=*"bridge"*]]
 [**--oom-kill-disable**]
 [**--oom-score-adj**[=*0*]]
 [**-P**|**--publish-all**]
@@ -395,7 +395,7 @@ and foreground Docker containers.
                                'host': use the Docker host network stack. Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure.
                                '<network-name>|<network-id>': connect to a user-defined network
 
-**--net-alias**=[]
+**--network-alias**=[]
    Add network-scoped alias for the container
 
 **--oom-kill-disable**=*true*|*false*

runconfig/opts/parse.go

@@ -182,10 +182,16 @@ func AddFlags(flags *pflag.FlagSet) *ContainerOptions {
 	flags.Var(&copts.flLinks, "link", "Add link to another container")
 	flags.Var(&copts.flLinkLocalIPs, "link-local-ip", "Container IPv4/IPv6 link-local addresses")
 	flags.StringVar(&copts.flMacAddress, "mac-address", "", "Container MAC address (e.g. 92:d0:c6:0a:29:33)")
-	flags.StringVar(&copts.flNetMode, "net", "default", "Connect a container to a network")
-	flags.Var(&copts.flAliases, "net-alias", "Add network-scoped alias for the container")
 	flags.VarP(&copts.flPublish, "publish", "p", "Publish a container's port(s) to the host")
 	flags.BoolVarP(&copts.flPublishAll, "publish-all", "P", false, "Publish all exposed ports to random ports")
+	// We allow for both "--net" and "--network", although the latter is the recommended way.
+	flags.StringVar(&copts.flNetMode, "net", "default", "Connect a container to a network")
+	flags.StringVar(&copts.flNetMode, "network", "default", "Connect a container to a network")
+	flags.MarkHidden("net")
+	// We allow for both "--net-alias" and "--network-alias", although the latter is the recommended way.
+	flags.Var(&copts.flAliases, "net-alias", "Add network-scoped alias for the container")
+	flags.Var(&copts.flAliases, "network-alias", "Add network-scoped alias for the container")
+	flags.MarkHidden("net-alias")
 
 	// Logging and storage
 	flags.StringVar(&copts.flLoggingDriver, "log-driver", "", "Logging driver for container")