|
| 1 | +--- |
| 2 | +title: .NET dumps FAQ |
| 3 | +description: Get answers to frequently asked questions about dumps in .NET. |
| 4 | +ms.date: 02/05/2025 |
| 5 | +ms.topic: faq |
| 6 | +ms.custom: linux-related-content |
| 7 | +--- |
| 8 | + |
| 9 | +# .NET Dumps - Frequency Asked Questions |
| 10 | + |
| 11 | +## Why is dump collection failing on Linux? |
| 12 | + |
| 13 | +In order to implement dump collection, .NET processes spawn a child process called createdump. This child process uses the Linux API [ptrace()](https://www.man7.org/linux/man-pages/man2/ptrace.2.html) and also reads from the [/proc](https://www.kernel.org/doc/html/latest/filesystems/proc.html) 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 may see output from the createdump process written on the console of the application being dumped such as: |
| 14 | + |
| 15 | +``` |
| 16 | +[createdump] The process or container does not have permissions or access: open(/proc/1234/mem) FAILED Permission denied (13) |
| 17 | +``` |
| 18 | + |
| 19 | +One reason that access may be denied is because a security sandbox intercepts the call using a [seccomp BPF filter](https://www.kernel.org/doc/html/v4.19/userspace-api/seccomp_filter.html). 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](https://github.com/moby/containerd) under the hood as a container runtime. When initializing, it specifies a default [seccomp profile](https://github.com/moby/moby/blob/master/profiles/seccomp/default.json) 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. |
| 20 | + |
| 21 | +If the calls aren't intercepted then the kernel will do a variety of built-in access checks. The docs for [ptrace()](https://www.man7.org/linux/man-pages/man2/ptrace.2.html) includes a detailed description near the bottom 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. This is an abbreviated summary of the security checks performed and some likely places where access might be denied: |
| 22 | + |
| 23 | +1. 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. |
| 24 | +2. 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 this setting can be changed by calling [prctl()](https://www.man7.org/linux/man-pages/man2/prctl.2.html) 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. See [the Linux documentation](https://www.man7.org/linux/man-pages/man2/PR_SET_DUMPABLE.2const.html) for a more detailed description of the dumpable setting and what causes it to be disabled. |
| 25 | +3. All of the enabled [Linux security modules](https://www.kernel.org/doc/html/v4.16/admin-guide/LSM/index.html) (LSMs) are enumerated and each of them must approve the access. Unforetunately if an LSM denies the access there is 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](https://www.kernel.org/doc/html/v4.16/admin-guide/LSM/Yama.html), [SELinux](https://selinuxproject.org/page/Main_Page), and [AppArmor](https://gitlab.com/apparmor/apparmor/-/wikis/GettingStarted) are frequently the relevant ones. |
| 26 | + |
| 27 | +AppArmor and SELinux both have a rich configuration and reporting mechanisms so its best to view each project's own documentation if you need to learn how to work with them. Yama only has a single configuration setting that can be displayed by running: |
| 28 | + |
| 29 | +``` |
| 30 | +cat /proc/sys/kernel/yama/ptrace_scope |
| 31 | +``` |
| 32 | + |
| 33 | +This will output a number indicating the current Yama ptrace security policy: |
| 34 | +0: Classic ptrace permissions. |
| 35 | +1: Restricted ptrace. |
| 36 | +2: Admin-only attach. |
| 37 | +3: No attach. |
| 38 | + |
| 39 | +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. |
| 40 | + |
| 41 | +## Why do I only get dumps on Linux if [dotnet-dump](dotnet-dump.md) or my [crashing process](collect-dumps-crash.md) is running elevated? |
| 42 | + |
| 43 | +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. See 'Why is dump collection failing on Linux?' above for a fuller description about how Linux security policies impact dump collection. |
| 44 | + |
| 45 | +## Why can't I collect dumps when running inside a container? |
| 46 | + |
| 47 | +For applications running under any Open Container Initiative technology, the `seccomp` profile must allow for calls to [ptrace()](https://www.man7.org/linux/man-pages/man2/ptrace.2.html). For example, `Docker` uses [containerd](https://github.com/moby/containerd) under the hood as a container runtime. When initializing the runtime, it specifies a default [seccomp profile](https://github.com/moby/moby/blob/master/profiles/seccomp/default.json) 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. |
| 48 | + |
| 49 | +See the question above 'Why is dump collection failing on Linux?' for a fuller description of how Linux security policies impact dump collection. |
| 50 | + |
| 51 | +## Why can't I collect dumps on macOS? |
| 52 | + |
| 53 | +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](../install/macos-notarization-issues.md#default-entitlements). |
| 54 | + |
| 55 | +## Where can I learn more about how I can leverage dumps to help diagnose problems in my .NET application? |
| 56 | + |
| 57 | +Here are some additional resources: |
| 58 | + |
| 59 | +- [Debug Linux dumps](debug-linux-dumps.md) |
| 60 | +- [Debug a deadlock in a .NET app](debug-deadlock.md) |
| 61 | + |
| 62 | +## How can I solve "It was not possible to find any compatible framework version"? |
| 63 | + |
| 64 | +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"). |
0 commit comments