Commit 93207b81 authored by Matt Traudt's avatar Matt Traudt
Browse files


parent ff355bd6
Deploying Simple Bandwidth Scanner
.. todo::
Determine if the sbws client and server can be on the same machine.
Replace all instances of **XX2** with the answer.
.. todo:: mark the terms here as terms for :doc:`glossary`?
.. note:: maybe add here terms from :doc:`glossary`?
So you want to run sbws for yourself. You will need
- A machine to measure from, hereafter referred to as *ClientMachine*.
- One or more machines to measure to, hereafter referred to as *ServerMachine*.
Both ServerMachine and ClientMachine should be on fast, well connected machines.
**XX2** The *ServerMachine* 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 in :doc:`/INSTALL`. Make sure you can run ``sbws client
-h`` and ``sbws server -h`` without error before moving on.
**On ClientMachine** ...
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
likely 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
- A machine to measure from, hereafter referred to as |scanner_nick|.
- One or more webservers hosting a large file, hereafter referred to as
.. note ::
Both |scanner_nick| and your |dests| should be on fast, well connected
You can disable helpers without removing them from the config by switching
"on" to "off"
|scanner_nick| requirements
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.
- A fast, well connected machine on the Internet. Ideally its bandwidth should
not be a limiting factor in measurements.
- Linux host OS
- Python 3, virtualenv
- Tor installed with ``tor`` in your ``PATH``
relay = 6B4ABE3FA1D4D0D4AEF2FD6C535891333591D06E
server_host =
server_port = 31648
password = G5YqRhj6J28UFIZzg2TI9ENL6kWZCt7qMsFnpLDVAQMZsgUnrbZIoJtkd4WpjzEf
relay = 09FA8B4F665AD65D2C2A49870F1AA3BA8811E449
server_host =
server_port = 31648
password = 6me6bTM7I4yDdzJ6cjZR0PUx5APFvpOLovA2NzNvyWigI3y42bQXDnB3JrG5kprq
.. note ::
``server_host`` can be an IP address. IPv4 will work. IPv6 will work
without ``[brackets]``
At this point you are done on ClientMachine 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 ... ]
|dests| requirements
While the following indicates there is an issue in your config.
- A fast, well connected machine on the Internet. Ideally its bandwidth should
not be a limiting factor in measurements.
- Some sort of webserver installed and running that supports HEAD and GET
requests (apache and nginx fit this description)
- Optional support for TLS
- A large file; at the time of writing, at least 1 GiB in size
|scanner_nick| setup
$ 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 ServerMachine** ...
Install sbws according to :doc:`/INSTALL`.
Recall that ServerMachine is the machine running a Tor relay and the one were we
are about to set up an sbws server.
Make sure you have initialized sbws. If you haven't already run ``sbws init``,
then enter your virtualenv and run it.
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.
Inside |dotsbws| you will find ``config.ini``. Open it with a text editor. it
should be very simple. Let's give our scanner a nickname. Add the following
# 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.
nickname = D0ntD3@dOpen!nside
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.
(Pick your own nickname. This one just demonstrates that you can use almost any
Congratulations, you've learned how to add a section to your config file and
how to add an option to a section.
# 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.
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.
Remeber |dests|? We need to add them to ``config.ini``. We're going to assume
you have two you are ready to use and one that isn't quite ready yet.
bind_ip =
You can set the ``bind_ip`` to ```` if you would like. It does not need
to be reachable from the Internet, so you probably want to make sure your
firewall does not allow incoming connections to sbws server's port.
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::
foo = on
bar = on
baz = off
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
url =
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.
url =
Once the config is valid, you should be ready to to run ``sbws server`` in
screen, tmux, or something like that.
url =
**On the ClientMachine** ...
``foo`` demonstrates a typical case.
Once all the sbws servers that you want to use are running, you can run
``sbws client`` in screen, tmux, or something like that.
``bar`` demonstrates a case where you want to use HTTPS and want to assume the
large file for sbws to download is at its default path (probably
.. _deploy_generate:
``baz`` demonstrates a disabled destination that sbws will ignore.
.. todo:: document when should be run ``sbws generate``, whether it should be
add to a cron, etc...
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