From: Sergio Durigan Junior <sergiodj@redhat.com>
To: GDB Patches <gdb-patches@sourceware.org>
Cc: Pedro Alves <palves@redhat.com>, Tom Tromey <tom@tromey.com>,
Kevin Buettner <kevinb@redhat.com>,
Sergio Durigan Junior <sergiodj@redhat.com>
Subject: [PATCH v2 5/5] Document Linux-specific possible ptrace restrictions
Date: Tue, 17 Mar 2020 11:47:19 -0400 [thread overview]
Message-ID: <20200317154719.2078283-6-sergiodj@redhat.com> (raw)
In-Reply-To: <20200317154719.2078283-1-sergiodj@redhat.com>
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 | 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:: GDB trace file format
* Index Section Format:: .gdb_index section format
* Man Pages:: Manual pages
@@ -45656,6 +45659,139 @@ 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 -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
--
2.24.1
next prev parent reply other threads:[~2020-03-17 15:47 UTC|newest]
Thread overview: 98+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-08-19 3:29 [PATCH] Improve ptrace-error detection on Linux targets Sergio Durigan Junior
2019-08-19 9:10 ` Ruslan Kabatsayev
2019-08-19 13:47 ` Sergio Durigan Junior
2019-08-19 14:57 ` Ruslan Kabatsayev
2019-08-19 16:30 ` Christian Biesinger via gdb-patches
2019-08-19 17:04 ` Sergio Durigan Junior
2019-08-19 14:33 ` Eli Zaretskii
2019-08-25 22:38 ` Sergio Durigan Junior
2019-08-19 18:26 ` Pedro Alves
2019-08-25 22:40 ` Sergio Durigan Junior
2019-08-26 18:32 ` [PATCH v2] " Sergio Durigan Junior
2019-08-26 18:35 ` Christian Biesinger via gdb-patches
2019-08-26 20:51 ` Sergio Durigan Junior
2019-08-26 18:44 ` Eli Zaretskii
2019-08-29 14:40 ` Pedro Alves
2019-08-29 19:27 ` Sergio Durigan Junior
2019-08-29 19:48 ` Sergio Durigan Junior
2019-08-30 19:03 ` Pedro Alves
2019-08-30 19:51 ` [PATCH] Remove "\nError: " suffix from nat/fork-inferior.c:trace_start_error warning message Sergio Durigan Junior
2019-08-30 19:54 ` Pedro Alves
2019-08-30 21:06 ` Sergio Durigan Junior
2019-08-30 12:45 ` [PATCH v2] Improve ptrace-error detection on Linux targets Pedro Alves
2019-09-04 19:21 ` Sergio Durigan Junior
2019-09-04 19:31 ` Sergio Durigan Junior
2019-09-04 19:58 ` Pedro Alves
2019-09-04 20:21 ` Sergio Durigan Junior
2019-09-04 20:35 ` Pedro Alves
2019-09-04 20:56 ` Sergio Durigan Junior
2019-09-04 21:23 ` Pedro Alves
2019-09-04 21:36 ` Sergio Durigan Junior
2019-09-05 12:19 ` Pedro Alves
2019-09-05 17:58 ` Sergio Durigan Junior
2019-08-30 12:47 ` Pedro Alves
2019-08-30 14:07 ` Eli Zaretskii
2019-08-30 19:44 ` Sergio Durigan Junior
2019-09-04 19:54 ` [PATCH v3] " Sergio Durigan Junior
2019-09-05 17:04 ` Eli Zaretskii
2019-09-11 1:11 ` [PATCH v4] " Sergio Durigan Junior
2019-09-12 12:39 ` Eli Zaretskii
2019-09-12 18:29 ` Sergio Durigan Junior
2019-09-24 20:40 ` Tom Tromey
2019-09-25 14:14 ` Sergio Durigan Junior
2019-09-25 22:04 ` Tom Tromey
2019-09-26 4:22 ` Sergio Durigan Junior
2019-09-26 4:22 ` [PATCH v5] " Sergio Durigan Junior
2019-09-26 17:32 ` Tom Tromey
2019-09-26 17:48 ` Pedro Alves
2019-09-26 17:51 ` Sergio Durigan Junior
2019-09-26 18:14 ` Pedro Alves
2019-09-26 18:25 ` Sergio Durigan Junior
2019-09-26 17:50 ` Sergio Durigan Junior
2019-09-26 18:13 ` Pedro Alves
2019-09-26 18:23 ` Sergio Durigan Junior
2020-02-26 20:06 ` [PATCH 0/6] Improve ptrace-error detection Sergio Durigan Junior
2020-02-26 20:06 ` [PATCH 2/6] Don't reset errno/bfd_error on 'throw_perror_with_name' Sergio Durigan Junior
2020-02-28 15:29 ` Tom Tromey
2020-02-28 16:36 ` Sergio Durigan Junior
2020-02-28 18:58 ` Tom Tromey
2020-02-28 19:50 ` Sergio Durigan Junior
2020-02-28 20:06 ` Pedro Alves
2020-02-28 20:35 ` Sergio Durigan Junior
2020-02-28 21:11 ` Pedro Alves
2020-03-02 20:07 ` Sergio Durigan Junior
2020-02-28 19:49 ` Pedro Alves
2020-02-28 20:01 ` Sergio Durigan Junior
2020-02-26 20:06 ` [PATCH 5/6] Document Linux-specific possible ptrace restrictions Sergio Durigan Junior
2020-02-26 21:00 ` Ruslan Kabatsayev
2020-02-26 22:08 ` Sergio Durigan Junior
2020-02-26 20:06 ` [PATCH 3/6] Expand 'fork_inferior' to check whether 'traceme_fun' succeeded Sergio Durigan Junior
2020-02-26 20:06 ` [PATCH 6/6] Fix comment for 'gdb_dlopen' Sergio Durigan Junior
2020-02-26 20:23 ` Christian Biesinger via gdb-patches
2020-02-26 20:49 ` Sergio Durigan Junior
2020-02-28 15:21 ` Tom Tromey
2020-02-28 16:05 ` Sergio Durigan Junior
2020-02-26 20:06 ` [PATCH 1/6] Introduce scoped_pipe.h Sergio Durigan Junior
2020-02-28 15:23 ` Tom Tromey
2020-02-28 16:08 ` Sergio Durigan Junior
2020-02-28 18:57 ` Tom Tromey
2020-02-28 19:48 ` Sergio Durigan Junior
2020-02-28 19:20 ` Pedro Alves
2020-02-28 19:47 ` Sergio Durigan Junior
2020-02-28 20:07 ` Pedro Alves
2020-02-26 20:06 ` [PATCH 4/6] Extend GNU/Linux to check for ptrace error Sergio Durigan Junior
[not found] ` <87v9nh3yme.fsf@redhat.com>
2020-03-15 4:21 ` [PATCH 0/6] Improve ptrace-error detection Sergio Durigan Junior
2020-03-15 21:16 ` Kevin Buettner
2020-03-17 15:47 ` [PATCH v2 0/5] " Sergio Durigan Junior
2020-03-17 15:47 ` [PATCH v2 1/5] Introduce scoped_pipe.h Sergio Durigan Junior
2020-03-17 15:47 ` [PATCH v2 2/5] Don't reset errno/bfd_error on 'throw_perror_with_name' Sergio Durigan Junior
2020-03-27 18:20 ` Pedro Alves
2020-03-17 15:47 ` [PATCH v2 3/5] Expand 'fork_inferior' to check whether 'traceme_fun' succeeded Sergio Durigan Junior
2020-03-27 4:14 ` Kevin Buettner
2020-03-27 13:06 ` Pedro Alves
2020-03-17 15:47 ` [PATCH v2 4/5] Extend GNU/Linux to check for ptrace error Sergio Durigan Junior
2020-03-27 15:28 ` Pedro Alves
2020-03-27 17:02 ` Kevin Buettner
2020-03-17 15:47 ` Sergio Durigan Junior [this message]
2020-03-20 0:53 ` [PATCH v2 0/5] Improve ptrace-error detection Kevin Buettner
2020-03-24 18:23 ` Sergio Durigan Junior
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200317154719.2078283-6-sergiodj@redhat.com \
--to=sergiodj@redhat.com \
--cc=gdb-patches@sourceware.org \
--cc=kevinb@redhat.com \
--cc=palves@redhat.com \
--cc=tom@tromey.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).