From d605fdc0bbed885a003a8c42c53ce3dfadf07c49 Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Fri, 28 Apr 2017 11:39:25 -0400 Subject: improved description and man page documenting well ahead of implementation now --- debug-me.1 | 64 ++++++++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 46 insertions(+), 18 deletions(-) (limited to 'debug-me.1') diff --git a/debug-me.1 b/debug-me.1 index ee12326..6b332aa 100644 --- a/debug-me.1 +++ b/debug-me.1 @@ -5,48 +5,76 @@ debug-me \- secure remote debugging .SH SYNOPSIS .B debug-me [options] .SH DESCRIPTION -.I debug-me -`debug-me` lets a developer access your computer remotely, to debug a problem, -avoiding a tedious back-and-forth by email. When you start `debug-me`, it -starts a shell, and generates an URL which you can give to the developer -(or developers) to connect them to the session. +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 -It's not normally a good idea to let someone run commands in a shell on -your computer. To make this as safe as possible, debug-me uses the -GPG web of trust. Everything the developer sends to debug-me is signed -with their GPG key, in a way that produces a GPG signed proof of what the -developer saw, and what they did in the debug-me session. -If the developer does something Evil, you have the neccessary proof -to adjust their reputation. +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 -.SH OPTIONS +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 "--". -.PP .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 proof chain in the log file is verified +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 "--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. .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" -- cgit v1.2.3