From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from us-smtp-delivery-74.mimecast.com (us-smtp-delivery-74.mimecast.com [63.128.21.74]) by sourceware.org (Postfix) with ESMTP id 1E2E93871026 for ; Tue, 17 Mar 2020 15:47:34 +0000 (GMT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-126-lfzQD48iP5eh2svJyt-LQg-1; Tue, 17 Mar 2020 11:47:29 -0400 X-MC-Unique: lfzQD48iP5eh2svJyt-LQg-1 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 22FED107ACC9; Tue, 17 Mar 2020 15:47:28 +0000 (UTC) Received: from psique.yyz.redhat.com (unused-10-15-17-54.yyz.redhat.com [10.15.17.54]) by smtp.corp.redhat.com (Postfix) with ESMTP id 87BCC10027A7; Tue, 17 Mar 2020 15:47:27 +0000 (UTC) From: Sergio Durigan Junior To: GDB Patches Cc: Pedro Alves , Tom Tromey , Kevin Buettner , Sergio Durigan Junior Subject: [PATCH v2 5/5] Document Linux-specific possible ptrace restrictions Date: Tue, 17 Mar 2020 11:47:19 -0400 Message-Id: <20200317154719.2078283-6-sergiodj@redhat.com> In-Reply-To: <20200317154719.2078283-1-sergiodj@redhat.com> References: <20200226200542.746617-1-sergiodj@redhat.com> <20200317154719.2078283-1-sergiodj@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: quoted-printable X-Spam-Status: No, score=-25.2 required=5.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 17 Mar 2020 15:47:35 -0000 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 =09* gdb.texinfo (Linux kernel ptrace restrictions): New appendix =09section. --- gdb/doc/gdb.texinfo | 136 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 385c832f22..0a6c6f6df6 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::=09=09GDB trace file format * Index Section Format:: .gdb_index section format * Man Pages::=09=09=09Manual pages @@ -45656,6 +45659,139 @@ should contain a comma-separated list of cores th= at this process is running on. Target may provide additional columns, which @value{GDBN} currently ignores. =20 +@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 t= he + 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} s= etting +* 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 -w kernel.yama.ptrace_scope=3D0 +kernel.yama.ptrace_scope =3D 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=3DSYS_PTRACE --security-opt +seccomp=3Dunconfined} when invoking Docker: + +@smallexample +$ docker run --cap-add=3DSYS_PTRACE --security-opt seccomp=3Dunconfined +@end smallexample + @node Trace File Format @appendix Trace File Format @cindex trace file format --=20 2.24.1