Cleanup explanations of options in bridgedb.conf.

bridgedb.conf

+# -*- mode: python ; coding: utf-8 -*-
+#
+#   +---------------+
+#   | bridgedb.conf |
+#   +---------------+
+#
+# This file uses Python syntax, and is sourced as if it were a .py file. Just
+# pretend you're writing Python, and everything will be peachy keen.
+#______________________________________________________________________________
+#
+# This file is part of BridgeDB, a Tor bridge distribution system.
+#
+# :copyright: (c) 2007-2013, The Tor Project, Inc.
+#             (c) 2007-2013, all sentient entities within the AUTHORS file
+# :license: see LICENSE for licensing information
+#______________________________________________________________________________
 
-#==========
-# General-purpose options.
+#===========================#
+#  General-purpose options  #
+#___________________________#
 
-# Either a file in which to write our pid, or None
-PIDFILE = "bridgedb.pid"
+#----------------
+# Required Files \  You'll want to make sure that these ones exist!
+#------------------------------------------------------------------------------
+#
+# All filenames are taken as relative to the RUNTIME directory, which is the
+# current working directory when you call the ``bridgedb`` script, or you may
+# specify a particular RUNTIME directory by doing:
+#
+#     $ bridgedb -r /path/to/some/nice/place
+#
+# Obviously, this config file should live in that directory, so that BridgeDB
+# can read it.
+#------------------------------------------------------------------------------
+
+# List of filenames from which we read ``@type bridge-server-descriptor``s, on
+# startup and on SIGHUP.
+BRIDGE_FILES = ["bridge-descriptors"]
+
+# List of filenames from which we read ``@type bridge-extra-info``
+# descriptors, for learning about a bridge's pluggable transports:
+EXTRA_INFO_FILES = ["cached-extrainfo", "cached-extrainfo.new"]
+
+# Filename from which we read ``@type bridge-network-status`` entries, for
+# learning which current bridges are Running, as well as their IPv6 addresses.
+STATUS_FILE = "networkstatus-bridges"
+
+# Certificate file and private key for the HTTPS Distributor. To create a
+# self-signed cert, run ``scripts/make-ssl-cert`` it will create these files
+# in your current directory.
+HTTPS_CERT_FILE="cert"
+HTTPS_KEY_FILE="privkey.pem"
+
+#----------------
+# Output Files   \  Where to store created data
+#------------------------------------------------------------------------------
+#
+# These will get automatically created for you, just specify where they should
+# go.
+#------------------------------------------------------------------------------
 
 # Either a file to log to, or None if we should log to the console.
 LOGFILE = "bridgedb.log"
 
+# File to which we dump bridge pool assignments for statistics.
+ASSIGNMENTS_FILE = "assignments.log"
+
+# File in which to write our pid
+PIDFILE = "bridgedb.pid"
+
+# Filename of the database to store persistent info in.
+DB_FILE = "bridgedist.db"
+
+# Filename to log changes to persistent info in. For debugging and bugfixing.
+DB_LOG_FILE = "bridgedist.log"
+
+# Filename where we store our secret HMAC root key. This file and the key
+# inside are automatically created for you if they do not exist.
+MASTER_KEY_FILE = "secret_key"
+
+# Filename that contains blocked bridges list. Comment out to disable.
+#COUNTRY_BLOCK_FILE = "blocked-bridges"
+
+# A list of filenames that contain IP addresses (one per line) of proxies.
+# All IP-based distributors that see an incoming connection from a proxy
+# will treat them specially.
+PROXY_LIST_FILES = []
+
+#------------------
+# Logging Options  \
+#------------------------------------------------------------------------------
+#
+# Be sure to also see the LOGFILE option above!
+#------------------------------------------------------------------------------
+
+# One of "DEBUG", "INFO", "WARNING", "ERROR"...
+LOGLEVEL = "DEBUG"
+
 # If true, we scrub all potentially identifying information before we log it
 SAFELOGGING = True
 
@@ -15,34 +103,9 @@ SAFELOGGING = True
 LOGFILE_COUNT = 5
 LOGFILE_ROTATE_SIZE = 10000000
 
-# One of "DEBUG", "INFO", "WARNING", "ERROR"...
-LOGLEVEL = "WARNING"
-
-# Files from which we read bridge descriptors, on start and on SIGHUP.
-BRIDGE_FILES = [ "./bridge-descriptors" ]
-
-# File from which we read routerstatus entries, for learning which
-# current bridges are Running.
-STATUS_FILE = "networkstatus-bridges"
-
-# Either a file that contains blocked bridges list or None
-#COUNTRY_BLOCK_FILE = "./blocked-bridges" 
-
-# File from which we read extra-info entries, for learning pluggable
-# transports
-EXTRA_INFO_FILES = ["cached-extrainfo", "cached-extrainfo.new"]
 
 # Only consider routers whose purpose matches this string.
 BRIDGE_PURPOSE = "bridge"
