path: root/debug-me.1

.\" -*- nroff -*-
.TH debug-me 1 "Commands"
.SH NAME
debug-me \- secure remote debugging
.SH SYNOPSIS
.B debug-me [options]
.SH DESCRIPTION
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.
.PP
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.
.PP
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. 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.
.PP
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, press Control-S immediately, which
will prevent them from doing anything else. You can also press
Control-Backslash to immediately end the debug-me session.
.PP
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.
.SH USER OPTIONS
.IP "-- cmd opts"
Normally debug-me will run your login shell. To run some other command,
pass the command and any options after "--".
.IP "--gpg-opt=option"
debug-me runs gpg to verify the GPG key of a developer. To pass options to
gpg, use --gpg-opt with the option to pass. For example:
--gpg-opt=--keyserver=pgpkeys.mit.edu
This can be done multiple times.
.IP "--control"
debug-me uses a separate window from the one displaying the debug-me
session to control the session. This control window is where debug-me will
show you the Gnupg keys of developers who connect and let you decide if
they should access the session. You can also chat with the developer
in the control window during the session.
.IP
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 and run "debug-me --control" to see it.
.SH DEVELOPER OPTIONS
.IP "--debug url"
Connect to a debug-me session on the specified url. The developer runs
debug-me with this option to see and interact with the user's bug.
.IP "--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 the session.
.SH LOG FILE OPTIONS
.IP "--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 verified.
.IP "--replay logfile"
Replay a debug-me log file with realistic pauses.
.IP "--graphviz logfile"
Uses graphviz to generate a visualization of a debug-me log file.
.IP "--show-hashes"
Include hashes in the graphviz visualization.
.SH SERVER OPTIONS
.IP "--server logdir"
Run a debug-me server, logging to the specified directory.
.IP "--port N"
Specify a port for the debug-me server to listen to.
.SH SEE ALSO
<https://debug-me.branchable.com/>
.SH AUTHOR 
Joey Hess <id@joeyh.name>