Commit e590ffcb authored by Matt Traudt's avatar Matt Traudt
Browse files

Write first run docs, with notes for futher investigation

parent 5f88bfde
......@@ -129,6 +129,173 @@ In this directory you will find
them into this directory. Other sbws commands (such as generate and stats)
read results from the files in this directory.
## Running sbws for the first time
So you want to run sbws for yourself. You will need
- A machine to measure from, hereafter referred to as *mach-client*.
- One or more machines to measure to, hereafter referred to as *mach-server*.
Both mach-server and mach-client should be on fast, well connected machines.
(**XXX can they be on the same machine?**) The *mach-server* should be on a
machine that is also running a Tor relay, and that Tor relay should be okay
with modifying its exit policy to allow exiting to one local IP on one port
(note that the relay will *not* get the Exit flag). Together, the sbws server
and the Tor relay it is running next to (ideally on the same machine) are
referred to as a *helper*.
First install sbws as described elsewhere. Make sure you can run `sbws client
-h` and `sbws server -h` without error before moving on.
**On mach-client** ...
For each helper you intend to use, generate a 64 character password. Set these
aside for now in a temporary file. Be ready to copy/paste them. Here we
generate two passwords and store them in a temporary file, annotating which
helper they are for.
$ export pwfile=/tmp/sbws-passwords.txt
$ echo "#Helper Mine" > $pwfile
$ sbws pwgen | tee -a $pwfile
$ echo "#Helper John" >> $pwfile
$ sbws pwgen | tee -a $pwfile
Now that you have those, open your sbws config file. By default it is located
in `~/.sbws/config.ini`. *If it does not exist, something went wrong, most
likley while calling `sbws init`*.
In the `[client]` section, give your client a better nickname.
Create a `[helpers]` section. For every helper you intend to use, add a line to
the section. For example, if I plan on using a helper I'm running and one that
John is running, I would add the following:
mine = on
john = on
(Note that you can disable helpers without removing them from the config by
switching "on" to "off")
For every enabled helper, you now need a section for them. In it we give the
details for the helper relay and its sbws server. This is where you'll need
those passwords you generated earlier.
relay = 6B4ABE3FA1D4D0D4AEF2FD6C535891333591D06E
server_host =
server_port = 31648
password = G5YqRhj6J28UFIZzg2TI9ENL6kWZCt7qMsFnpLDVAQMZsgUnrbZIoJtkd4WpjzEf
relay = 09FA8B4F665AD65D2C2A49870F1AA3BA8811E449
server_host =
server_port = 31648
password = 6me6bTM7I4yDdzJ6cjZR0PUx5APFvpOLovA2NzNvyWigI3y42bQXDnB3JrG5kprq
(Note that `server_host` can be an IP address. IPv4 will work, IPv6 is
(**XXX Can it be ???**)
At this point you are done on mach-client for now. You should verify that the
configuration is most likely valid by running a simple sbws command and seeing
if it complains. The following indicates there is no problem.
$ sbws
usage: sbws [-h] [-v] [-q] [-d DIRECTORY]
{client,generate,init,pwgen,server,stats} ...
[ ... more help output ... ]
While the following indicates there is an issue in your config.
$ sbws
[2018-04-06 08:38:29.122616] [error] [MainThread] client/nickname (Bad_NickName): Letter _ at position 3 is not in allowed characters "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
[2018-04-06 08:38:29.122678] [error] [MainThread] helpers.mine is an enabled helper but is not a section in the config
**On mach-server** ...
Recall that mach-server is the machine running a Tor relay and the one were we
are about to set up an sbws server.
Minor modifications need to be made to the relay's torrc. Assuming this is a
non-exit relay and you do not want that to change, we need to allow exiting to
a single IP and port, and that IP is on the local machine. This requires a few
torrc options.
# Modifications needed for a non-exit sbws helper relay
ExitRelay 1
ExitPolicyRejectPrivate 0
ExitPolicy accept
ExitPolicy reject *:*
# End modifications needed for a non-exit sbws helper relay
Replace `` with the IP address of this machine. (**XXX can
localhost be used?**)
If this is an exit relay, you will still need to set
`ExitPolicyRejectPrivate 0` and allow exiting to a local IP address on a single
port; however, *you should take care to block exiting to the rest of local
address space*. By default Tor would do that for you, but you must now do it
manually. The exit part of your torrc should look something like this.
# Exit relay config with modifications needed to run an sbws helper relay
ExitRelay 1
ExitPolicyRejectPrivate 0
ExitPolicy reject*
ExitPolicy reject*
ExitPolicy reject*
ExitPolicy reject*
ExitPolicy reject*
ExitPolicy reject*
[ ... Your usual ExitPolicy options should be here, then ... ]
ExitPolicy accept
ExitPolicy reject *:*
# End exit relay config and modifications needed for an exit sbws helper relay
Again, replacing `` with the IP address of this machine.
(**XXX can localhost be used?**)
Once you are done editing your torrc, reload Tor. Make sure Tor is still
It's finally time to get to configuring sbws. Open its config file, located at
`~/.sbws/config.ini` by default. *If this directory or file does not exist,
you probably haven't initialized sbws or something went wrong when you did. The
file should not be empty.*
Add a `[server]` section to the config and tell sbws to bind to the IP address
for this machine.
bind_ip =
**XXX Again, can this be localhost?**
Now it's time to tell the sbws which clients we want to allow to use our
server. Gather the 64 character passwords from all the clients you want to
allow and add them to a new `[server.passwords]` section.
alice = joyrsUxkpvrlt6ZNxXyP4stdMGohZ5OwyqawvMhevzKq2gDFYjWUSsxMQeG5iIRY
bob = Ll22MSLm1DOGYXw74c2vyCbnLtRidgaAb7pAOLua62pYoAx8PsTsaC3BN7QUdD4N
mine = G5YqRhj6J28UFIZzg2TI9ENL6kWZCt7qMsFnpLDVAQMZsgUnrbZIoJtkd4WpjzEf
(Note if you would like to disallow a client from using your server without
removing their password completely, comment out their line in this section and
restart the sbws server)
To check if the config is valid, run `sbws` and check that you get normal usage
output as described earlier while setting up the sbws client.
Once the config is valid, you should be ready to to run `sbws server` in
screen, tmux, or something like that.
**On the mach-client** ...
Once all the sbws servers that you want to use are running, you can run
`sbws client` in screen, tmux, or something like that.
## Build HTML documentation
pip install -e .[doc]
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment