[Pkg-privacy-commits] [onionbalance] 110/117: Major restructure of the documentation
Donncha O'Cearbahill
donncha-guest at moszumanska.debian.org
Wed Dec 16 23:18:55 UTC 2015
This is an automated email from the git hooks/post-receive script.
donncha-guest pushed a commit to branch debian/sid
in repository onionbalance.
commit 9003f6148dc76b30046c61c4727346b59ea0473f
Author: Donncha O'Cearbhaill <donncha at donncha.is>
Date: Mon Dec 14 22:22:36 2015 +0100
Major restructure of the documentation
Reword and restructured much of the documentation. Created pages
for the `onionbalance` and `onionbalance-config` tools which can
used for generating man pages.
---
README.rst | 113 ++------------------
docs/changelog.rst | 6 ++
docs/conf.py | 243 +++++-------------------------------------
docs/getting-started.rst | 107 +++++++++++++++++++
docs/index.rst | 49 ++++++---
docs/installation.rst | 35 ++++++
docs/onionbalance-config.rst | 59 ++++++++++
docs/running-onionbalance.rst | 131 +++++++++++++++++++++++
docs/use-cases.rst | 40 +++++++
tox.ini | 1 +
10 files changed, 450 insertions(+), 334 deletions(-)
diff --git a/README.rst b/README.rst
index a140a7e..d394048 100644
--- a/README.rst
+++ b/README.rst
@@ -4,116 +4,23 @@ OnionBalance
Introduction
------------
-The OnionBalance software allows for Tor hidden service requests to be distributed across multiple backend Tor instances. OnionBalance provides load-balancing while also making onion services more resilient and reliable by eliminating single points-of-failure.
+The OnionBalance software allows for Tor hidden service requests to be
+distributed across multiple backend Tor instances. OnionBalance provides
+load-balancing while also making onion services more resilient and reliable
+by eliminating single points-of-failure.
-* `Documentation <https://onionbalance.readthedocs.org>`_
-* `Code <https://github.com/DonnchaC/onionbalance/>`_
-* `Bug Tracker <https://github.com/DonnchaC/onionbalance/issues>`_
+- Latest release: |version| (:ref:`changelog`)
+- GitHub: https://github.com/DonnchaC/onionbalance/
+- Issue tracker: https://github.com/DonnchaC/onionbalance/issues
+- PyPI: https://pypi.python.org/pypi/OnionBalance
+- IRC: #onionbalance @ OFTC
|build-status| |docs|
Getting Started
---------------
-OnionBalance requires a system which runs the OnionBalance management server and up to 10 backend servers which run onion services that serve the desired content (web site, IRC server etc.).
-
-Installing OnionBalance
-~~~~~~~~~~~~~~~~~~~~~~~
-
-::
-
- $ pip install onionbalance
-
-or
-
-::
-
- $ git clone https://github.com/DonnchaC/onionbalance.git
- $ cd onionbalance
- $ python setup.py install
-
-The management server does not need to be installed on the same systems that host the backend onion service instances.
-
-
-Configuring the OnionBalance management server
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The bundled ``onionbalance-config`` tool is the fastest way to generate the necessary keys and config files to get your onion service up and running.
-
-::
-
- $ onionbalance-config
-
-The config generator runs in an interactive mode when called without any arguments. The ``master`` directory should be stored on the management server while the other instance directories should be transferred to the respective backend servers.
-
-
-Configuring Tor on the management server
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-OnionBalance requires that a recent version of Tor (>= 0.2.7.1-alpha) is installed on the management server system. This versions of Tor is not yet available from the Tor repositories yet and must be compiled from source.
-
-::
-
- $ wget https://www.torproject.org/dist/tor-0.2.7.1-alpha.tar.gz
- $ tar -xzvf tor-0.2.7.1-alpha.tar.gz && cd tor-0.2.7.1-alpha
- $ ./configure --disable-asciidoc && sudo make install
-
-The Tor config file at ``onionbalance/data/torrc-server`` can be used for the management server. The ``onionbalance-config`` tool also outputs a suitable Tor config file as ``master/torrc-server``.
-
-::
-
- $ tor -f torrc-server
-
-Configuring the backend onion service instances
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Each backend instance should be run a standard onion service which serves your website or other content. More information about configuring onion services is available in the Tor Project's `hidden service configuration guide <https://www.torproject.org/docs/tor-hidden-service.html.en>`_.
-
-If you have used the ``onionbalance-config`` tool you should transfer the generated instance config files and keys to the respective backend servers. You can then start the onion service instance by simply running:
-
-::
-
- $ tor -f instance_torrc
-
-OnionBalance config file
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-The OnionBalance management server must have access to the private key for the master onion service. This master private key determines the address that users will use to access your onion service. This private key must be kept secure.
-
-The location of the private key must be specified as relative or absolute path under ``key`` in the config file. Each backend Tor onion service instance is listed by it's unique onion address in the ``instances`` list.
-
-An example config file is provided in `config.example.yaml <onionbalance/data/config.example.yaml>`_. If you have used the ``onionbalance-config`` tool you can simply use the generated config file at ``master/config.yaml``.
-
-Running
-~~~~~~~
-
-
-You can start the management server once your backend onion service instances are running. The management server must be left running to publish descriptors for your onion service.
-
-::
-
- $ onionbalance -c config.yaml
-
-Multiple OnionBalance management servers can be run to make your service more resilient and remove a single point of failure. Each redundant server should be run with the same private key and config file.
-
-Use Cases
----------
-
-- A popular onion service with an overloaded web server or Tor process
-
- A service such as Facebook which gets a large number of users would like to distribute client requests across multiple servers as the load is too much for a single Tor instance to handle. They would also like to balance between instances when the 'encrypted services' proposal is implemented [2555].
-
-- Redundancy and automatic failover
-
- A political activist would like to keep their web service accessible and secure in the event that the secret police seize some of their servers. Clients should ideally automatically fail-over to another online instances with minimal service disruption.
-
-- 'Shared Hosting' scenarios
-
- A hosting provider wishes to allow their customers to access their shared hosting control panel over an encrypted onion service. Rather than creating an individual onion service (with corresponding overhead) for thousands of customers, the host could instead run one onion service. Multiple service descriptors could then be published under unique customer onion addresses which would then be routed to that users control panel. This could also enable a low-resourced OnionFlare-type implem [...]
-
-- Secure Onion Service Key storage
-
- An onion service operator would like to compartmentalize their permanent onion key in a secure location separate to their Tor process and other services. With this proposal permanent keys could be stored on an independent, isolated system.
+Installation and usage documentation is available at https://onionbalance.readthedocs.org.
Contact
-------
diff --git a/docs/changelog.rst b/docs/changelog.rst
new file mode 100644
index 0000000..503cb1a
--- /dev/null
+++ b/docs/changelog.rst
@@ -0,0 +1,6 @@
+.. _changelog:
+
+Change Log
+==========
+
+.. include:: ../CHANGES.rst
diff --git a/docs/conf.py b/docs/conf.py
index c1c26a2..63614ef 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -51,10 +51,11 @@ needs_sphinx = '1.1'
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
+ 'alabaster',
'sphinx.ext.autodoc',
'sphinx.ext.todo',
'sphinx.ext.viewcode',
- 'sphinx.ext.doctest',
+ 'sphinxcontrib.autoprogram',
]
# Add any paths that contain templates here, relative to this directory.
@@ -73,7 +74,9 @@ master_doc = 'index'
# General information about the project.
project = 'OnionBalance'
-copyright = '{}, {}'.format(datetime.datetime.now().year, __author__)
+
+# Remove copyright notice for man page
+copyright = ''
author = __author__
# The version info for the project you're documenting, acts as replacement for
@@ -81,7 +84,7 @@ author = __author__
# built documents.
#
# The short X.Y version.
-version = __version__[:__version__.rfind(".")]
+version = __version__
# The full version, including alpha/beta/rc tags.
release = __version__
@@ -102,21 +105,6 @@ language = 'en'
# directories to ignore when looking for source files.
exclude_patterns = ['_build', 'modules.rst']
-# The reST default role (used for this markup: `text`) to use for all
-# documents.
-#default_role = None
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
-
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
@@ -139,7 +127,12 @@ html_theme = 'alabaster'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
-#html_theme_options = {}
+html_theme_options = {
+ "description": "Load balancing and redundancy for Tor hidden services.",
+ 'github_user': 'DonnchaC',
+ 'github_repo': 'onionbalance',
+ 'travis_button': True,
+}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
@@ -155,226 +148,44 @@ html_short_title = "OnionBalance Docs"
# of the sidebar.
#html_logo = None
-# The name of an image file (within the static path) to use as favicon of the
-# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#html_favicon = None
-
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = []
-# Add any extra paths that contain custom files (such as robots.txt or
-# .htaccess) here, relative to this directory. These files are copied
-# directly to the root of the documentation.
-#html_extra_path = []
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#html_additional_pages = {}
+html_sidebars = {
+ '**': [
+ 'about.html',
+ 'navigation.html',
+ 'relations.html',
+ ]
+}
# If false, no module index is generated.
-#html_domain_indices = True
-
-# If false, no index is generated.
-#html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
+html_domain_indices = False
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
html_show_sphinx = False
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it. The value of this option must be the
-# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
-
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = None
-
-# Language to be used for generating the HTML full-text search index.
-# Sphinx supports the following languages:
-# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
-# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
-#html_search_language = 'en'
-
-# A dictionary with options for the search language support, empty by default.
-# Now only 'ja' uses this config value
-#html_search_options = {'type': 'default'}
-
-# The name of a javascript file (relative to the configuration directory) that
-# implements a search results scorer. If empty, the default will be used.
-#html_search_scorer = 'scorer.js'
+html_show_copyright = False
# Output file base name for HTML help builder.
htmlhelp_basename = 'onionbalancedoc'
-# -- Options for LaTeX output ---------------------------------------------
-
-latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
-
-# The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
-
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
-
-# Latex figure (float) alignment
-#'figure_align': 'htbp',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-# author, documentclass [howto, manual, or own class]).
-latex_documents = [
- (master_doc, 'onionbalance.tex', 'OnionBalance Documentation',
- [author], 'manual'),
-]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = False
-
-# If true, show page references after internal links.
-#latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-#latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-#latex_domain_indices = True
-
-
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- (master_doc, 'OnionBalance', 'OnionBalance Documentation',
- ['%s (%s)' % (__author__, __contact__)], 1)
+ ('running-onionbalance', 'onionbalance',
+ 'a Tor hidden service load balancer',
+ ['%s <%s>' % (__author__, __contact__)], 1),
+ ('onionbalance-config', 'onionbalance-config',
+ 'tool for generating onionbalance config files and keys',
+ ['%s <%s>' % (__author__, __contact__)], 1),
]
# If true, show URL addresses after external links.
#man_show_urls = False
-
-
-# -- Options for Texinfo output -------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-# dir menu entry, description, category)
-texinfo_documents = [
- (master_doc, 'OnionBalance', 'OnionBalance Documentation',
- author, 'OnionBalance', 'Tool for distributing Tor onion services '
- 'connections to multiple backend Tor instances', 'Miscellaneous'),
-]
-
-# Documents to append as an appendix to all manuals.
-#texinfo_appendices = []
-
-# If false, no module index is generated.
-#texinfo_domain_indices = True
-
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-#texinfo_show_urls = 'footnote'
-
-# If true, do not generate a @detailmenu in the "Top" node's menu.
-#texinfo_no_detailmenu = False
-
-
-# -- Options for Epub output ----------------------------------------------
-
-# Bibliographic Dublin Core info.
-epub_title = project
-epub_author = author
-epub_publisher = author
-epub_copyright = copyright
-
-# The basename for the epub file. It defaults to the project name.
-#epub_basename = project
-
-# The HTML theme for the epub output. Since the default themes are not optimized
-# for small screen space, using the same theme for HTML and epub output is
-# usually not wise. This defaults to 'epub', a theme designed to save visual
-# space.
-#epub_theme = 'epub'
-
-# The language of the text. It defaults to the language option
-# or 'en' if the language is not set.
-#epub_language = ''
-
-# The scheme of the identifier. Typical schemes are ISBN or URL.
-#epub_scheme = ''
-
-# The unique identifier of the text. This can be a ISBN number
-# or the project homepage.
-#epub_identifier = ''
-
-# A unique identification for the text.
-#epub_uid = ''
-
-# A tuple containing the cover image and cover page html template filenames.
-#epub_cover = ()
-
-# A sequence of (type, uri, title) tuples for the guide element of content.opf.
-#epub_guide = ()
-
-# HTML files that should be inserted before the pages created by sphinx.
-# The format is a list of tuples containing the path and title.
-#epub_pre_files = []
-
-# HTML files shat should be inserted after the pages created by sphinx.
-# The format is a list of tuples containing the path and title.
-#epub_post_files = []
-
-# A list of files that should not be packed into the epub file.
-epub_exclude_files = ['search.html']
-
-# The depth of the table of contents in toc.ncx.
-#epub_tocdepth = 3
-
-# Allow duplicate toc entries.
-#epub_tocdup = True
-
-# Choose between 'default' and 'includehidden'.
-#epub_tocscope = 'default'
-
-# Fix unsupported image types using the Pillow.
-#epub_fix_images = False
-
-# Scale large images.
-#epub_max_image_width = 0
-
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-#epub_show_urls = 'inline'
-
-# If false, no index is generated.
-#epub_use_index = True
diff --git a/docs/getting-started.rst b/docs/getting-started.rst
new file mode 100644
index 0000000..a296bde
--- /dev/null
+++ b/docs/getting-started.rst
@@ -0,0 +1,107 @@
+.. _getting_started:
+
+Getting Started
+===============
+
+OnionBalance implements `round-robin` like load balancing on top of Tor
+hidden services. A typical OnionBalance deployment will incorporate one management
+servers and multiple backend application servers.
+
+Architecture
+------------
+
+The management server runs the OnionBalance daemon and will regularly publish
+hidden service routing information to the Tor network.
+
+The backend application servers / node runs their own standard Tor
+hidden service. Client access the public hidden service address are then
+routed to one of the backend application servers.
+
+**Management Server**
+ is the machine running the OnionBalance daemon. It the master hidden
+ service private key.
+
+ This machine can be located geographically isolated from the machines
+ hosting the hidden service content. It does not need to serve any content.
+
+**Backend Instance**
+ Each backend application server will run a Tor hidden service. EXPLAIN
+
+.. note::
+ The :ref:`onionbalance-config <onionbalance_config>` tool can be used to
+ quickly generate keys and config files for your OnionBalance deployment.
+
+
+The OnionBalance tool provide two command line tools:
+
+ **onionbalance** acts as a long running daemon.
+
+ **onionbalance-config** is a helper utility which eases the process of
+ creating keys and configuration files for onionbalance and the backend
+ Tor instances.
+
+CLI Documentation
+~~~~~~~~~~~~~~~~~
+
+ .. toctree::
+ :maxdepth: 1
+
+ onionbalance <running-onionbalance>
+ onionbalance-config <onionbalance-config>
+
+
+Installing and Configuring Tor
+------------------------------
+
+Tor is need on the management server and every backend hidden service
+instance.
+
+Management Server
+~~~~~~~~~~~~~~~~~
+
+OnionBalance requires that a recent version of Tor (``>= 0.2.7.1-alpha``) is
+installed on the management server system. This version might not be available
+in your operating system's repositories yet.
+
+It is recommended that you install Tor from the
+`Tor Project repositories <https://www.torproject.org/download/download-unix.html.en>`_
+to ensure you stay up to date with the latest Tor releases.
+
+The management server need to have its control port enabled to allow
+the OnionBalance daemon to talk to the Tor process. This can be done by
+uncommenting the ``ControlPort`` option in your ``torrc`` configuration file.
+
+Alternatively you can replace your ``torrc`` file with the following
+is suitable for the Tor instance running on the management server:
+
+.. literalinclude:: ../onionbalance/data/torrc-server
+ :name: torrc-server
+ :lines: 6-
+
+After configuring Tor you should restart your Tor process
+
+.. code-block:: console
+
+ $ sudo service tor reload
+
+Backend Instances
+~~~~~~~~~~~~~~~~~
+
+Each backend instance should be run a standard onion service which serves your
+website or other content. More information about configuring onion services is
+available in the Tor Project's
+`hidden service configuration guide <https://www.torproject.org/docs/tor-hidden-service.html.en>`_.
+
+If you have used the ``onionbalance-config`` tool you should transfer the
+generated instance config files and keys to the Tor configuration directory
+on the backend servers.
+
+.. literalinclude:: ../onionbalance/data/torrc-instance
+ :name: torrc-instance
+ :lines: 6-
+
+After configuring Tor you should restart your Tor process
+
+.. code-block:: console
+
+ $ sudo service tor reload
diff --git a/docs/index.rst b/docs/index.rst
index 239d974..5109b85 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -3,30 +3,49 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-.. include:: ../README.rst
+Overview
+========
-----
+The OnionBalance software allows for Tor hidden service requests to be
+distributed across multiple backend Tor instances. OnionBalance provides
+load-balancing while also making onion services more resilient and reliable
+by eliminating single points-of-failure.
+- Latest release: |version| (:ref:`changelog`)
+- GitHub: https://github.com/DonnchaC/onionbalance/
+- Issue tracker: https://github.com/DonnchaC/onionbalance/issues
+- PyPI: https://pypi.python.org/pypi/OnionBalance
+- IRC: #onionbalance @ OFTC
-Contents
+Features
========
-.. toctree::
- :maxdepth: 2
+OnionBalance is under active development and new features are being added
+regularly:
- onionbalance
- design
+- Load balancing between up to 10 backend hidden services
+- Storage of the hidden service private key separate to th hidden service
+ hosts
-Todo List
-=========
-.. todolist::
+User Guide
+==========
+Onionbalance consists of a long-running daemon and a command-line
+configuration tool. Please see the :ref:`getting_started` page for usage
+instructions.
-Indices and tables
-==================
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. toctree::
+ :maxdepth: 2
+ installation
+ getting-started
+ running-onionbalance
+ use-cases
+
+.. toctree::
+ :maxdepth: 2
+
+ design
+ changelog
diff --git a/docs/installation.rst b/docs/installation.rst
new file mode 100644
index 0000000..82f8fc0
--- /dev/null
+++ b/docs/installation.rst
@@ -0,0 +1,35 @@
+Installation
+============
+
+OnionBalance requires at least one system that is running the OnionBalance
+management server.
+
+The OnionBalance software does not need to be installed on the
+backend servers which provide the hidden service content (i.e. web site,
+IRC server etc.).
+
+OnionBalance is not yet packaged for Linux and BSD. The tool can be
+installed from PyPI or directly from the Git repository:
+
+.. code-block:: console
+
+ # pip install onionbalance
+
+or
+
+.. code-block:: console
+
+ $ git clone https://github.com/DonnchaC/onionbalance.git
+ $ cd onionbalance
+ # python setup.py install
+
+All tagged releases on Github or PyPi are signed with my GPG key:
+
+::
+
+ pub 4096R/0x3B0D706A7FBFED86 2013-06-27 [expires: 2016-07-11]
+ Key fingerprint = 7EFB DDE8 FD21 11AE A7BE 1AA6 3B0D 706A 7FBF ED86
+ uid [ultimate] Donncha O'Cearbhaill <donncha at donncha.is>
+ sub 3072R/0xD60D64E73458F285 2013-06-27 [expires: 2016-07-11]
+ sub 3072R/0x7D49FC2C759AA659 2013-06-27 [expires: 2016-07-11]
+ sub 3072R/0x2C9C6F4ABBFCF7DD 2013-06-27 [expires: 2016-07-11]
diff --git a/docs/onionbalance-config.rst b/docs/onionbalance-config.rst
new file mode 100644
index 0000000..d8cb51f
--- /dev/null
+++ b/docs/onionbalance-config.rst
@@ -0,0 +1,59 @@
+.. _onionbalance_config:
+
+onionbalance-config Tool
+========================
+
+Description
+-----------
+
+The ``onionbalance-config`` tool is the fastest way to generate the necessary
+keys and config files to get your onion service up and running.
+
+.. code-block:: console
+
+ $ onionbalance-config
+
+When called without any arguments, the config generator will run in an
+interactive mode and prompt for user input.
+
+The ``master`` directory should be stored on the management server while
+the other ``instance`` directories should be transferred to the respective
+backend servers.
+
+
+Command-Line Options
+--------------------
+
+.. autoprogram:: onionbalance.manager:parse_cmd_args()
+ :prog: onionbalance-config
+
+
+Files
+-----
+
+master/config.yaml
+ This is the configuration file that is used my the OnionBalance management
+ server.
+
+master/<ONION_ADDRESS>.key
+ The private key which will become the public address and identity for your
+ hidden service. It is essential that you keep this key secure.
+
+master/torrc-server
+ A sample Tor configuration file which can be used with the Tor instance
+ running on the management server.
+
+srv/torrc-instance
+ A sample Tor config file which contains the Tor ``HiddenService*`` options
+ needed for your backend Tor instance.
+
+srv/<ONION_ADDRESS>/private_key
+ Directory containing the private key for you backend hidden service instance.
+ This key is less critical as it can be rotated if lost or compromised.
+
+
+See Also
+--------
+
+Full documentation for the **OnionBalance** software is available at
+https://onionbalance.readthedocs.org/
diff --git a/docs/running-onionbalance.rst b/docs/running-onionbalance.rst
new file mode 100644
index 0000000..fa898f8
--- /dev/null
+++ b/docs/running-onionbalance.rst
@@ -0,0 +1,131 @@
+Running OnionBalance
+====================
+
+Description
+-----------
+
+You can start the OnionBalance management server once all of your backend
+onion service instances are running.
+
+You will need to create a :ref:`configuration file <configuration_file_format>`
+which list the backend hidden services and the location of your hidden
+service keys.
+
+.. code-block:: console
+
+ $ onionbalance -c config.yaml
+
+or
+
+.. code-block:: console
+
+ $ sudo service onionbalance start
+
+The management server must be left running to publish new descriptors for
+your onion service.
+
+.. note::
+
+ Multiple OnionBalance management servers can be run simultaneously with
+ the same master private key and configuration file to provide redundancy.
+
+Command-Line Options
+--------------------
+
+.. autoprogram:: onionbalance.manager:parse_cmd_args()
+ :prog: onionbalance
+
+
+.. _configuration_file_format:
+
+Configuration File Format
+-------------------------
+
+The OnionBalance management server is primarily configured using a YAML
+configuration file.
+
+.. literalinclude:: ../onionbalance/data/config.example.yaml
+ :name: example-config.yaml
+ :language: yaml
+
+
+The ``services`` section of the configuration file contains a list of
+master onion services that OnionBalance is responsible for.
+
+Each ``key`` option specifies the location of the 1024 bit private RSA key
+for the hidden service. This master private key determines the address
+that users will use to access your onion service. This private key **must**
+be kept secure.
+
+The location of the private key is evaluated as an absolute path, or
+relative to the configuration file location.
+
+You can use existing Tor hidden service private key with OnionBalance
+to keep your onion address.
+
+Each backend Tor onion service instance is listed by it's unique onion
+address in the ``instances`` list.
+
+.. note::
+
+ You can replace backend instance keys if they get lost or compromised.
+ Simply start a new backend hidden service under a new key and replace
+ the ``address`` in the config file.
+
+If you have used the :ref:`onionbalance-config <onionbalance_config>` tool
+you can simply use the generated config file from ``master/config.yaml``.
+
+.. note::
+
+ By default onionbalance will search for a ``config.yaml`` file in
+ ``/etc/onionbalance/`` followed by the current working directory.
+
+
+Configuration Options
+~~~~~~~~~~~~~~~~~~~~~
+
+REFRESH_INTERVAL
+ How often to check for updated backend hidden service descriptors. This
+ value can be increased if your backend instance are under heavy loaded
+ causing them to rotate introduction points quickly.
+ (default: 600 seconds).
+
+PUBLISH_CHECK_INTERVAL
+ How often should to check if new descriptors need to be published for
+ the master hidden service (default: 360 seconds).
+
+The following options typically do not need to be modified by the end user:
+
+REPLICAS
+ How many set of HSDirs to upload too (default: 2).
+
+MAX_INTRO_POINTS
+ How many introduction points to include in a descriptor (default: 10)
+
+DESCRIPTOR_VALIDITY_PERIOD
+ How long a hidden service descriptor remains valid (default:
+ 86400 seconds)
+
+DESCRIPTOR_OVERLAP_PERIOD
+ How long to overlap hidden service descriptors when changing
+ descriptor IDs (default: 3600 seconds)
+
+DESCRIPTOR_UPLOAD_PERIOD
+ How often to publish a descriptor, even when the introduction points
+ don't change (default: 3600 seconds)
+
+Files
+-----
+
+/etc/onionbalance/config.yaml
+ The configuration file, which contains ``services`` entries.
+
+config.yaml
+ Fallback location for torrc, if /etc/onionbalance/config.yaml is
+ not found.
+
+See Also
+--------
+
+Full documentation for the **OnionBalance** software is available at
+https://onionbalance.readthedocs.org/
diff --git a/docs/use-cases.rst b/docs/use-cases.rst
new file mode 100644
index 0000000..a970fd7
--- /dev/null
+++ b/docs/use-cases.rst
@@ -0,0 +1,40 @@
+Use Cases
+=========
+
+There a many ways to use OnionBalance to increase the scalabiliy, reliability and security of your onion service. The following are some examples of what is
+possible.
+
+
+Current Deployments
+-------------------
+
+**SKS Keyserver Pool**
+ Kristian Fiskerstrand has set up a hidden service
+ `keyserver pool <https://sks-keyservers.net/overview-of-pools.php#pool_tor>`_
+ which connects users to one of the available hidden service key servers.
+
+
+
+Other Examples
+--------------
+
+- A popular onion service with an overloaded web server or Tor process
+
+ A service such as Facebook which gets a large number of users would like
+ to distribute client requests across multiple servers as the load is too
+ much for a single Tor instance to handle. They would also like to balance
+ between instances when the 'encrypted services' proposal is implemented [2555].
+
+- Redundancy and automatic failover
+
+ A political activist would like to keep their web service accessible and
+ secure in the event that the secret police seize some of their servers.
+ Clients should ideally automatically fail-over to another online instances
+ with minimal service disruption.
+
+- Secure Onion Service Key storage
+
+ An onion service operator would like to compartmentalize their permanent
+ onion key in a secure location separate to their Tor process and other
+ services. With this proposal permanent keys could be stored on an
+ independent, isolated system.
diff --git a/tox.ini b/tox.ini
index 5f5ac4d..ff5cd18 100644
--- a/tox.ini
+++ b/tox.ini
@@ -17,6 +17,7 @@ commands = py.test
basepython=python
changedir=docs
deps=sphinx
+ sphinxcontrib-autoprogram
commands=
sphinx-build -W -b html -d {envtmpdir}/docs . {envtmpdir}/html
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-privacy/packages/onionbalance.git
More information about the Pkg-privacy-commits
mailing list