Skip to content
GitLab
Commit d07d9c5a authored by Matt Traudt's avatar Matt Traudt
Browse files

Breakup part of readme into install and deploy docs 

Thanks teor and juga for feedback!
parent e590ffcb
Hide whitespace changes
Inline Side-by-side
DEPLOY.rst 0 → 100644
View file @ d07d9c5a
Deploying Simple Bandwidth Scanner
----------------------------------
.. todo::
Determine if the helper exit can specify 127.0.0.1 as the location of
the sbws server. Replace all instances of **XX1** with the answer.
.. todo::
Determine if the sbws client and server can be on the same machine.
Replace all instances of **XX2** with the answer.
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:
::
[helpers]
mine = on
john = on
.. note ::
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.
::
[helpers.mine]
relay = 6B4ABE3FA1D4D0D4AEF2FD6C535891333591D06E
server_host = freebird.system33.pw
server_port = 31648
password = G5YqRhj6J28UFIZzg2TI9ENL6kWZCt7qMsFnpLDVAQMZsgUnrbZIoJtkd4WpjzEf
[helpers.john]
relay = 09FA8B4F665AD65D2C2A49870F1AA3BA8811E449
server_host = stanmarsh.system33.pw
server_port = 31648
password = 6me6bTM7I4yDdzJ6cjZR0PUx5APFvpOLovA2NzNvyWigI3y42bQXDnB3JrG5kprq
.. note ::
``server_host`` can be an IP address. IPv4 will work, IPv6 is untested
**XX1**
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 ... ]
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 ServerMachine** ...
Recall that ServerMachine 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 33.33.33.33:31648
ExitPolicy reject *:*
# End modifications needed for a non-exit sbws helper relay
Replace ``33.33.33.33`` with the IP address of this machine.
**XX1**
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 0.0.0.0/8:*
ExitPolicy reject 169.254.0.0/16:*
ExitPolicy reject 127.0.0.0/8:*
ExitPolicy reject 192.168.0.0/16:*
ExitPolicy reject 10.0.0.0/8:*
ExitPolicy reject 172.16.0.0/12:*
[ ... Your usual ExitPolicy options should be here, then ... ]
ExitPolicy accept 33.33.33.33:31648
ExitPolicy reject *:*
# End exit relay config and modifications needed for an exit sbws helper relay
Again, replacing ``33.33.33.33`` with the IP address of this machine.
**XX1**
Once you are done editing your torrc, reload Tor. Make sure Tor is still
running.
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.
::
[server]
bind_ip = 33.33.33.33
**XX1**
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.
::
[server.passwords]
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 ClientMachine** ...
Once all the sbws servers that you want to use are running, you can run
``sbws client`` in screen, tmux, or something like that.
INSTALL.rst 0 → 100644
View file @ d07d9c5a
Installing Simple Bandwidth Scanner
-----------------------------------
First, clone the repo. Then
::
virtualenv -p python3 venv
source venv/bin/activate
pip install .
sbws init
sbws client -h
sbws server -h
README.md
View file @ d07d9c5a
......@@ -74,17 +74,6 @@ a backward incompatible way.
This project is released to the public domain under the CC0 1.0 Universal
license. See [`LICENSE.md`](/LICENSE.md) for more information.
## Installing
Clone the repo
virtualenv -p python3 venv
source venv/bin/activate
pip install .
sbws init
sbws client -h
sbws server -h
## Authenticating to `sbws server`
**XXX Write this.**
......@@ -129,173 +118,6 @@ 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:
[helpers]
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.
[helpers.mine]
relay = 6B4ABE3FA1D4D0D4AEF2FD6C535891333591D06E
server_host = freebird.system33.pw
server_port = 31648
password = G5YqRhj6J28UFIZzg2TI9ENL6kWZCt7qMsFnpLDVAQMZsgUnrbZIoJtkd4WpjzEf
[helpers.john]
relay = 09FA8B4F665AD65D2C2A49870F1AA3BA8811E449
server_host = stanmarsh.system33.pw
server_port = 31648
password = 6me6bTM7I4yDdzJ6cjZR0PUx5APFvpOLovA2NzNvyWigI3y42bQXDnB3JrG5kprq
(Note that `server_host` can be an IP address. IPv4 will work, IPv6 is
untested)
(**XXX Can it be 127.0.0.1 ???**)
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 33.33.33.33:31648
ExitPolicy reject *:*
# End modifications needed for a non-exit sbws helper relay
Replace `33.33.33.33` 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 0.0.0.0/8:*
ExitPolicy reject 169.254.0.0/16:*
ExitPolicy reject 127.0.0.0/8:*
ExitPolicy reject 192.168.0.0/16:*
ExitPolicy reject 10.0.0.0/8:*
ExitPolicy reject 172.16.0.0/12:*
[ ... Your usual ExitPolicy options should be here, then ... ]
ExitPolicy accept 33.33.33.33:31648
ExitPolicy reject *:*
# End exit relay config and modifications needed for an exit sbws helper relay
Again, replacing `33.33.33.33` 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
running.
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.
[server]
bind_ip = 33.33.33.33
**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.
[server.passwords]
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]
......
docs/source/DEPLOY.rst 0 → 120000
View file @ d07d9c5a
../../DEPLOY.rst
\ No newline at end of file
docs/source/INSTALL.rst 0 → 120000
View file @ d07d9c5a
../../INSTALL.rst
\ No newline at end of file
docs/source/index.rst
View file @ d07d9c5a
......@@ -12,6 +12,8 @@ Welcome to Simple Bandwidth Scanner's documentation!
:caption: Contents:
specification
INSTALL
DEPLOY
README
AUTHORS
sbws
......
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