add

1 files changed, 104 insertions, 0 deletions

diff --git a/doc/faq.mdwn b/doc/faq.mdwn
new file mode 100644
index 0000000..b819332
--- /dev/null
+++ b/doc/faq.mdwn
@@ -0,0 +1,104 @@
+[[!toc]]
+
+### for users
+
+#### Should I let John Doe connect to my debug-me session? I don't know that guy.
+
+When a developer connects to your debug-me session, it will display
+their Gnupg key, and the number of people who have signed it. It will
+also list the names of some of those people (the best connected ones).
+
+If the developer of software you use is connecting to debug-me,
+their software documentation might say what their Gnupg key is. Then you
+can simply check that the Gnupg key ids match.
+
+If debug-me says that "John Doe is probably a real person", it means
+that he's connected to the strong set of the Gnupg web of trust.
+Other people, who certianly are real, have verified his identity.
+So even if you don't know his name, it can be safe to let him connect.
+
+But it's a gut call. If in doubt, don't let the developer connect.
+
+If debug-me says "identity cannot be verified!", it means that the Gnupg
+key couldn't be downloaded at all, or the developer is not connected to the
+strong set of the Gnupg web of trust. Be super wary in this case.
+
+#### I don't feel comfortable letting someone run commands on my computer. Can I still use debug-me?
+
+You can, just answer "n" when it asks if you want to let a developer
+run commands. The developer who connected to your debug-me session will
+still be able to see what you do in the session, so you can show them
+what they need to see to understand the bug.
+
+This is less efficient though. The developer will have to explain to you
+what to do, instead of just doing it. It will probably be harder for them
+to quickly get a grasp of the problem.
+
+Also, this can be less secure than letting the developer type stuff!
+Consider: The developer could ask you to run some complex command you've
+never heard of. Maybe that command will do something bad. Then there's
+no proof that the developer tricked you into doing that. If you use
+debug-me to let them type, there would be a proof of anything bad they did.
+
+#### How does debug-me prove when the developer uses it to do something bad?
+
+The debug-me session log file records everything the developer saw and did
+in a debug-me session. Each keystroke they sent is signed with their Gnupg
+key, and is part of a signed chain of activities. By examining this
+evidence, it can be cryptographically proven that the developer did what
+they did.
+
+For this to work, you have to have a copy of the session log file. This is
+why the debug-me server will email it to you at the end of the session, to
+make sure you get a copy.
+
+### for developers
+
+#### What do I need to do to start using debug-me?
+
+Here's a quick checklist:
+
+* Make a Gnupg key, if you don't already have one.
+* Get it signed by at least one person who's connected to the strong
+  set of the Gnupg web of trust. The more signatures the better.
+  Keysigning parties are great.
+* Include your Gnupg key id in your project's documentation, so users
+  will know which key is yours. It also helps to sign git tags,
+  tarballs, git commits, etc with your key.
+* When a user has a bug that you need more information to reproduce and
+  understand, ask if they'll use debug-me.
+
+#### What should I do and not do in a debug-me session?
+
+You're a guest in the user's computer, and your every move is being
+recorded as evidence. Act acordingly. Ask for permission, not forgiveness.
+
+Avoid looking at personal files unncessarily, and ask permission if you
+need to in order to investigate the bug.
+
+Never delete or modify their personal files. 
+
+Don't download software. Don't try to sudo to root, etc.
+
+#### Seems some of my keystrokes are not getting through to the user?
+
+Due to the way debug-me's proof chains work ([[details|protocol]]), this
+will sometimes happen, when you are typing faster than the roundtrip latency
+to the user. debug-me will beep when this happens (but a lot of modern
+terminal emulators don't sound beeps).
+
+This shouldn't be a problem, even at high latency, when you're typing
+at the shell prompt, but it may make using editors etc hard when latency
+is high.
+
+If a keystroke doesn't get though, wait a second and try it again,
+then it generally will.
+
+#### Any other terminal related problems I might encounter?
+
+If you're going to edit a file, etc it helps to have your terminal set to
+the same (or larger) number of lines and columns as the user's terminal.
+Run `echo $LINES $COLUMNS` in their shell to find the values there.
+
+It can sometimes be useful to `export TERM=vt100` in the user's shell
+to avoid any differences in terminal emulation.