Merge pull request #20285 from moxiegirl/fix-user-guide

Update the userguide to fix user feedback

docs/userguide/index.md

@@ -1,8 +1,8 @@
 <!--[metadata]>
 +++
 title = "User guide"
-description = "Welcome to the user guide"
-keywords = ["docker, introduction, documentation, about, technology, docker.io, user, guide, user's, manual, platform, framework, home,  intro"]
+description = "How to use the Docker Engine user guide"
+keywords = ["engine, introduction, documentation, about, technology, docker, user, guide, framework, home,  intro"]
 [menu.main]
 parent="engine_use"
 identifier = "engine_guide"
@@ -10,4 +10,54 @@ weight="-80"
 +++
 <![end-metadata]-->
 
-# User guide
+# Docker Engine user guide
+
+This guide helps users learn how to use Docker Engine.
+
+- [Introduction to Engine user guide](intro.md)
+
+## Learn by example
+
+- [Hello world in a container](containers/dockerizing.md)
+- [Build your own images](containers/dockerimages.md)
+- [Network containers](containers/networkingcontainers.md)
+- [Run a simple application](containers/usingdocker.md)
+- [Manage data in containers](containers/dockervolumes.md)
+- [Store images on Docker Hub](containers/dockerrepos.md)
+
+## Work with images
+
+- [Best practices for writing Dockerfiles](eng-image/dockerfile_best-practices.md)
+- [Create a base image](eng-image/baseimages.md)
+- [Image management](eng-image/image_management.md)
+
+## Manage storage drivers
+
+- [Understand images, containers, and storage drivers](storagedriver/imagesandcontainers.md)
+- [Select a storage driver](storagedriver/selectadriver.md)
+- [AUFS storage in practice](storagedriver/aufs-driver.md)
+- [Btrfs storage in practice](storagedriver/btrfs-driver.md)
+- [Device Mapper storage in practice](storagedriver/device-mapper-driver.md)
+- [OverlayFS storage in practice](storagedriver/overlayfs-driver.md)
+- [ZFS storage in practice](storagedriver/zfs-driver.md)
+
+## Configure networks
+
+- [Understand Docker container networks](networking/dockernetworks.md)
+- [Embedded DNS server in user-defined networks](networking/configure-dns.md)
+- [Get started with multi-host networking](networking/get-started-overlay.md)
+- [Work with network commands](networking/work-with-networks.md)
+
+### Work with the default network
+
+- [Understand container communication](networking/default_network/container-communication.md)
+- [Legacy container links](networking/default_network/dockerlinks.md)
+- [Binding container ports to the host](networking/default_network/binding.md)
+- [Build your own bridge](networking/default_network/build-bridges.md)
+- [Configure container DNS](networking/default_network/configure-dns.md)
+- [Customize the docker0 bridge](networking/default_network/custom-docker0.md)  
+- [IPv6 with Docker](networking/default_network/ipv6.md)  
+
+## Misc
+
+- [Apply custom metadata](labels-custom-metadata.md)

docs/userguide/networking/default_network/options.md