-# File to store persistent info in.
-DB_FILE = "bridgedist.db"
-# File to log changes to persistent info in.  For debugging and bugfixing.
-DB_LOG_FILE = "bridgedist.log"
-# File in which we store our secret HMAC root key.
-MASTER_KEY_FILE = "secret_key"
-
-# File to which we dump bridge pool assignments for statistics.
-ASSIGNMENTS_FILE = "assignments.log"
 
 # How many clusters do we group IPs in when distributing bridges based on IP?
 # Note that if PROXY_LIST_FILES is set (below), what we actually do here
@@ -51,60 +114,72 @@ ASSIGNMENTS_FILE = "assignments.log"
 N_IP_CLUSTERS = 4
 
 # If possible, always give a certain number of answers with a given ORPort.
-# This is a list of (port,minimum) tuples.
-FORCE_PORTS = [ (443, 1) ]
+# This is a list of ``(port, minimum)`` tuples.
+FORCE_PORTS = [(443, 1)]
 
 # If possible, always give a certain number of answers with a given flag.
 # Only "stable" is now supported.  This is a list of (flag,minimum) tuples.
-FORCE_FLAGS = [ ("Stable", 1) ]
+FORCE_FLAGS = [("Stable", 1)]
 
-# A list of filenames that contain IP addresses (one per line) of proxies.
-# All IP-based distributors that see an incoming connection from a proxy
-# will treat them specially.
-PROXY_LIST_FILES = [ ]
-
-#==========
-# Options related to HTTPS
+#-------------------------------
+# HTTP(S) Distribution Options  \
+#------------------------------------------------------------------------------
+#
+# These options configure the behaviour of the web interface bridge
+# distribution mechanism. If HTTPS_DIST is enabled, make sure that the above
+# HTTPS_CERT_FILE and HTTPS_KEY_FILE options point to the correct location of
+# your SSL certificate and key!
+#------------------------------------------------------------------------------
 
-# True if we are enabling distribution via HTTP or HTTPS; False otherwise.
+# Set to ``True`` to enable distribution via HTTP or HTTPS; False otherwise.
 HTTPS_DIST = True
-# What proportion of bridges do we allocate to HTTP distribution?  See
-# EMAIL_SHARE and RESERVED_SHARE.
-HTTPS_SHARE=10
-# An IP address (form "1.2.3.4") where we listen for HTTPS connections.
-# "None" to listen on the default interface.
-HTTPS_BIND_IP='127.0.0.1'
-# Port to listen on for incoming HTTPS connections
-HTTPS_PORT=6789
-# Certificate file
-HTTPS_CERT_FILE="cert"
-# Private key file.
-HTTPS_KEY_FILE="privkey.pem"
+
+# (string or None) The IP address where we listen for HTTPS connections. If
+# ``None``, listen on the default interface.
+HTTPS_BIND_IP = '127.0.0.1'
+
+# (integer or None) The port to listen on for incoming HTTPS connections.
+HTTPS_PORT = 6789
+
+# How many bridges do we give back in an answer?
+HTTPS_N_BRIDGES_PER_ANSWER = 3
+
+# Should we tell http users about the bridge fingerprints?  Turn this on
+# once we have the vidalia/tor interaction fixed for everbody.
+HTTPS_INCLUDE_FINGERPRINTS = True
+
 # If true, there is a trusted proxy relaying incoming messages to us: take
 # the *last* entry from its X-Forwarded-For header as the client's IP.
 HTTPS_USE_IP_FROM_FORWARDED_HEADER = False
 
-# IP and port to listen on for unencrypted HTTP connections.
-HTTP_UNENCRYPTED_BIND_IP=None
-HTTP_UNENCRYPTED_PORT=None
-# As HTTPS_USE_IP_FROM_FORWARDED_HEADER, but for unencrypted connections.
+# (string or None) The IP address to listen on for unencrypted HTTP
+# connections. Set to ``None`` to disable unencrypted connections to the web
+# interface.
+HTTP_UNENCRYPTED_BIND_IP = None
+
+# (integer or None) The port to listen on for incoming HTTP connections.
+HTTP_UNENCRYPTED_PORT = None
+
+# Same as the ``HTTPS_USE_IP_FROM_FORWARDED_HEADER`` option, but for
+# unencrypted connections.
 HTTP_USE_IP_FROM_FORWARDED_HEADER = False
-# How many bridges do we give back in an answer?
-HTTPS_N_BRIDGES_PER_ANSWER=3
-HTTP_N_BRIDGES_PER_ANSWER=3
 
-# Should we tell http users about the bridge fingerprints?  Turn this on
-# once we have the vidalia/tor interaction fixed for everbody.
-HTTPS_INCLUDE_FINGERPRINTS=True
+# The number of bridges to hand out per response by the unencrypted HTTP
+# distributor
+HTTP_N_BRIDGES_PER_ANSWER = 3
 
