.. _deploy:

Deploying Simple Bandwidth Scanner
=====================================

To run sbws is needed:

- A machine to run the :term:`scanner`.
- One or more :term:`destination` (s) that serve a large file.

Both the ``scanner`` and your the ``destination`` (s) should be on fast,
well connected machines.

.. _destinations_requirements:

destination requirements
------------------------------------

- A Web server installed and running that supports HTTP GET, HEAD and
  Range (:rfc:`7233`) requests.
  ``Apache`` HTTP Server and ``Nginx`` support them.

  Note that if the server is configured with ``keep-alive`` timeout, it'd need
  to be at least the same timeout as in the sbws HTTP requests, which is 10
  seconds by default (``http_timeout`` variable in the configuration file, see
  more about in the next section).
- TLS support to avoid HTTP content caches at the various exit nodes.
- Certificates can be self-signed.
- A large file; at the time of writing, at least 1 GiB in size
  It can be created running::

      head -c $((1024*1024*1024)) /dev/urandom > 1GiB

- A fixed IP address or a domain name.
- Bandwidth: at least 12.5MB/s (100 Mbit/s).
- Network traffic: around 12-15GB/day.

If you want, use a `Content delivery network`_ (CDN) in order to make the
destination IP closer to the scanner exit.

scanner setup
----------------------

.. note:: To facilitate debugging, it is recommended that the system timezone
   is set to UTC.

To set the timezone to UTC in Debian::

  apt-get --reinstall install tzdata
  ln -sf /usr/share/zoneinfo/UTC /etc/localtime
  update-initramfs -u

Install sbws according to `<INSTALL.rst>`_ (in the local directory or Tor
Project Gitlab) or `<INSTALL.html>`_  (local build or Read the Docs).

To run the ``scanner`` it is mandatory to create a configuration file with at
least one ``destination``.
It is recommended to set several ``destinations`` so that the ``scanner`` can
continue if one fails.

If ``sbws`` is installed from the Debian package, then create the configuration
file in ``/etc/sbws/sbws.ini``.
You can see an example with all the possible options here, note that you don't
need to include all of that and that everything that starts with ``#`` and
``;`` is a comment:

.. literalinclude:: /examples/sbws.example.ini
    :caption: Example sbws.example.ini

If ``sbws`` is installed from the sources as a non-root user then create the
configuration file in ``~/.sbws.ini``.

More details about the configuration file can be found in
``./docs/source/man_sbws.ini.rst`` (in the local directory or Tor Project
Gitlab) or `<man_sbws.ini.html>`_  (local build or Read the Docs) or
``man sbws.ini`` (system package).

generator setup
---------------

The Debian package also includes a cron job to run the ``generator``.
If sbws is installed in some other way, there should be cron job. For example::

  35 *     * * *   sbws  /usr/local/bin/sbws -c /etc/sbws/sbws.ini generate
  05 0     * * *   sbws  /usr/local/bin/sbws -c /etc/sbws/sbws.ini cleanup

(Note that there is also a command to clean the old data).

If the cron job is configured to send Email alerts on errors, it's probably
better to configure the log level to ``ERROR`` instead of ``WARNING``.

At level ``WARNING``, the first days, the ``generator`` will log every hour
that it hasn't reached enough percentage of relays to report.
After some days, if the scanner is located near fasts exits, it would also log
every hour that it is reporting more than the 50% of the consensus bandwidth.

The log level can be changed in the configuration file, for example::

  to_stdout_level = error

This setup will affect both to the ``generator`` and the ``scanner``, so for
Email alerts, it's probably more convenient to configure it from the command
line, for example::

  /usr/local/bin/sbws --log-level error generate


See also ``./docs/source/man_sbws.rst`` (in the local directory or Tor Project
Gitlab) or `<man_sbws.html>`_ (local build or Read the Docs) or ``man sbws``
(system package).

.. _Content delivery network: https://en.wikipedia.org/wiki/Content_delivery_network
