diff --git a/_data/toc.yaml b/_data/toc.yaml index 8d9dfb3533a1..c22ad4c8889e 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -222,6 +222,8 @@ guides: title: Get started with macvlan network driver - path: /engine/userguide/networking/overlay-security-model/ title: Swarm mode overlay network security model + - path: /engine/userguide/networking/network-debug/ + title: Debug overlay or swarm networking issues - path: /engine/userguide/networking/configure-dns/ title: Configure container DNS in user-defined networks - sectiontitle: Default bridge network diff --git a/engine/userguide/networking/network-debug.md b/engine/userguide/networking/network-debug.md new file mode 100644 index 000000000000..dc720ccff1dc --- /dev/null +++ b/engine/userguide/networking/network-debug.md @@ -0,0 +1,219 @@ +--- +description: Learn to use the built-in network debugger to debug overlay networking problems +keywords: network, troubleshooting, debug +title: Debug overlay or swarm networking issues +--- + +Docker CE 17.12 and higher introduce a network debugging tool designed to help +debug issues with overlay networks and swarm services running on Linux hosts. +When enabled, a network diagnostic server listens on the specified port and +provides diagnostic information. The network debugging tool should only be +started to debug specific issues, and should not be left running all the time. + +Information about networks is stored in a database, which can be examined using +the API. + +The Docker API exposes endpoints to query and control the network debugging +tool. CLI integration is provided as a preview, but the implementation is not +yet considered stable and commands and options may change without notice. + +## Enable the diagnostic tool + +The tool currently only works on Docker hosts running on Linux. Repeat these +steps for each node participating in the swarm. + +1. Set the `network-diagnostic-port` to a port which is free on the Docker + host, in the `/etc/docker/daemon.json` configuration file. + + ```json + “network-diagnostic-port”: + ``` + +2. Get the process ID (PID) of the `dockerd` process. It is the second field in + the output, and is typically a number from 2 to 6 digits long. + + ```bash + $ ps aux |grep dockerd | grep -v grep + ``` + +3. Reload the Docker configuration without restarting Docker, by sending the + `HUP` signal to the PID you found in the previous step. + + ```bash + kill -HUP + ``` + +A message like the following will appear in the Docker host logs: + +```none +Starting the diagnose server listening on for commands +``` + +## Disable the diagnostic tool + +Repeat these steps for each node participating in the swarm. + +1. Remove the `network-diagnostic-port` key from the `/etc/docker/daemon.json` + configuration file. + +2. Get the process ID (PID) of the `dockerd` process. It is the second field in + the output, and is typically a number from 2 to 6 digits long. + + ```bash + $ ps aux |grep dockerd | grep -v grep + ``` + +3. Reload the Docker configuration without restarting Docker, by sending the + `HUP` signal to the PID you found in the previous step. + + ```bash + kill -HUP + ``` + +A message like the following will appear in the Docker host logs: + +```none +Disabling the diagnose server +``` + +## Access the diagnostic tool's API + +The network diagnostic tool exposes its own RESTful API. To access the API, +send a HTTP request to the port where the tool is listening. The following +commands assume the tool is listening on port 2000. + +Examples are not given for every endpoint. + +### Get help + +```bash +$ curl localhost:2000/help + +OK +/updateentry +/getentry +/gettable +/leavenetwork +/createentry +/help +/clusterpeers +/ready +/joinnetwork +/deleteentry +/networkpeers +/ +/join +``` + +### Join or leave the network database cluster + +```bash +$ curl localhost:2000/join?members=ip1,ip2,... +``` + +```bash +$ curl localhost:2000/leave?members=ip1,ip2,... +``` + +### Join or leave a network + +```bash +$ curl localhost:2000/joinnetwork?nid= +``` + +```bash +$ curl localhost:2000/leavenetwork?nid= +``` + +### List cluster peers + +```bash +$ curl localhost:2000/clusterpeers +``` + +### List nodes connected to a given network + +```bash +$ curl localhost:2000/networkpeers?nid= +``` + +### Dump database tables + +The tables are called `endpoint_table` and `overlay_peer_table`. These names may +change. + +```bash +$ curl localhost:2000/gettable?nid=&tname= +``` + +### Interact with a specific database table + +The tables are called `endpoint_table` and `overlay_peer_table`. These names may +change. + +```bash +$ curl localhost:2000/?nid=&tname=
&key=[&value=] +``` + +## Access the diagnostic tool's CLI + +The CLI is provided as a preview and is not yet stable. Commands or options may +change at any time. + +The CLI executable is called `diagnosticClient` and is made available using a +standalone container. + +The following flags are supported: + +| Flag | Description | +|---------------|-------------------------------------------------| +| -c | Command to run. One of `sd` or `overlay`. | +| -ip | The IP address to query. Defaults to 127.0.0.1. | +| -net | The target network ID. | +| -port | The target port. | +| -v | Enable verbose output. | + +### Access the CLI + +The CLI is provided as a container that needs to run using privileged mode. + +1. To run the container, use a command like the following: + + ```bash + $ docker container run --name net-diagnostic -d --privileged --network host fcrisciani/network-diagnostic + ``` + +2. Connect to the container using `docker container attach `, + and start the server using the following command: + + ```bash + $ kill -HUP 1 + ``` + +3. If you have not already done so, join the Docker host to the swarm, then + run the diagnostic CLI within the container. + + ```bash + $ ./diagnosticClient ... + ``` + +4. When finished debugging, stop the container. + +### Examples + +The following commands dump the service discovery table and verify node +ownership. + +**Standalone network:** + +```bash +$ debugClient -c sd -v -net n8a8ie6tb3wr2e260vxj8ncy4 +``` + +**Overlay network:** + +```bash +$ debugClient -port 2001 -c overlay -v -net n8a8ie6tb3wr2e260vxj8ncy4 +``` + +