Merge pull request #276 from jzelinskie/configdocs

example_config: add initial documentation

example_config.yaml

@@ -1,49 +1,88 @@
 chihaya:
+  # The interval communicated with BitTorrent clients informing them how
+  # frequently they should announce in between client events.
   announce_interval: 15m
-  prometheus_addr: localhost:6880
+
+  # The network interface that will bind to an HTTP endpoint that can be
+  # scraped by an instance of the Prometheus time series database.
+  # For more info see: https://prometheus.io
+  prometheus_addr: "0.0.0.0:6880"
+
+  # The maximum number of peers returned in an announce.
   max_numwant: 50
+
+  # The default number of peers returned in an announce.
   default_numwant: 25
 
+  # This block defines configuration for the tracker's HTTP interface.
+  # If you do not wish to run this, delete this section.
   http:
-    addr: 0.0.0.0:6881
+    # The network interface that will bind to an HTTP server for serving
+    # BitTorrent traffic.
+    addr: "0.0.0.0:6881"
+
+    # When enabled, the IP address used to connect to the tracker will not
+    # override the value clients advertise as their IP address.
     allow_ip_spoofing: false
-    real_ip_header: x-real-ip
+
+    # The HTTP Header containing the IP address of the client.
+    # This is only necessary if using a reverse proxy.
+    real_ip_header: "x-real-ip"
+
+    # The timeout durations for HTTP requests.
     read_timeout: 5s
     write_timeout: 5s
     request_timeout: 5s
 
+  # This block defines configuration for the tracker's UDP interface.
+  # If you do not wish to run this, delete this section.
   udp:
-    addr: 0.0.0.0:6881
-    allow_ip_spoofing: false
-    max_clock_skew: 10s
-    private_key: |
-      paste a random string here that will be used to hmac connection IDs
+    # The network interface that will bind to a UDP server for serving
+    # BitTorrent traffic.
+    addr: "0.0.0.0:6881"
 
+    # When enabled, the IP address used to connect to the tracker will not
+    # override the value clients advertise as their IP address.
+    allow_ip_spoofing: false
+
+    # The leeway for a timestamp on a connection ID.
+    max_clock_skew: 10s
+
+    # The key used to encrypt connection IDs.
+    private_key: "paste a random string here that will be used to hmac connection IDs"
+
+  # This block defines configuration used for the storage of peer data.
   storage:
+    # The frequency which stale peers are removed.
     gc_interval: 14m
-    peer_lifetime: 15m
+
+    # The amount of time until a peer is considered stale.
+    # To avoid churn, keep this slightly larger than `announce_interval`
+    peer_lifetime: 16m
+
+    # The number of partitions data will be divided into in order to provide a
+    # higher degree of parallelism.
     shards: 1
 
+  # This block defines configuration used for middleware executed before a
+  # response has been returned to a BitTorrent client.
   prehooks:
   - name: jwt
     config:
-      issuer: https://issuer.com
-      audience: https://chihaya.issuer.com
-      jwk_set_url: https://issuer.com/keys
+      issuer: "https://issuer.com"
+      audience: "https://chihaya.issuer.com"
+      jwk_set_url: "https://issuer.com/keys"
       jwk_set_update_interval: 5m
+
   - name: client approval
     config:
       whitelist:
-      - OP1011
+      - "OP1011"
       blacklist:
-      - OP1012
+      - "OP1012"
+
   - name: interval variation
     config:
       modify_response_probability: 0.2
       max_increase_delta: 60
       modify_min_interval: true
-
-  posthooks:
-  - name: gossip
-    config:
-      boostrap_node: 127.0.0.1:6881