FAQ for dumps

In order to implement dump collection, .NET processes spawn a child process called createdump. This child process uses the Linux API ptrace() and also reads from the /proc filesystem to access thread and memory data that is written into the dump file. Although the API usage is allowed by the default security settings on many Linux distros, sometimes a less common security configuration will deny access. You might see output from the createdump process written on the console of the application being dumped such as:

[createdump] The process or container does not have permissions or access: open(/proc/1234/mem) FAILED Permission denied (13)

One reason that access can be denied is if a security sandbox intercepts the call using a seccomp BPF filter. For applications running in a container using Open Container Initiative technology, the seccomp profile must allow for calls to ptrace. For example, Docker uses containerd under the hood as a container runtime. When initializing, it specifies a default seccomp profile that allows ptrace only if the container host has a kernel version higher than 4.8 or if the CAP_SYS_PTRACE capability was specified on the container.

If the calls aren't intercepted, then the kernel does a variety of built-in access checks. The docs for ptrace() include a detailed description near the end, titled "Ptrace access mode checking", that describes how these are done. Accessing the /proc filesystem also uses a variation of the same ptrace access mode checking. What follows is an abbreviated summary of the security checks performed and places where access might be denied:

• Either the calling process needs to have the same user ID as the target process, or the calling process needs to have CAP_SYS_PTRACE. If neither of these is true, access is denied. Since the .NET runtime doesn't do anything to change the user account when launching createdump, the user IDs should match and this step should succeed.
• If createdump doesn't have CAP_SYS_PTRACE (it doesn't by default), then the target process being dumped needs to be marked "dumpable". By default, most processes on Linux are dumpable, but you can change this setting by calling prctl() with the PR_SET_DUMPABLE option. If you add capabilities to a process using the setcap tool, this can also cause a process to stop being dumpable. For a more detailed description of the dumpable setting and what causes it to be disabled, see the Linux documentation.
• All of the enabled Linux security modules (LSMs) are enumerated and each of them must approve the access. Unfortunately, if an LSM denies the access, there's no uniform Linux reporting mechanism to know which one is responsible. Instead you need to determine which ones are enabled on your system and then investigate each individually. You can determine which LSMs are active by running: cat /sys/kernel/security/lsm. Although any LSM could be responsible, Yama, SELinux, and AppArmor are frequently the relevant ones.

AppArmor and SELinux both have rich configuration and reporting mechanisms, so if you need to learn how to work with them, it's best to view each project's own documentation. Yama only has a single configuration setting, which can be displayed by running:

cat /proc/sys/kernel/yama/ptrace_scope

This command outputs a number indicating the current Yama ptrace security policy:

• 0: Classic ptrace permissions.
• 1: Restricted ptrace.
• 2: Admin-only attach.
• 3: No attach.

Yama should grant access for createdump under policies 0 and 1, but expect access will be denied under policies 2 and 3. Policy 3 always denies access, and policy 2 doesn't work by default because createdump normally does not have the capability CAP_SYS_PTRACE.

Some Linux-based systems are configured with security policies that require any process collecting a dump to have the capability CAP_SYS_PTRACE. Normally processes do not have this capability but running elevated is one way to enable it. For a fuller description of how Linux security policies impact dump collection, see 'Why is dump collection failing on Linux?'.

For applications running under any Open Container Initiative technology, the seccomp profile must allow for calls to ptrace(). For example, Docker uses containerd under the hood as a container runtime. When initializing the runtime, it specifies a default seccomp profile that allows ptrace only if the container host has a kernel version higher than 4.8 or if the CAP_SYS_PTRACE capability was specified.

For a fuller description of how Linux security policies impact dump collection, see the question 'Why is dump collection failing on Linux?'.

On macOS the use of ptrace requires the host of the target process to be properly entitled. For information about the minimum required entitlements, see Default entitlements.

Here are some additional resources:

• Debug Linux dumps
• Debug a deadlock in a .NET app

On Linux, the DOTNET_ROOT environment variable must point to the correct folder when set. When it points to another .NET version, dotnet-dump always produces this error. When the DOTNET_ROOT environment variable isn't set, a different error is produced ("You must install .NET to run this application").