Message ID | 20200226200542.746617-6-sergiodj@redhat.com |
---|---|
State | New |
Headers | show |
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.
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 + +@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