debug-me - secure remote debugging
Debugging a problem over email is slow, tedious, and hard. The developer needs
to see the your problem to understand it. Debug-me aims to make debugging
fast, fun, and easy, by letting the developer access your computer remotely,
so they can immediately see and interact with the problem. Making your problem
their problem gets it fixed fast.
A debug-me session is logged and signed with the developer's GnuPG key,
producing a chain of evidence of what they saw and what they did. So the
developer's good reputation is leveraged to make debug-me secure. If you trust
a developer to ship software to your computer, you can trust them to debug-me.
When you start debug-me without any options, it will connect to a debug-me
server, and print out an url that you can give to the developer to get them
connected to you. Then debug-me will show you their GnuPG key and who has
signed it, and will let you know if they are a known developer of software on
your computer. If the developer has a good reputation, you can proceed to let
them type into your console in a debug-me session. Once the session is done,
the debug-me server will email you the signed evidence of what the developer
did in the session.
It's a good idea to watch the debug-me session. The developer should be running
their buggy program in different ways, perhaps running a debugger, or looking
at configuration files. They should *not* be looking at your personal files
without asking you first in the debug-me chat window. They should not be
downloading or installing other software. If you see them do anything you
don't expect, you can enter "/quit" in the control window to
immediately end the debug-me session.
If the developer did do something bad, you'd have proof that they cannot be
trusted, which you can share with the world. Knowing that is the case will
keep most developers honest.
- --run cmd
- Normally debug-me will run your login shell. To run some
other command, use this option.
- --use-server url
- Specify a debug-me server to use. Not normally needed since
there is a default server.
- Connect to a debug-me session on the specified url, to see
and interact with the user's bug. You need a GnuPG key to use this.
- --watch url
- Connect to a debug-me session on the specified url and
display what happens in the session. Your keystrokes will not be sent to
- debug-me uses a separate window than the one displaying the
debug-me session, to control the session. This control window is where
debug-me shows the user what developers want to connect to the session.
The user and developer can also chat using the control window.
- Normally, the control window will be opened when debug-me
starts, by running a terminal emulator (xterm or gnome-terminal, etc). If
debug-me is not being run in a graphical environment, that won't work, and
you'll need to open another shell prompt and run "debug-me
--control" to see it.
- --download url
- Download a debug-me log file from the specified url. Note
that if the debug-me session is still in progress, this will continue
downloading until the session ends. The signature chain in the log file is
verified as it is downloaded, but developer gpg signatures are not
- --replay logfile
- Replay a debug-me log file with realistic pauses.
- While this is running, you can press Space to skip forward
in the recording to the next point, which is useful when there are long
pauses in the recording.
- --verify logfile
- Verify that the log file contains a valid chain of hashes,
and valid signatures. Will exit nonzero if any problem is detected.
Displays the gpg public keys of any developers who interacted with the
- --graphviz logfile
- Uses graphviz to generate a visualization of a debug-me log
- Include hashes in the graphviz visualization.
- --server logdir
- Run a debug-me server, logging to the specified
- --port N
- Specify a port for the debug-me server to listen to.
- --from-email address
- The server will email session logs to users. It's a good
idea to provide a real email address, otherwise a dummy one will be used.
You can also set the enviroment variable DEBUG_ME_FROM_EMAIL to configure
- Normally the server will retain old log files so that users
and developers can refer to them. This option makes it delete the log file
once the session is done.
- Sessions are logged to here. The log file name is displayed
when debug-me exits.
- When using debug-me to connect to a remote session, the
session will be logged to here.
- When verifying a developer's gpg key, debug-me checks if
it's listed in the keyrings in this directory, which can be provided by
software installed on the computer.
Joey Hess <firstname.lastname@example.org>