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

[Sergio Durigan Junior <sergiodj@redhat.com>]

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.

-- 
Sergio
GPG key ID: 237A 54B1 0287 28BF 00EF  31F4 D0EB 7628 65FC 5E36
Please send encrypted e-mail if possible
http://sergiodj.net/