@@ -1,141 +0,0 @@
-<!--[metadata]>
-+++
-draft=true
-title = "Tools and Examples"
-keywords = ["docker, bridge, docker0, network"]
-[menu.main]
-parent = "smn_networking_def"
-+++
-<![end-metadata]-->
-
-<!--[metadata]>
-We may want to add it back in later under another form. Labeled DRAFT for now. Won't be built.
-<![end-metadata]-->
-
-# Quick guide to the options
-Here is a quick list of the networking-related Docker command-line options, in case it helps you find the section below that you are looking for.
-
-Some networking command-line options can only be supplied to the Docker server when it starts up, and cannot be changed once it is running:
-- `-b BRIDGE` or `--bridge=BRIDGE` -- see
-
-  [Building your own bridge](#bridge-building)
-
-- `--bip=CIDR` -- see
-
-  [Customizing docker0](#docker0)
-
-- `--default-gateway=IP_ADDRESS` -- see
-
-  [How Docker networks a container](#container-networking)
-
-- `--default-gateway-v6=IP_ADDRESS` -- see
-
-  [IPv6](#ipv6)
-
-- `--fixed-cidr` -- see
-
-  [Customizing docker0](#docker0)
-
-- `--fixed-cidr-v6` -- see
-
-  [IPv6](#ipv6)
-
-- `-H SOCKET...` or `--host=SOCKET...` --
-
-  This might sound like it would affect container networking,
-
-  but it actually faces in the other direction:
-
-  it tells the Docker server over what channels
-
-  it should be willing to receive commands
-
-  like "run container" and "stop container."
-
-- `--icc=true|false` -- see
-
-  [Communication between containers](#between-containers)
-
-- `--ip=IP_ADDRESS` -- see
-
-  [Binding container ports](#binding-ports)
-
-- `--ipv6=true|false` -- see
-
-  [IPv6](#ipv6)
-
-- `--ip-forward=true|false` -- see
-
-  [Communication between containers and the wider world](#the-world)
-
-- `--iptables=true|false` -- see
-
-  [Communication between containers](#between-containers)
-
-- `--mtu=BYTES` -- see
-
-  [Customizing docker0](#docker0)
-
-- `--userland-proxy=true|false` -- see
-
-  [Binding container ports](#binding-ports)
-
-There are three 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 specified:
-- `--dns=IP_ADDRESS...` -- see
-
-  [Configuring DNS](#dns)
-
-- `--dns-search=DOMAIN...` -- see
-
-  [Configuring DNS](#dns)
-
-- `--dns-opt=OPTION...` -- see
-
-  [Configuring DNS](#dns)
-
-Finally, several networking options can only be provided when calling `docker run` because they specify something specific to one container:
-- `-h HOSTNAME` or `--hostname=HOSTNAME` -- see
-
-  [Configuring DNS](#dns) and
-
-  [How Docker networks a container](#container-networking)
-
-- `--link=CONTAINER_NAME_or_ID:ALIAS` -- see
-
-  [Configuring DNS](#dns) and
-
-  [Communication between containers](#between-containers)
-
-- `--net=bridge|none|container:NAME_or_ID|host` -- see
-
-  [How Docker networks a container](#container-networking)
-
-- `--mac-address=MACADDRESS...` -- see
-
-  [How Docker networks a container](#container-networking)
-
-- `-p SPEC` or `--publish=SPEC` -- see
-
-  [Binding container ports](#binding-ports)
-
-- `-P` or `--publish-all=true|false` -- see
-
-  [Binding container ports](#binding-ports)
-
-To supply networking options to the Docker server at startup, use the `DOCKER_OPTS` variable in the Docker upstart configuration file. For Ubuntu, edit the variable in `/etc/default/docker` or `/etc/sysconfig/docker` for CentOS.
-
-The following example illustrates how to configure Docker on Ubuntu to recognize a newly built bridge.
-
-Edit the `/etc/default/docker` file:
-
-```
-$ echo 'DOCKER_OPTS="-b=bridge0"' >> /etc/default/docker
-```
-
-Then restart the Docker server.
-
-```
-$ sudo service docker start
-```
-
-For additional information on bridges, see [building your own bridge](#building-your-own-bridge) later on this page.

docs/userguide/networking/default_network/saveme.md

@@ -1,28 +0,0 @@
-<!--[metadata]>
-+++
-draft=true
-title = "Saved text"
-keywords = ["docker, bridge, docker0, network"]
-[menu.main]
-parent = "smn_networking_def"
-+++
-<![end-metadata]-->
-
-<!--[metadata]>
-This content was extracted from the original introduction. We may want to add it back in later under another form. Labeled DRAFT for now. Won't be built.
-<![end-metadata]-->
-
-
-## A Brief introduction to networking and docker
-When Docker starts, it creates a virtual interface named `docker0` on the host machine.  It randomly chooses an address and subnet from the private range defined by [RFC 1918](http://tools.ietf.org/html/rfc1918) that are not in use on the host machine, and assigns it to `docker0`. Docker made the choice `172.17.42.1/16` when I started it a few minutes ago, for example -- a 16-bit netmask providing 65,534 addresses for the host machine and its containers. The MAC address is generated using the IP address allocated to the container to avoid ARP collisions, using a range from `02:42:ac:11:00:00` to `02:42:ac:11:ff:ff`.
-
-> **Note:** This document discusses advanced networking configuration and options for Docker. In most cases you won't need this information. If you're looking to get started with a simpler explanation of Docker networking and an introduction to the concept of container linking see the [Docker User Guide](dockerlinks.md).
-
-But `docker0` is no ordinary interface.  It is a virtual _Ethernet bridge_ that automatically forwards packets between any other network interfaces that are attached to it.  This lets containers communicate both with the host machine and with each other.  Every time Docker creates a container, it creates a pair of "peer" interfaces that are like opposite ends of a pipe -- a packet sent on one will be received on the other.  It gives one of the peers to the container to become its `eth0` interface and keeps the other peer, with a unique name like `vethAQI2QT`, out in the namespace of the host machine.  By binding every `veth*` interface to the `docker0` bridge, Docker creates a virtual subnet shared between the host machine and every Docker container.
-
-The remaining sections of this document explain all of the ways that you can use Docker options and -- in advanced cases -- raw Linux networking commands to tweak, supplement, or entirely replace Docker's default networking configuration.
-
-## Editing networking config files
-Starting with Docker v.1.2.0, you can now edit `/etc/hosts`, `/etc/hostname` and `/etc/resolve.conf` in a running container. This is useful if you need to install bind or other services that might override one of those files.
-
-Note, however, that changes to these files will not be saved by `docker commit`, nor will they be saved during `docker run`. That means they won't be saved in the image, nor will they persist when a container is restarted; they will only "stick" in a running container.

docs/userguide/networking/default_network/tools.md

@@ -1,83 +0,0 @@
-<!--[metadata]>
-+++
-draft=true
-title = "Tools and Examples"
-keywords = ["docker, bridge, docker0, network"]
-[menu.main]
-parent = "smn_networking_def"
-+++
-<![end-metadata]-->
-
-<!--[metadata]>
-Dave Tucker instructed remove this.  We may want to add it back in later under another form. Labeled DRAFT for now. Won't be built.
-<![end-metadata]-->
-
-# Tools and examples
-Before diving into the following sections on custom network topologies, you might be interested in glancing at a few external tools or examples of the same kinds of configuration.  Here are two:
-- Jérôme Petazzoni has created a `pipework` shell script to help you
-
-  connect together containers in arbitrarily complex scenarios:
-
-  [https://github.com/jpetazzo/pipework](https://github.com/jpetazzo/pipework)
-
-- Brandon Rhodes has created a whole network topology of Docker
-
-  containers for the next edition of Foundations of Python Network
-
-  Programming that includes routing, NAT'd firewalls, and servers that
-
-  offer HTTP, SMTP, POP, IMAP, Telnet, SSH, and FTP:
-
-  [https://github.com/brandon-rhodes/fopnp/tree/m/playground](https://github.com/brandon-rhodes/fopnp/tree/m/playground)
-
-Both tools use networking commands very much like the ones you saw in the previous section, and will see in the following sections.
-
-# Building a point-to-point connection
-<a name="point-to-point"></a>
-
-By default, Docker attaches all containers to the virtual subnet implemented by `docker0`.  You can create containers that are each connected to some different virtual subnet by creating your own bridge as shown in [Building your own bridge](#bridge-building), starting each container with `docker run --net=none`, and then attaching the containers to your bridge with the shell commands shown in [How Docker networks a container](#container-networking).
-
-But sometimes you want two particular containers to be able to communicate directly without the added complexity of both being bound to a host-wide Ethernet bridge.
-
-The solution is simple: when you create your pair of peer interfaces, simply throw _both_ of them into containers, and configure them as classic point-to-point links.  The two containers will then be able to communicate directly (provided you manage to tell each container the other's IP address, of course).  You might adjust the instructions of the previous section to go something like this:
-
-```
-# Start up two containers in two terminal windows
-
-$ docker run -i -t --rm --net=none base /bin/bash
-root@1f1f4c1f931a:/#
-
-$ docker run -i -t --rm --net=none base /bin/bash
-root@12e343489d2f:/#
-
-# Learn the container process IDs
-# and create their namespace entries
-
-$ docker inspect -f '{{.State.Pid}}' 1f1f4c1f931a
-2989
-$ docker inspect -f '{{.State.Pid}}' 12e343489d2f
-3004
-$ sudo mkdir -p /var/run/netns
-$ sudo ln -s /proc/2989/ns/net /var/run/netns/2989
-$ sudo ln -s /proc/3004/ns/net /var/run/netns/3004
-
-# Create the "peer" interfaces and hand them out
-
-$ sudo ip link add A type veth peer name B
-
-$ sudo ip link set A netns 2989
-$ sudo ip netns exec 2989 ip addr add 10.1.1.1/32 dev A
-$ sudo ip netns exec 2989 ip link set A up
-$ sudo ip netns exec 2989 ip route add 10.1.1.2/32 dev A
-
-$ sudo ip link set B netns 3004
-$ sudo ip netns exec 3004 ip addr add 10.1.1.2/32 dev B
-$ sudo ip netns exec 3004 ip link set B up
-$ sudo ip netns exec 3004 ip route add 10.1.1.1/32 dev B
-```
-
-The two containers should now be able to ping each other and make connections successfully.  Point-to-point links like this do not depend on a subnet nor a netmask, but on the bare assertion made by `ip route` that some other single IP address is connected to a particular network interface.
-
-Note that point-to-point links can be safely combined with other kinds of network connectivity -- there is no need to start the containers with `--net=none` if you want point-to-point links to be an addition to the container's normal networking instead of a replacement.
-
-A final permutation of this pattern is to create the point-to-point link between the Docker host and one container, which would allow the host to communicate with that one container on some single IP address and thus communicate "out-of-band" of the bridge that connects the other, more usual containers.  But unless you have very specific networking needs that drive you to such a solution, it is probably far preferable to use `--icc=false` to lock down inter-container communication, as we explored earlier.