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, debug-me will display their GnuPG key, and information about it, including the number of people who have signed it. It will also list the names of some of those people (the best connected ones).

Suppose you're using Debian, and debug-me says "John Doe is a Debian developer". Then it's probably safe to let this person connect, because you already trust this guy implicitly, since you're using software he develops.

How does debug-me know that John Doe is a Debian developer? It's checked that his gpg key is in the keyring at /usr/share/debug-me/keyring/a_Debian_developer.gpg, which is provided by Debian. Other software projects that are installed on your computer can also put keyrings in that directory, and then debug-me will be able to tell then a developer of a project is connecting.

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. That means: 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 if in doubt, don't let him.

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.

To verify a session log file, run: debug-me --verify debug-me.log That will display the gpg key of the developer who was active in that session, and verify the integrety of the log file.

A debug-me log file can be replayed by running: debug-me --reply debug-me.log

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.

• Make your software package install a gpg keyring of its developers to /usr/share/debug-me/keyring/.

  A file there named "a_Foo_developer.gpg" will make debug-me tell the user that "Your Name is a Foo developer." when you connect to their debug-me session, and so the user will be more likely to trust you and let you connect.

  For example:

  gpg --export-options export-minimal --export C910D9222512E3C7 > a_Foo_developer.gpg

• 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.

Don't share the log of your debug-me session without getting the user's approval, as it might contain information they wish to remain private.

Seems some of my keystrokes are not getting through to the user?

Due to the way debug-me's proof chains work (details), 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.