diff options
Diffstat (limited to 'gdb/doc')
| -rw-r--r-- | gdb/doc/ChangeLog | 5 | ||||
| -rw-r--r-- | gdb/doc/gdb.texinfo | 143 |
2 files changed, 148 insertions, 0 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 0a10fa3..003c8c2 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,8 @@ +2019-09-26 Sergio Durigan Junior <sergiodj@redhat.com> + + * gdb.texinfo (Linux kernel ptrace restrictions): New appendix + section. + 2019-09-20 Ulrich Weigand <uweigand@de.ibm.com> * doc/gdb.texinfo (Remote Configuration): Remove documentation for diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index f2713c0..e7b5b18 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 @@ -44665,6 +44668,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 + +@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 |