mobydig
(dig as in DNS dig) is a consumable Golang module (including a demo
CLI) for diagnosing the reachability of other containers on Docker custom
networks directly reachable from a particular Docker container:
- on these directly attached custom networks, what are the DNS names of other containers and (Docker compose) services?
- are the corresponding IP addresses reachable?
mobydig
is part of the "Edgeshark" project that consist of several
repositories:
- Edgeshark Hub repository
- G(h)ostwire discovery service
- Packetflix packet streaming service
- Containershark Extcap plugin for Wireshark
- support modules:
- csharg (CLI)
- 🖝 mobydig 🖜
- ieddata
Think of mobydig
as a (pure Go) combination of dig
and ping
in order to
dig up the IP addresses associated with other containers and services and then
to (in)validate these IP addresses. But without the need to install dig
and
ping
into your containers. This module is designed for consumption by other
modules and thus the mobydig
command rather is a show case.
In the following example, the container named test_test_1
is taken as the
starting point. mobydig
first determines the custom networks test_test_1
is
connected to, then all other containers also attached to at least one of these
custom networks. Next, the DNS service and container names are dug to which
Docker's embedded DNS resolver will respond, and then finally all resulting IP
addresses pinged.
$ # set up a testbed with some custom networks and a couple of containers
$ ./test/up # tear down using ./test/down
$ go run -exec sudo ./cmd/mobydig/ test-test-1
networks attached to container test-test-1: net_A net_B net_C
DNS names for containers/services on any attached network
26105065c679 ✔ 172.24.0.4
3ab1c736c330 ✔ 172.24.0.2
974fd4a0c59f ✔ 172.23.0.2
bar ✔ 172.23.0.2
foo ✔ 172.24.0.2 ✔ 172.24.0.4
test-bar-1 ✔ 172.23.0.2
test-foo-1 ✔ 172.24.0.2
test-foo-2 ✔ 172.24.0.4
DNS names for containers/services on network net_A
26105065c679.net_A ✔ 172.24.0.4
3ab1c736c330.net_A ✔ 172.24.0.2
foo.net_A ✔ 172.24.0.2 ✔ 172.24.0.4
test-foo-1.net_A ✔ 172.24.0.2
test-foo-2.net_A ✔ 172.24.0.4
DNS names for containers/services on network net_B
974fd4a0c59f.net_B ✔ 172.23.0.2
bar.net_B ✔ 172.23.0.2
test-bar-1.net_B ✔ 172.23.0.2
DNS names for containers/services on network net_C
26105065c679.net_C ✔ 172.22.0.4
3ab1c736c330.net_C ✔ 172.22.0.3
foo.net_C ✔ 172.22.0.3 ✔ 172.22.0.4
test-foo-1.net_C ✔ 172.22.0.3
test-foo-2.net_C ✔ 172.22.0.4
(Note: this example uses the test deployment in test/
.)
go get github.com/siemens/mobydig@latest
Note: ieddata
supports versions of Go 1 that are noted by the Go release
policy, that is, major
versions N and N-1 (where N is the current major version).
mobydig
can be either used as a CLI tool, or its components integrated in
other tools and applications:
-
Digger
takes a list of Docker network names with the container and service names on each network and then digs up the associated IP addresses and validates them by pinging them.Digger
operates from the perspective of any arbitrary network namespace, and especially from the network perspective of a particular container. -
Validator
consumes names and IP addresses, as emitted by aDigger
and then validates them using aPinger
. In contrast to directly wire up aDigger
and aPinger
, aValidator
uses a cache in order to avoid duplicate validations when multiple DNS names resolve to the same address(es). -
Pinger
(in)validates IP addresses from the perspective of any arbitrary network namespace inside a Linux host, while live streaming its results over a Go channel. -
DnsPool
operates a limited of eager DNS workers who like to resolve FQDNs into their associated IP address(es) from the perspective of any arbitrary network namespace inside a Linux host and then stream their findings live over a Go channel.DnsPool
workers can also be deployed in queries for other RRs than justA
andAAAA
RRs.
The tests require "docker composer" v2 and fail for "docker-composer" v1 due to the change in container naming from v1→v2. With Docker CE on Ubuntu or Debian, install with
sudo apt-get install docker-compose-plugin
if not automatically installed already.
While some of mobydig
s unit tests can successfully run as an ordinary user,
many tests require root rights. Also, a Docker engine is required for the tests
to successfully complete (well, this package is about Docker's integrated DNS
resolver to quite some extend anyway):
make test
The included mobydig.code-workspace
defines the following tasks:
-
View Go module documentation task: installs
pkgsite
, if not done already so, then startspkgsite
and opens VSCode's integrated ("simple") browser to show the go-plugger/v2 documentation. -
Build workspace task: builds all, including the shared library test plugin.
-
Run all tests with coverage task: does what it says on the tin and runs all tests with coverage.
- pksite service: auxilliary task to run
pkgsite
as a background service usingscripts/pkgsite.sh
. The script leverages browser-sync and nodemon to hot reload the Go module documentation on changes; many thanks to @mdaverde's Build your Golang package docs locally for paving the way.scripts/pkgsite.sh
adds automatic installation ofpkgsite
, as well as thebrowser-sync
andnodemon
npm packages for the local user. - view pkgsite: auxilliary task to open the VSCode-integrated "simple" browser
and pass it the local URL to open in order to show the module documentation
rendered by
pkgsite
. This requires a detour via a task input with ID "pkgsite".
make
: lists all targets.make coverage
: runs all tests with coverage and then updates the coverage badge inREADME.md
.make pkgsite
: installsx/pkgsite
, as well as thebrowser-sync
andnodemon
npm packages first, if not already done so. Then runs thepkgsite
and hot reloads it whenever the documentation changes.make report
: installs@gojp/goreportcard
if not yet done so and then runs it on the code base.make test
: runs all tests.
⚠ Make sure to disable parallel test execution using
-p 1
when testing multiple packages, as in the case for./...
. It is not possible to run multiple package tests simultaneously as the multiple docker-compose instances will trip on each other happily and create multiple networks with the same name, as well as mix and match containers by name and then completely mess up.
In the tradition of CuriousMarc's "ouchies":
-
Forgetting or not knowing that
go test ./...
runs all tests in parallel, so that the same docker compose project harness gets created multiple times in parallel. See next item why this is considered to be harmful. -
Names of Docker networks are not unique, as opposed to Docker container names alway being unique: it is possible to create multiple different Docker networks with the same name, yet unique IDs. See also
@moby/moby
issue The docker daemon API lets you create two networks with the same name #18864.
-
Rob Pike's Self-referential functions and the design of options.
-
Dave Cheney's Functional options for friendly APIs.
Please see CONTRIBUTING.md.
(c) Siemens AG 2023