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

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(+)

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
>

On Wednesday, February 26 2020, Ruslan Kabatsayev wrote:

> 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
> ).

Thanks.  I'll remove this part from the docs, then.