Merge pull request #18301 from wenchma/doc_update_for_net

Add NETWORK_NAME_or_ID value for --net= option

contrib/completion/zsh/_docker

@@ -278,7 +278,7 @@ __docker_network_commands() {
         "disconnect:Disconnects a container from a network"
         "inspect:Displays detailed information on a network"
         "ls:Lists all the networks created by the user"
-        "rm:Deletes a network"
+        "rm:Deletes one or more networks"
     )
     _describe -t docker-network-commands "docker network command" _docker_network_subcommands
 }

docs/reference/commandline/create.md

@@ -56,7 +56,12 @@ Creates a new container.
       --memory-swap=""              Total memory (memory + swap), '-1' to disable swap
       --memory-swappiness=""        Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.
       --name=""                     Assign a name to the container
-      --net="default"               Set the Network mode for the container
+      --net="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
       --oom-kill-disable=false      Whether to disable OOM Killer for the container or not
       --oom-score-adj=0             Tune the host's OOM preferences for containers (accepts -1000 to 1000)
       -P, --publish-all=false       Publish all exposed ports to random ports

docs/reference/commandline/run.md

@@ -55,12 +55,12 @@ parent = "smn_cli"
       --memory-swap=""              Total memory (memory + swap), '-1' to disable swap
       --memory-swappiness=""        Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.
       --name=""                     Assign a name to the container
-      --net="bridge"                Connects a container to a network
-                                    'bridge': creates a new network stack for the container on the docker bridge
-                                    'none': no networking for this container
-                                    'container:<name|id>': reuses another container network stack
-                                    'host': use the host network stack inside the container
-                                    'NETWORK': connects the container to user-created network using `docker network create` command
+      --net="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
       --oom-kill-disable=false      Whether to disable OOM Killer for the container or not
       --oom-score-adj=0             Tune the host's OOM preferences for containers (accepts -1000 to 1000)
       -P, --publish-all=false       Publish all exposed ports to random ports

docs/reference/run.md

@@ -244,12 +244,12 @@ of the containers.
 ## Network settings
 
     --dns=[]         : Set custom dns servers for the container
-    --net="bridge"   : Connects a container to a network
-                        'bridge': creates a new network stack for the container on the docker bridge
-                        'none': no networking for this container
-                        'container:<name|id>': reuses another container network stack
-                        'host': use the host network stack inside the container
-                        'NETWORK': connects the container to user-created network using `docker network create` command
+    --net="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
     --add-host=""    : Add a line to /etc/hosts (host:IP)
     --mac-address="" : Sets the container's Ethernet device's MAC address
 

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

@@ -15,7 +15,7 @@ DRAFT to prevent building. Keeping for one cycle before deleting.
 
 # How the default network
 
-The information in this section explains configuring container DNS within tthe Docker default bridge. This is a `bridge` network named `bridge` created
+The information in this section explains configuring container networks within the Docker default bridge. This is a `bridge` network named `bridge` created
 automatically when you install Docker.
 
 **Note**: The [Docker networks feature](../dockernetworks.md) allows you to create user-defined networks in addition to the default bridge network.
@@ -40,7 +40,7 @@ The steps with which Docker configures a container are:
 
 With these steps complete, the container now possesses an `eth0` (virtual) network card and will find itself able to communicate with other containers and the rest of the Internet.
 
-You can opt out of the above process for a particular container by giving the `--net=` option to `docker run`, which takes four possible values.
+You can opt out of the above process for a particular container by giving the `--net=` option to `docker run`, which takes these possible values.
 - `--net=bridge` -- The default action, that connects the container to the Docker bridge as described above.
 
 - `--net=host` -- Tells Docker to skip placing the container inside of a separate network stack.  In essence, this choice tells Docker to **not containerize the container's networking**!  While container processes will still be confined to their own filesystem and process list and resource limits, a quick `ip addr` command will show you that, network-wise, they live "outside" in the main Docker host and have full access to its network interfaces.  Note that this does **not** let the container reconfigure the host network stack -- that would require `--privileged=true` -- but it does let container processes open low-numbered ports like any other root process. It also allows the container to access local network services like D-bus.  This can lead to processes in the container being able to do unexpected things like [restart your computer](https://github.com/docker/docker/issues/6401). You should use this option with caution.
@@ -49,6 +49,8 @@ You can opt out of the above process for a particular container by giving the `-
 
 - `--net=none` -- Tells Docker to put the container inside of its own network stack but not to take any steps to configure its network, leaving you free to build any of the custom configurations explored in the last few sections of this document.
 
+- `--net=<network-name>|<network-id>` -- Tells Docker to connect the container to a user-defined network.
+
 ## Manually network
 
 To get an idea of the steps that are necessary if you use `--net=none` as described in that last bullet point, here are the commands that you would run to reach roughly the same configuration as if you had let Docker do all of the configuration:

man/docker-create.1.md

@@ -227,10 +227,11 @@ This value should always larger than **-m**, so you should always use this with
 
 **--net**="*bridge*"
    Set the Network mode for the container
-                               'bridge': creates a new network stack for the container on the docker bridge
-                               'none': no networking for this container
-                               'container:<name|id>': reuses another container network stack
-                               'host': use the host network stack inside the container.  Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure.
+                               '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.  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
 
 **--oom-kill-disable**=*true*|*false*
 	Whether to disable OOM Killer for the container or not.

man/docker-run.1.md

@@ -339,10 +339,11 @@ and foreground Docker containers.
 
 **--net**="*bridge*"
    Set the Network mode for the container
-                               'bridge': creates a new network stack for the container on the docker bridge
-                               'none': no networking for this container
-                               'container:<name|id>': reuses another container network stack
-                               'host': use the host network stack inside the container.  Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure.
+                               '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. 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
 
 **--oom-kill-disable**=*true*|*false*
    Whether to disable OOM Killer for the container or not.