Re: [PATCH 5/6] Document Linux-specific possible ptrace restrictions

Ruslan Kabatsayev
2020-02-26T21:00:59Z

On Wed, 26 Feb 2020 at 23:06, Sergio Durigan Junior <sergiodj@redhat.com> wrote:
>
> This patch creates a new "Linux kernel ptrace restrictions" which
> documents possible causes that can be prevent the inferior from being
> correctly started/debugged.
>
> This has been pre-approved by Eli.
>
> gdb/doc/ChangeLog:
> yyyy-mm-dd Sergio Durigan Junior <sergiodj@redhat.com>
>
> * gdb.texinfo (Linux kernel ptrace restrictions): New appendix
> section.
> ---
> gdb/doc/gdb.texinfo | 143 ++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 143 insertions(+)
>
> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index f1798e35b5..a95158d5d3 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -182,6 +182,9 @@ software in general. We will miss him.
> @value{GDBN}
> * Operating System Information:: Getting additional information from
> the operating system
> +* Linux kernel ptrace restrictions:: Restrictions sometimes
> + imposed by the Linux
> + kernel on @code{ptrace}
> * Trace File Format:: GDB trace file format
> * Index Section Format:: .gdb_index section format
> * Man Pages:: Manual pages
> @@ -45629,6 +45632,146 @@ should contain a comma-separated list of cores that this process
> is running on. Target may provide additional columns,
> which @value{GDBN} currently ignores.
>
> +@node Linux kernel ptrace restrictions
> +@appendix Linux kernel @code{ptrace} restrictions
> +@cindex linux kernel ptrace restrictions, attach
> +
> +The @code{ptrace} system call is used by @value{GDBN} and
> +@code{gdbserver} on GNU/Linux to, among other things, attach to a new
> +or existing inferior in order to start debugging it. Due to security
> +concerns, some distributions and vendors disable or severely restrict
> +the ability to perform these operations, which can make @value{GDBN}
> +or @code{gdbserver} malfunction. In this section, we will expand on
> +how this malfunction can manifest itself, and how to modify the
> +system's settings in order to be able to use @value{GDBN} and
> +@code{gdbserver} properly.
> +
> +@menu
> +* The error message:: The error message displayed when the
> + system prevents @value{GDBN}
> + or @code{gdbserver} from using
> + @code{ptrace}
> +* SELinux's deny_ptrace:: SELinux and the @code{deny_ptrace} option
> +* Yama's ptrace_scope:: Yama and the @code{ptrace_scope} setting
> +* Docker and seccomp:: Docker and the @code{seccomp}
> + infrastructure
> +@end menu
> +
> +@node The error message
> +@appendixsection The error message
> +
> +When the system prevents @value{GDBN} or @code{gdbserver} from using
> +the @code{ptrace} system call, you will likely see a descriptive error
> +message explaining what is wrong and how to attempt to fix the
> +problem. For example, when SELinux's @code{deny_ptrace} option is
> +enabled, you can see:
> +
> +@smallexample
> +$ gdb program
> +...
> +(@value{GDBP}) run
> +Starting program: program
> +warning: Could not trace the inferior process.
> +Error:
> +warning: ptrace: Permission denied
> +The SELinux 'deny_ptrace' option is enabled and preventing @value{GDBN}
> +from using 'ptrace'. You can disable it by executing (as root):
> +
> + setsebool deny_ptrace off
> +
> +If you are debugging the inferior remotely, the instruction(s) above must
> +be performed in the target system (e.g., where GDBserver is running).
> +During startup program exited with code 127.
> +(@value{GDBP})
> +@end smallexample
> +
> +Sometimes, it may not be possible to acquire the necessary data to
> +determine the root cause of the failure. In this case, you will see a
> +generic error message pointing you to this section:
> +
> +@smallexample
> +$ gdb program
> +...
> +Starting program: program
> +warning: Could not trace the inferior process.
> +Error:
> +warning: ptrace: Permission denied
> +There might be restrictions preventing ptrace from working. Please see
> +the appendix "Linux kernel ptrace restrictions" in the GDB documentation
> +for more details.
> +During startup program exited with code 127.
> +(@value{GDBP})
> +@end smallexample
> +
> +@node SELinux's deny_ptrace
> +@appendixsection SELinux's @code{deny_ptrace}
> +@cindex SELinux
> +@cindex deny_ptrace
> +
> +If you are using SELinux, you might want to check whether the
> +@code{deny_ptrace} option is enabled by doing:
> +
> +@smallexample
> +$ getsebool deny_ptrace
> +deny_ptrace --> on
> +@end smallexample
> +
> +If the option is enabled, you can disable it by doing, as root:
> +
> +@smallexample
> +# setsebool deny_ptrace off
> +@end smallexample
> +
> +The option will be disabled until the next reboot. If you would like
> +to disable it permanently, you can do (as root):
> +
> +@smallexample
> +# setsebool -P deny_ptrace off
> +@end smallexample
> +
> +@node Yama's ptrace_scope
> +@appendixsection Yama's @code{ptrace_scope}
> +@cindex yama, ptrace_scope
> +
> +If your system has Yama enabled, you might want to check whether the
> +@code{ptrace_scope} setting is enabled by checking the value of
> +@file{/proc/sys/kernel/yama/ptrace_scope}:
> +
> +@smallexample
> +$ cat /proc/sys/kernel/yama/ptrace_scope
> +0
> +@end smallexample
> +
> +If you see anything other than @code{0}, @value{GDBN} or
> +@code{gdbserver} can be affected by it. You can temporarily disable
> +the feature by doing, as root:
> +
> +@smallexample
> +# sysctl kernel.yama.ptrace_scope=0
> +kernel.yama.ptrace_scope = 0
> +@end smallexample
> +
> +You can make this permanent by doing, as root:
> +
> +@smallexample
> +# sysctl -w kernel.yama.ptrace_scope=0
> +kernel.yama.ptrace_scope = 0
> +@end smallexample

Actually, sysctl's "-w" option doesn't make the setting permanent. It
just lets one write the value. sysctl(8) says about the
"variable=value" syntax:
> This requires the -w parameter to use.
Though I've found that omitting "-w" works exactly the same on
procps-ng 3.3.9 — checked with strace, which gives identical output in
both cases.
In any case, to make this permanent, one has to modify /etc/sysctl.*
locations (namely, on Ubuntu 14.04 it's /etc/sysctl.d/10-ptrace.conf
).

> +
> +@node Docker and seccomp
> +@appendixsection Docker and @code{seccomp}
> +@cindex docker, seccomp
> +
> +If you are using Docker (@uref{https://www.docker.com/}) containers,
> +you will probably have to disable its @code{seccomp} protections in
> +order to be able to use @value{GDBN} or @code{gdbserver}. To do that,
> +you can use the options @code{--cap-add=SYS_PTRACE --security-opt
> +seccomp=unconfined} when invoking Docker:
> +
> +@smallexample
> +$ docker run --cap-add=SYS_PTRACE --security-opt seccomp=unconfined
> +@end smallexample
> +
> @node Trace File Format
> @appendix Trace File Format
> @cindex trace file format
> --
> 2.24.1
>