Hi Karel,
I've created a simple GDB sessions design document including my ideas
from last few days. It most probably needs extending, could you please
review?
Thanks,
Michal
======================================================================
GDB session design
======================================================================
GDB session is an extension to Retrace Server that allows real-time
remote debugging of coredumps.
----------------------------------------------------------------------
Contents
----------------------------------------------------------------------
1. Overview
2. Interface
2.1 Beginning a session
2.2 Communicating with GDB
2.3 Terminating a session
2.4 Limitting traffic
3. Security
----------------------------------------------------------------------
1. Overview
----------------------------------------------------------------------
The client starts a retrace task by sending coredump to the Retrace
Server. After finishing the task standard backtrace is generated, but
the chroot is not cleaned up and is ready to begin GDB session.
The client can send GDB commands to the server which forwards them
to remote GDB prompt and provides the response back to client. After
finishing the GDB session, chroot is cleaned up.
----------------------------------------------------------------------
2. Interface
----------------------------------------------------------------------
The handler is a WSGI script similar to existing Retrace Server's
actions (create, backtrace etc.). In favor of higher performance HTTPS
may be disabled on a trusted network, however it is highly recommended
to use it because of security reasons.
----------------------------------------------------------------------
2.1 Beginning a session
----------------------------------------------------------------------
The client begins a standard "create" action by sending an HTTP
request to http(s)://someserver/create. The request must include
"X-Task-Type" header containing the constant value TASK_GDB. After
receiving the request, the server runs a standard task but exists
before cleaning up the chroot, setting task status to
"FINISHED_SUCCESS". This means the standard backtrace has been
generated and the chroot is ready to begin real-time debugging.
----------------------------------------------------------------------
2.2 Communicating with GDB
----------------------------------------------------------------------
The client may request the output of a GDB command(s) by sending HTTP
POST request to http(s)://someserver/<id>/gdb URL, where <id> is
the numerical task id returned in the "X-Task-Id" header by
http(s)://someserver/create. If the <id> is not in the valid format,
or the task <id> does not exist, the server must return
the "404 Not Found" HTTP error code. If the request does not use POST
method, the server must return the "405 Method Not Allowed" HTTP error
code.
The request must contain the "X-Task-Password" header, and its
value must match the password stored for task <id>. If the header
is not present or its value is not valid, the server must return
the "403 Forbidden" HTTP error code.
If the task <id> was not created with TASK_GDB type, the server must
return the "406 Not Acceptable" HTTP error code.
If the task <id> was created with TASK_GDB type, but the session has
either been terminated by the user or garbage collected, the server
must return the "410 Gone" HTTP error code.
The request must contain a proper "Content-Length" and "Content-Type"
headers. If the "Content-Length" header is missing, the server must
return the "411 Length Required" HTTP error code. If
the "Content-Type" is other than "text/plain", the server must return
the "415 Unsupported Media Type" HTTP error code. If
the "Content-Length" value is greater than a limit set in the server
configuration file (1 kB by default), the server must return
the "413 Request Entity Too Large" HTTP error code and provide
an explanation. The limit can be checked by calling
http(s)://someserver/settings. The limit is changeable from the server
configuration file.
The request body must contain proper GDB command(s): not all of them
are allowed to run on the server (see chapter 3. Security). If
the commands are malformed or contain some forbidden command,
the server must return "403 Forbidden" HTTP error code. Multiple
commands are delimited by the newline character. The server executes
all specified commands as one batch. A new instance of GDB is spawned
for every separate request. The command list does not need to include
"file" or "core-file" commands. These are called automatically by
the server at the beginning of every batch.
If the batch is successfully forwarded to GDB, the server must return
"200 OK" HTTP status code and the response body must contain GDB's
output (both stdout and stderr).
----------------------------------------------------------------------
2.3 Terminating a session
----------------------------------------------------------------------
The client may terminate a session by sending a single "quit" command
to GDB. After receiving this, the server cleans up the chroot
and the GDB session is no longer available.
If the user does not send any command to GDB for a time period
specified in server configuration file (4 hours by default),
the garbage collector (retrace-server-cleanup) must clean up
the chroot automatically on its next execution.
----------------------------------------------------------------------
2.4 Limitting traffic
----------------------------------------------------------------------
The task is considered active during the "create" phase. Global limits
for maximum simultaneous tasks are applied.
Once the "create" phase of the session is finished, the task is no
longer considered active and does not limit other "create" requests.
The number of unterminated (created but not terminated nor garbage
collected) GDB sessions is limited by the value set in the server
configuration file (3 by default).
If a new TASK_GDB request comes while all slots for such tasks are
occupied, the server must return the "503 Service Unavailable" HTTP
error code.
----------------------------------------------------------------------
3. Security
----------------------------------------------------------------------
The server calls GDB within chroot, with no root privileges. Although
the user has no root priviliges within chroot or host system, he may
use GDB "shell" command to read system devices (such as /dev/random)
or commands "+", "-" etc., which are using ncurses and thus do not
produce the suitable plain text output. This is why only a subset of
GDB commands needs to be whitelisted: "print", "info", TODO: whatever?
Coredumps and GDB output may contain sensitive data such as
passwords, credit card numbers etc., that's why it is strictly
recommended to use HTTPS to communicate with the client.
Coredumps are kept within the chroot, which is basically readeble for
everybody. The coredumps must only be readable by the mockbuild user.
There is no need to write SELinux policy. The server operates within
mock chroot which has its policy available.
