lxkns

package module

v0.33.1 Latest Latest Go to latest Published: Mar 19, 2024 License: Apache-2.0 Imports: 0 Imported by: 0

Details

Valid go.mod file

The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
Redistributable license

Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
Tagged version

Modules with tagged versions give importers more predictable builds.
Stable version

When a project reaches major version v1 it is considered stable.
Learn more about best practices

Repository

github.com/thediveo/lxkns

Links

Open Source Insights

README ¶

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.

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.

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.

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

Documentation ¶

Overview ¶

Package lxkns discovers Linux kernel namespaces. Please see github.com/thediveo/lxkns/discovery for the specific API to namespace discovery.

For a broader introduction into lxkns, including the service deployment and web user interface, please refer to the 📖online manual.

Additional TDD support can be found in github.com/thediveo/lxkns/test/matchers, implementing domain-specific Gomega matchers about containers, container groups, pods, et cetera.

Index ¶

Constants

Constants ¶

View Source

const SemVersion = "0.32.2-2-g6776f8e"

SemVersion is the semantic version string of the lxkns module.

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

This section is empty.

Source Files ¶

View all Source files

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
api
types Package types defines the common types for (un)marshalling elements of the lxkns information model from/to JSON.	Package types defines the common types for (un)marshalling elements of the lxkns information model from/to JSON.
cmd
dumpns dumpns runs a namespace (and process) discovery and then dumps the results as JSON.	dumpns runs a namespace (and process) discovery and then dumps the results as JSON.
internal/pkg/caps Package caps provides textual information about the effective capabilities of a process.	Package caps provides textual information about the effective capabilities of a process.
internal/pkg/cli Package cli handles registering CLI flags via a plug-in mechanism.	Package cli handles registering CLI flags via a plug-in mechanism.
internal/pkg/cli/cliplugin
internal/pkg/debug Package debug supplies the --log and --debug CLI flags.	Package debug supplies the --log and --debug CLI flags.
internal/pkg/filter Package filter provides CLI-controlled filtering of namespaces by type.	Package filter provides CLI-controlled filtering of namespaces by type.
internal/pkg/output Package output provides terminal output convenience helpers for namespace type icons and cgroup information rendering.	Package output provides terminal output convenience helpers for namespace type icons and cgroup information rendering.
internal/pkg/style Package style styles text output of the CLI commands with foreground and background colors, as well as different text styles (bold, italics, ...).	Package style styles text output of the CLI commands with foreground and background colors, as well as different text styles (bold, italics, ...).
internal/pkg/task Package task provides the “--task” CLI flag to enable task discovery.	Package task provides the “--task” CLI flag to enable task discovery.
internal/pkg/turtles
internal/test/getstdout Package getstdout captures os.Stdout and os.Stderr while executing a specified function, returning the captured output afterwards.	Package getstdout captures os.Stdout and os.Stderr while executing a specified function, returning the captured output afterwards.
internal/tool Package tool provides convenience helpers useful to the lxkns CLI tools.	Package tool provides convenience helpers useful to the lxkns CLI tools.
lspidns lspidns lists the tree of PID namespaces, optionally with their owning user namespaces.	lspidns lists the tree of PID namespaces, optionally with their owning user namespaces.
lsuns lsuns lists the tree of user namespaces, optionally with the other namespaces they own.	lsuns lists the tree of user namespaces, optionally with the other namespaces they own.
lxkns
mntnssandbox
nscaps nscaps determines a process' capabilities in some namespace.	nscaps determines a process' capabilities in some namespace.
pidtree pidtree displays a tree (or only a single branch) of processes together with their PID namespaces, and additionally also shows the local PIDs of processes (where applicable).	pidtree displays a tree (or only a single branch) of processes together with their PID namespaces, and additionally also shows the local PIDs of processes (where applicable).
containerizer Package containerizer provides the implementations to store data about [Container] and [ContainerEngine] objects.	Package containerizer provides the implementations to store data about [Container] and [ContainerEngine] objects.
whalefriend Package whalefriend implements a [containerizer.Containerizer] that discovers containers from container engines supported by the [@thediveo/whalewatcher] module, such as Docker and containerd (moby & friends).	Package whalefriend implements a [containerizer.Containerizer] that discovers containers from container engines supported by the [@thediveo/whalewatcher] module, such as Docker and containerd (moby & friends).
decorator Package decorator defines the [Decorate] plug-in interface, where the so-called “decorators” adorn the container information model with additional data, such as container grouping and unified pod-related container labels.	Package decorator defines the [Decorate] plug-in interface, where the so-called “decorators” adorn the container information model with additional data, such as container grouping and unified pod-related container labels.
all Package all imports and activates all lxkns (container) decorator plugins, activating them during discoveries.	Package all imports and activates all lxkns (container) decorator plugins, activating them during discoveries.
composer Package composer decorates lxkns information models with (Docker) Composer project groups.	Package composer decorates lxkns information models with (Docker) Composer project groups.
dockerplugin Package dockerplugin decorates containerd containers that are represent managed Docker plugins.	Package dockerplugin decorates containerd containers that are represent managed Docker plugins.
industrialedge Package industrialedge decorates the composer-project flavor of [Siemens Industrial Edge] apps (“IE apps”) when an IE App project is detected.	Package industrialedge decorates the composer-project flavor of [Siemens Industrial Edge] apps (“IE apps”) when an IE App project is detected.
kuhbernetes Package kuhbernetes provides Decorators for “recovering” Kubernetes pods from the containers found.	Package kuhbernetes provides Decorators for “recovering” Kubernetes pods from the containers found.
kuhbernetes/cri Package cri decorates Kubernetes pod groups discovered from CRI-managed containers, based on their CRI-related labels.	Package cri decorates Kubernetes pod groups discovered from CRI-managed containers, based on their CRI-related labels.
kuhbernetes/dockershim Package dockershim decorates Kubernetes pod groups discovered from Docker container names managed by the (in)famous Docker shim.	Package dockershim decorates Kubernetes pod groups discovered from Docker container names managed by the (in)famous Docker shim.
discover Package discover discovers [Linux kernel namespaces] of types cgroup, ipc, mount, net, pid, time, user, and uts.	Package discover discovers [Linux kernel namespaces] of types cgroup, ipc, mount, net, pid, time, user, and uts.
examples
barebones
lsallns
internal
gen/version
namespaces
pidmap Package pidmap translates process PIDs (and also task TIDs) between different PID namespaces.	Package pidmap translates process PIDs (and also task TIDs) between different PID namespaces.
log Package log allows consumers of the lxkns module to forward logging originating in the lxkns module to whatever logger module they prefer.	Package log allows consumers of the lxkns module to forward logging originating in the lxkns module to whatever logger module they prefer.
logrus Package logrus enables logging within the lxkns module and directs all logging output to the sirupsen/logrus logging module.	Package logrus enables logging within the lxkns module and directs all logging output to the sirupsen/logrus logging module.
model Package model defines the core of lxkns information model: Linux kernel namespaces and processes, and how they relate to each other; with the additional missing link between processes and user-land containers.	Package model defines the core of lxkns information model: Linux kernel namespaces and processes, and how they relate to each other; with the additional missing link between processes and user-land containers.
mounts Package mounts enhances the Linux kernel's mountinfo data model (as available through "/proc/[PID]/mountinfo") with mount point visibility (“overmounts”) and a hierarchical mount path tree.	Package mounts enhances the Linux kernel's mountinfo data model (as available through "/proc/[PID]/mountinfo") with mount point visibility (“overmounts”) and a hierarchical mount path tree.
nsioctl Package nsioctl defines namespace-related ioctl request values that aren't defined in the sys/unix standard package.	Package nsioctl defines namespace-related ioctl request values that aren't defined in the sys/unix standard package.
nstest Package nstest provides testing support in the context of Linux kernel namespaces.	Package nstest provides testing support in the context of Linux kernel namespaces.
gmodel Package gmodel provides Gomega matches for lxkns model elements.	Package gmodel provides Gomega matches for lxkns model elements.
ops Package ops provides a Golang-idiomatic API to the query and switching operations on Linux-kernel namespaces, hiding ioctl()s and syscalls.	Package ops provides a Golang-idiomatic API to the query and switching operations on Linux-kernel namespaces, hiding ioctl()s and syscalls.
internal/opener Package opener provides access to the file descriptors of namespace references.	Package opener provides access to the file descriptors of namespace references.
mountineer Package mountineer allows accessing the file system contents from (other) mount namespaces via procfs.	Package mountineer allows accessing the file system contents from (other) mount namespaces via procfs.
mountineer/mntnssandbox Package mntnssandbox is a single-purpose, stripped-down version of thediveo/gons.	Package mntnssandbox is a single-purpose, stripped-down version of thediveo/gons.
portable Package portable provides so-called “portable” namespace references with validation and “locking” to the referenced namespace open and thus alive.	Package portable provides so-called “portable” namespace references with validation and “locking” to the referenced namespace open and thus alive.
relations Package relations gives access to properties of and relationships between Linux-kernel namespaces, such as type and ID of a namespace, its owning user namespace, parent namespace in case of hierarchical namespaces, et cetera.	Package relations gives access to properties of and relationships between Linux-kernel namespaces, such as type and ID of a namespace, its owning user namespace, parent namespace in case of hierarchical namespaces, et cetera.
plural Package plural supplies lxkns with (only) English-language plurals for common objects appearing in the lxkns information model.	Package plural supplies lxkns with (only) English-language plurals for common objects appearing in the lxkns information model.
species Package species defines the type constants and type names of the currently 8 Linux kernel namespace types (“species”).	Package species defines the type constants and type names of the currently 8 Linux kernel namespace types (“species”).
test
cmd/loosethread Program loosethread creates a thread (task) that is attached to a newly created network namespace, without attaching this process' other tasks to the new network namespace.	Program loosethread creates a thread (task) that is attached to a newly created network namespace, without attaching this process' other tasks to the new network namespace.
containerdtest Package containerdtest is a poor-man's dockertest.	Package containerdtest is a poor-man's dockertest.
matcher Package matcher implements Gomega matchers for lxkns information model artifacts, such as containers and container groups (pods in particular).	Package matcher implements Gomega matchers for lxkns information model artifacts, such as containers and container groups (pods in particular).
success