From patchwork Wed Feb 26 20:05:41 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sergio Durigan Junior X-Patchwork-Id: 38332 Received: (qmail 102544 invoked by alias); 26 Feb 2020 20:06:41 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Delivered-To: mailing list gdb-patches@sourceware.org Received: (qmail 102498 invoked by uid 89); 26 Feb 2020 20:06:41 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-16.7 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, RCVD_IN_DNSWL_NONE autolearn=ham version=3.3.1 spammy=columns, Pages, docker, Man X-HELO: us-smtp-delivery-1.mimecast.com Received: from us-smtp-1.mimecast.com (HELO us-smtp-delivery-1.mimecast.com) (205.139.110.61) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Wed, 26 Feb 2020 20:06:30 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1582747588; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=2+XXclPiX1V64CTGl/127yb8HMUyuvF3sPcEKXel0q0=; b=YDAtHg5JV6DrqZaK1jfhIuwEqRPTGjTun8yoFe5SG78qKjGhKJsjBT/7jXBw7afdJDsl/m laFFWXKfZs7RZ9PbjBl33nGWAcWDrOhEUhRYbkqe+iRwCBY51+5eDsm6RrslQyuMulUwRA 2zyAMFh5mu8W/R8iHQPmTwhHxWObp5w= 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-284-piLEwD1XNuami7EJwfnRpg-1; Wed, 26 Feb 2020 15:06:22 -0500 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id CEC56800EBB; Wed, 26 Feb 2020 20:06:21 +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 30B795DA76; Wed, 26 Feb 2020 20:06:21 +0000 (UTC) From: Sergio Durigan Junior To: GDB Patches Cc: Pedro Alves , Tom Tromey , Eli Zaretskii , Ruslan Kabatsayev , Sergio Durigan Junior Subject: [PATCH 5/6] Document Linux-specific possible ptrace restrictions Date: Wed, 26 Feb 2020 15:05:41 -0500 Message-Id: <20200226200542.746617-6-sergiodj@redhat.com> In-Reply-To: <20200226200542.746617-1-sergiodj@redhat.com> References: <20190926042155.31481-1-sergiodj@redhat.com> <20200226200542.746617-1-sergiodj@redhat.com> MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-IsSubscribed: yes 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 * 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 + +@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