summaryrefslogtreecommitdiffhomepage
path: root/debug-me.1
blob: 4640ff1960e5a801dfb392eea11752c6cfc46a32 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
.\" -*- 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.
If you trust a developer to ship software to your computer,
you can trust them to debug-me.
.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, 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.
.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, you can enter "/quit" in the control
window 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 "--run cmd"
Normally debug-me will run your login shell. To run some other command,
use this option.
.IP "--use-server url"
Specify a debug-me server to use. Not normally needed since there is a
default server.
.SH DEVELOPER OPTIONS
.IP url
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.
.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 COMMON SESSION OPTIONS
.IP "--control"
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.
.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 prompt and
run "debug-me --control" to see it.
.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
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.
.IP "--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 debug-me 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"
Specify a port for the debug-me server to listen to.
.IP "--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
this.
.IP "--delete-old-logs"
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.
.SH FILES
.IP "~/.debug-me/log/"
Sessions are logged to here. The log file name is displayed when debug-me
exits.
.IP "~/.debug-me/log/remote/"
When using debug-me to connect to a remote session, the session will be
logged to here.
.IP "/usr/share/debug-me/keyring/*.gpg"
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.
.SH SEE ALSO
<https://debug-me.branchable.com/>
.PP
.BR gnupg (1)
.SH AUTHOR 
Joey Hess <id@joeyh.name>