commit c1b0fdd8cfaa89d2507c4bb23ef907c40de73d61 Author: Cecylia Bocovich <cohosh@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/snowf...) 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/snowf...) 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/snowf.... + +### 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).