README.md

Linux kernel Namespaces

Discover how containers are using Linux kernel namespaces...

...or the mounts inside your containers, and how over-mounts make other mounts invisible.

Quick Start

First, ensure that you have the Docker compose v2 plugin installed.

Note

Debian users typically need to install docker-ce instead of docker.io packages, as Debian only backports random "security fixes" and freezes features completely – which absolutely makes sense in a fast moving container world ... NOT.

Make sure you have a Linux kernel of at least version 4.11 installed, however we highly recommend at least kernel version 5.6 or later.

wget -q --no-cache -O - \
  https://github.com/thediveo/lxkns/raw/master/deployments/wget/docker-compose.yaml \
  | docker compose -f - up

Finally, visit http://localhost:5010 and start looking around Linux kernel namespaces, as well as mount points with their hierarchies.

Overview

lxkns discovers...

• Linux namespaces in almost every nook and cranny of your hosts (from open file descriptors, bind-mounts, processes, and now even tasks and from open sockets) – please see the table below,
• the mount points inside mount namespaces (correctly representing "overmounts").
• container workloads: these are automatically related to the underlying Linux namespaces.
  • lxkns now leverages (Siemens OSS) Turtlefinder technology to autodetect container engines even in hierarchical configurations, such as Kubernetes-in-Docker and Docker Desktop on WSL2. Also, (socket-activated) podman detection has finally landed in turtlefinder, and in turn also in lxkns.

	Where?	lsns	lxkns	Kernel
➀	/proc/*/ns/*	✓	✓	4.11
➁	/proc/*/task/*/ns/*	✗	✓	4.11
➂	bind mounts	✓A	✓	4.11
➃a	/proc/*/fd/* namespace fds	✗	✓	4.11
➃b	/proc/*/fd/* socket fds	✗	✓	5.6
➄	namespace hierarchy	✗	✓	4.11
➅	owning user namespaces	✗	✓	4.11

• ^A very recent versions of lsns have improved and are now reporting bind-mounted namespaces as of "util-linux 2.39.1". Maybe lxkns managed to put some pressure to innovate on lsns, maybe not; we would like to hear from people who are acquainted with the rationale.

lxkns finds mount points even in process-less mount namespaces (for instance, as utilized in "snap" technology). Our discovery engine even determines the visibility of mount points, taking different forms of "overmounting" into consideration.

Take a look at the comprehensive user (and developer) manual.

Note

Please check Important Changes, especially if you have been used the API in the past, and not only the service.

Intro Video

Or, watch the short overview video how to find your way around discovery web frontend:

Detected/Supported Container Engines

The following container engine types are supported:

• Docker,
• plain containerd,
• via the CRI Evented PLEG API: containerd and CRI-O,
• socket-activatable podman – via the Docker-compatible API only. Please note that there is no support for podman-proprietary pods (not to be confused with Kubernetes pods).

Deployment Options

The lxkns discovery engine can be operated as a stand-alone REST service with additional web UI. Alternatively, it can be embedded/integrated into other system diagnosis tools. A prominent example of embedding lxkns is @siemens/ghostwire.

Notes

Supported Go Versions

lxkns supports versions of Go that are noted by the Go release policy, that is, major versions N and N-1 (where N is the current major version).

Hacking It

This project comes with comprehensive unit tests, also covering leak checks:

• goroutine leak checking courtesy of Gomega's gleak package.

• file descriptor leak checking courtesy of the @thediveo/fdooze module.

Caution

Note: do not run parallel tests for multiple packages. make test ensures to run all package tests always sequentially, but in case you run go test yourself, please don't forget -p 1 when testing multiple packages in one, erm, go.

Contributing

Please see CONTRIBUTING.md.

Copyright and License

lxkns is Copyright 2020‒24 Harald Albrecht, and licensed under the Apache License, Version 2.0.