Options¶

--container container-id, -C container-id

Identify the container in which to execute the shell process.

--shell shell-path, -S shell-path

Specify the path to an alternative shell binary. This can be useful if the target container does not have /bin/bash (or possibly even dynamic libraries). In this case, you could install a statically linked shell binary such as busybox in your calling context, and invoke ns-exec --shell /usr/bin/busybox-static. ns-exec will then try to execute the busybox image inside the target container (using execveat(2)).

--export host-path:container-path, -M host-path:container-path

This option allows you to provide additional tooling in the container you wish to inspect, such as strace or vi. When given this option, ns-exec will attempt to mount the given host-path (in the host namespace) on directory container-path inside the container namespace.

Several directories can be exported by providing --export repeatedly.

These mounts will only be visible to your diagnostic shell; the mount namespace of the application(s) running inside the container will not be polluted. When you exit the diagnostic shell, these mounts will disappear in a puff of kernel logic.

Two caveats apply. Firstly, the container-path mount point is expected to exist; it is not created on the fly. Second, this mechanism can currently only be used to export files to the container. Due to the way this directory is set up inside the container, changes made to them will not be propagated back to the host.

So in particular, if you collect log files in the container and later wish to export them, writing them to an exported directory is not the right approach. This is what the --savelogs option is for.

--savelogs directory

This option enables you to save log files from within the container to a designated directory in the host context. In order to use this facility, you need the savelog(1) helper program accessible inside the container (for example, by exporting it to your shell session via --export).

--debug, -d

Enable debugging (currently somewhat terse). If no log file is specified, information is written to ns-exec.log in the current working directory.

--logfile filename, -L filename

Specify a file to which debugging information is logged.

Diagnostic Standalone Container¶

With this setup, you would create a container including the ns-exec utility (and possibly other useful stuff), and run it with full privilege, sharing the pid namespace with the host:

podman run --privileged --cap-add=all --pid=host -it my-container

If you now attach to your diagnostic container, ns-exec should be able to see (and enter) all containers running on this host.

Diagnostic Sidecar Container¶

With this approach, you would create a pod that includes the original container, plus your diagnostic container, for instance like this:

podman pod create --name sleuth --share=pid
id1=$(podman create --pod=sleuth --name=sleuth.main orig-container)
id2=$(podman create --pod=sleuth --name=sleuth.sidecar --privileged=true my-container)
podman pod start sleuth

If you now attach to the sidecar container, ns-exec should be able to see (and enter) just the container you wish to debug.