[tor-commits] [snowflake/main] Cleaned up and reorganized READMEs
cohosh at torproject.org
cohosh at torproject.org
Mon Jul 19 14:16:49 UTC 2021
commit c1b0fdd8cfaa89d2507c4bb23ef907c40de73d61
Author: Cecylia Bocovich <cohosh at torproject.org>
Date: Thu Jul 15 10:40:48 2021 -0400
Cleaned up and reorganized READMEs
---
README.md | 80 +++++++++++++++++------------------------------------
broker/README.md | 9 ++++++
client/README.md | 54 +++++++++++++++++++++++++++++-------
probetest/README.md | 9 ++++++
proxy/README.md | 49 ++++++++++++++++++++++++++++++--
server/README.md | 9 ++++++
6 files changed, 143 insertions(+), 67 deletions(-)
diff --git a/README.md b/README.md
index 6d47012..afc4ddf 100644
--- a/README.md
+++ b/README.md
@@ -8,66 +8,47 @@ Pluggable Transport using WebRTC, inspired by Flashproxy.
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**
+- [Structure of this Repository](#structure-of-this-repository)
- [Usage](#usage)
- - [Dependencies](#dependencies)
- - [More Info](#more-info)
- - [Building](#building)
- - [Test Environment](#test-environment)
+ - [Using Snowflake with Tor](#using-snowflake-with-tor)
+ - [Running a Snowflake Proxy](#running-a-snowflake-proxy)
+ - [Using the Snowflake Library with Other Applications](#using-the-snowflake-library-with-other-applications)
+- [Test Environment](#test-environment)
- [FAQ](#faq)
-- [Appendix](#appendix)
- - [-- Testing with Standalone Proxy --](#---testing-with-standalone-proxy---)
+- [More info and links](#more-info-and-links)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-### Usage
-
-```
-cd client/
-go get
-go build
-tor -f torrc
-```
-This should start the client plugin, bootstrapping to 100% using WebRTC.
-
-#### Dependencies
+### Structure of this Repository
-Client:
-- [pion/webrtc](https://github.com/pion/webrtc)
-- Go 1.13+
+- `broker/` contains code for the Snowflake broker
+- `doc/` contains Snowflake documentation and manpages
+- `client/` contains the Tor pluggable transport client and client library code
+- `common/` contains generic libraries used by multiple pieces of Snowflake
+- `proxy/` contains code for the Go standalone Snowflake proxy
+- `probetest/` contains code for a NAT probetesting service
+- `server/` contains the Tor pluggable transport server and server library code
----
-
-#### More Info
+### Usage
-Tor can plug in the Snowflake client via a correctly configured `torrc`.
-For example:
+Snowflake is currently deployed as a pluggable transport for Tor.
-```
-ClientTransportPlugin snowflake exec ./client \
--url https://snowflake-broker.azureedge.net/ \
--front ajax.aspnetcdn.com \
--ice stun:stun.l.google.com:19302
--max 3
-```
+#### Using Snowflake with Tor
-The flags `-url` and `-front` allow the Snowflake client to speak to the Broker,
-in order to get connected with some volunteer's browser proxy. `-ice` is a
-comma-separated list of ICE servers, which are required for NAT traversal.
+To use the Snowflake client with Tor, you will need to add the appropriate `Bridge` and `ClientTransportPlugin` lines to your [torrc](https://2019.www.torproject.org/docs/tor-manual.html.en) file. See the [client README](client) for more information on building and running the Snowflake client.
-For logging, run `tail -F snowflake.log` in a second terminal.
+#### Running a Snowflake Proxy
-You can modify the `torrc` to use your own broker:
+You can contribute to Snowflake by running a Snowflake proxy. We have the option to run a proxy in your browser or as a standalone Go program. See our [community documentation](https://community.torproject.org/relay/setup/snowflake/) for more details.
-```
-ClientTransportPlugin snowflake exec ./client --meek
-```
+#### Using the Snowflake Library with Other Applications
+Snowflake can be used as a Go API, and adheres to the [v2.1 pluggable transports specification](). For more information on using the Snowflake Go library, see the [Snowflake library documentation](doc/using-the-snowflake-library).
-#### Test Environment
+### Test Environment
There is a Docker-based test environment at https://github.com/cohosh/snowbox.
-
### FAQ
**Q: How does it work?**
@@ -103,17 +84,6 @@ manual port forwarding!
It utilizes the "ICE" negotiation via WebRTC, and also involves a great
abundance of ephemeral and short-lived (and special!) volunteer proxies...
-### Appendix
-
-##### -- Testing with Standalone Proxy --
-
-```
-cd proxy
-go build
-./proxy
-```
-
-More documentation on the way.
+### More info and links
-Also available at:
-[torproject.org/pluggable-transports/snowflake](https://gitweb.torproject.org/pluggable-transports/snowflake.git/)
+We have more documentation in the [Snowflake wiki](https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/snowflake/-/wikis/home) and at https://snowflake.torproject.org/.
diff --git a/broker/README.md b/broker/README.md
index fb6181e..1e0a763 100644
--- a/broker/README.md
+++ b/broker/README.md
@@ -1,3 +1,12 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Overview](#overview)
+- [Running your own](#running-your-own)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
This is the Broker component of Snowflake.
### Overview
diff --git a/client/README.md b/client/README.md
index 50bdba3..aed11c3 100644
--- a/client/README.md
+++ b/client/README.md
@@ -1,20 +1,54 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Dependencies](#dependencies)
+- [Building the Snowflake client](#building-the-snowflake-client)
+- [Running the Snowflake client with Tor](#running-the-snowflake-client-with-tor)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
This is the Tor client component of Snowflake.
-It is based on goptlib.
+It is based on the [goptlib](https://gitweb.torproject.org/pluggable-transports/goptlib.git/) pluggable transports library for Tor.
+
+
+### Dependencies
+
+- Go 1.13+
+- We use the [pion/webrtc](https://github.com/pion/webrtc) library for WebRTC communication with Snowflake proxies. Note: running `go get` will fetch this dependency automatically during the build process.
+
+### Building the Snowflake client
+
+To build the Snowflake client, make sure you are in the `client/` directory, and then run:
-### Flags
+```
+go get
+go build
+```
-The client uses these following `torrc` options by default:
+### Running the Snowflake client with Tor
+
+We have an example `torrc` file in this repository. The client uses these following `torrc` options by default:
```
+UseBridges 1
+
ClientTransportPlugin snowflake exec ./client \
--url https://snowflake-broker.azureedge.net/ \
--front ajax.aspnetcdn.com \
--ice stun:stun.l.google.com:19302
+-url https://snowflake-broker.torproject.net.global.prod.fastly.net/ \
+-front cdn.sstatic.net \
+-ice stun:stun.voip.blackberry.com:3478,stun:stun.altar.com.pl:3478,stun:stun.antisip.com:3478,stun:stun.bluesip.net:3478,stun:stun.dus.net:3478,stun:stun.epygi.com:3478,stun:stun.sonetel.com:3478,stun:stun.sonetel.net:3478,stun:stun.stunprotocol.org:3478,stun:stun.uls.co.za:3478,stun:stun.voipgate.com:3478,stun:stun.voys.nl:3478
+
+Bridge snowflake 192.0.2.3:1
```
-`-url` should be the URL of a Broker instance.
+`-url` is the URL of a broker instance. If you would like to try out Snowflake with your own broker, simply provide the URL of your broker instance with this option.
+
+`-front` is an optional front domain for the broker request.
-`-front` is an optional front domain for the Broker request.
+`-ice` is a comma-separated list of ICE servers. These can be STUN or TURN servers. We recommend using servers that have implemented NAT discovery. See our wiki page on [NAT traversal](https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/snowflake/-/wikis/NAT-matching) for more information.
-`-ice` is a comma-separated list of ICE servers. These can be STUN or TURN
-servers.
+To bootstrap Tor, run:
+```
+tor -f torrc
+```
+This should start the client plugin, bootstrapping to 100% using WebRTC.
diff --git a/probetest/README.md b/probetest/README.md
index 8af42f5..44c7837 100644
--- a/probetest/README.md
+++ b/probetest/README.md
@@ -1,3 +1,12 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Overview](#overview)
+- [Running your own](#running-your-own)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
This is code for a remote probe test component of Snowflake.
### Overview
diff --git a/proxy/README.md b/proxy/README.md
index 381e3e5..a7496da 100644
--- a/proxy/README.md
+++ b/proxy/README.md
@@ -1,3 +1,48 @@
-This is a standalone (not browser-based) version of the Snowflake proxy.
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
-Usage: ./proxy
+- [Dependencies](#dependencies)
+- [Building the standalone Snowflake proxy](#building-the-standalone-snowflake-proxy)
+- [Running a standalone Snowflake proxy](#running-a-standalone-snowflake-proxy)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+This is a standalone (not browser-based) version of the Snowflake proxy. For browser-based versions of the Snowflake proxy, see https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/snowflake-webext.
+
+### Dependencies
+
+- Go 1.13+
+- We use the [pion/webrtc](https://github.com/pion/webrtc) library for WebRTC communication with Snowflake proxies. Note: running `go get` will fetch this dependency automatically during the build process.
+
+### Building the standalone Snowflake proxy
+
+To build the Snowflake proxy, make sure you are in the `proxy/` directory, and then run:
+
+```
+go get
+go build
+```
+
+### Running a standalone Snowflake proxy
+
+The Snowflake proxy can be run with the following options:
+```
+Usage of ./proxy:
+ -broker string
+ broker URL (default "https://snowflake-broker.bamsoftware.com/")
+ -capacity uint
+ maximum concurrent clients
+ -keep-local-addresses
+ keep local LAN address ICE candidates
+ -log string
+ log filename
+ -relay string
+ websocket relay URL (default "wss://snowflake.bamsoftware.com/")
+ -stun string
+ stun URL (default "stun:stun.stunprotocol.org:3478")
+ -unsafe-logging
+ prevent logs from being scrubbed
+```
+
+For more information on how to run a Snowflake proxy in deployment, see our [community documentation](https://community.torproject.org/relay/setup/snowflake/standalone/).
diff --git a/server/README.md b/server/README.md
index 312a506..18b24a7 100644
--- a/server/README.md
+++ b/server/README.md
@@ -1,3 +1,12 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Setup](#setup)
+- [TLS](#tls)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
This is the server transport plugin for Snowflake.
The actual transport protocol it uses is
[WebSocket](https://tools.ietf.org/html/rfc6455).
More information about the tor-commits
mailing list