commit 5f26b667d3a30a48c0f8582f88e2ef6b78ccdaf0 Author: Isis Lovecruft isis@torproject.org Date: Sun Oct 6 05:39:22 2013 +0000
Cleanup explanations of options in bridgedb.conf. --- bridgedb.conf | 268 +++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 185 insertions(+), 83 deletions(-)
diff --git a/bridgedb.conf b/bridgedb.conf index 88aa231..a0a1f57 100644 --- a/bridgedb.conf +++ b/bridgedb.conf @@ -1,13 +1,101 @@ +# -*- 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 = ''