-#==========
-# Options related to Email
+#-------------------------------
+# Email Distribution Options    \
+#------------------------------------------------------------------------------
+#
+# These options configure the behaviour of the email bridge distribution
+# mechanism. If EMAIL_DIST is enabled, make sure that the above
+# HTTPS_CERT_FILE and HTTPS_KEY_FILE options point to the correct location of
+# your SSL certificate and key!
+# ------------------------------------------------------------------------------
 
 # True if we are enabling distribution via Email; false otherwise.
 EMAIL_DIST = True
-# What proportion of bridges do we allocate to Email distribution?  See
-# HTTPS_SHARE and RESERVED_SHARE.
-EMAIL_SHARE=10
 
 # What email addresses do we use for outgoing email?  EMAIL_FROM_ADDR goes
 # in the From: line in outgoing headers, and EMAIL_SMTP_FROM_ADDR goes in
@@ -118,11 +193,12 @@ EMAIL_SMTP_PORT = 25
 EMAIL_USERNAME = "bridges"
 
 # Canonical versions of domains that we will reply to.
-EMAIL_DOMAINS = [ "gmail.com", "yahoo.com" ]
+EMAIL_DOMAINS = ["gmail.com", "yahoo.com"]
+
 # Map from unofficial domain to canonical domain.
 EMAIL_DOMAIN_MAP = { "mail.google.com" : "gmail.com",
-                     "googlemail.com" : "gmail.com",
-                     }
+                     "googlemail.com" : "gmail.com"}
+
 # Map from canonical domain to list of options for that domain.  Recognized
 # options are:
 #     "ignore_dots" -- the service ignores "." characters in email addresses.
@@ -131,14 +207,16 @@ EMAIL_DOMAIN_MAP = { "mail.google.com" : "gmail.com",
 #
 # Note that unrecognized options are ignored; be sure to spell them right!
 EMAIL_DOMAIN_RULES = { 'gmail.com' : ["ignore_dots", "dkim"],
-                       'yahoo.com' : ["dkim"]
-                       }
+                       'yahoo.com' : ["dkim"]}
+
 # If there are any IPs in this list, only allow incoming connections from
 # those IPs.
-EMAIL_RESTRICT_IPS=[]
+EMAIL_RESTRICT_IPS = []
+
 # IP and port to listen on for email connections. Debugging only.
 EMAIL_BIND_IP="127.0.0.1"
 EMAIL_PORT=6725
+
 # How many bridges do we give back in an answer?
 EMAIL_N_BRIDGES_PER_ANSWER=3
 
@@ -150,22 +228,46 @@ EMAIL_INCLUDE_FINGERPRINTS = True
 EMAIL_GPG_SIGNING_ENABLED = True
 EMAIL_GPG_SIGNING_KEY = 'gnupghome/TESTING.subkeys.sec'
 
-#==========
-# Options related to unallocated bridges.
+#-------------------------------
+# Hashring Allocation Options   \
+#------------------------------------------------------------------------------
+#
+# These options determine the proportions of bridges per hashring. When
+# BridgeDB receives a descriptor for a new bridge, that bridge is assigned to
+# a hashring. For example, if ``HTTPS_DIST`` and ``EMAIL_DIST`` are both
+# enabled, there is a hashring for bridges allocated to the HTTP(S)
+# Distributor, and another for the Email Distributor. In addition, an
+# "Unallocated" hashring is always created, in order to reserve some portion
+# of bridges for manual distribution, or as backup in the case of a major
+# blocking event. Once a bridge is assigned to one of these allocation groups,
+# it stays there; there is currently no mechanism for changing a bridge's
+# hashring allocation.
+#
+# The bridges are allocated to these groups with the following proportions:
+#
+#     ``HTTPS_SHARE`` : ``EMAIL_SHARE`` : ``RESERVED_SHARE``
+# ------------------------------------------------------------------------------
+
+# The proportion of bridges to allocate to HTTP distribution.
+HTTPS_SHARE = 10
 
-# We split bridges into a group accessible by HTTPS queries; a group
-# accessible by email queries; and a group that we don't assign to any
-# query mechanism.  Once a bridge is assigned to either of the first
-# two groups, it stays there persistently.  The bridges are allocated
-# to these groups in a proportion of
-#   HTTPS_SHARE : EMAIL_SHARE : RESERVED_SHARE
-RESERVED_SHARE=2
+# The proportion of bridges to allocate to Email distribution.
+EMAIL_SHARE = 10
 
+# An integer specifying the proportion of bridges which should remain
+# unallocated, for backup usage and manual distribution.
+RESERVED_SHARE = 2
+
+# A dictionary of {FILENAME: NUMBER} where FILENAME is a string specifying the
+# filename to store a certain NUMBER (an integer) of bridges in. The number of
+# bridges here is *not* a share/proportion, as above; instead it's literally
+# the number of bridges.
 FILE_BUCKETS = {}
 
 # Options related to recaptcha support.
 # Enable/Disable recaptcha
 RECAPTCHA_ENABLED = False
+
 # Recaptcha API keys
 RECAPTCHA_PUB_KEY = ''
-RECAPTCHA_PRIV_KEY = '' 
+RECAPTCHA_PRIV_KEY = ''