mirror of
https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/snowflake.git
synced 2025-10-13 11:11:30 -04:00
Cleaned up and reorganized READMEs
This commit is contained in:
Cecylia Bocovich
parent
2d7cd3f2b7
commit
c1b0fdd8cf
6 changed files with 144 additions and 68 deletions
82
README.md
82
README.md
|
|
@ -8,66 +8,47 @@ Pluggable Transport using WebRTC, inspired by Flashproxy.
|
||||||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||||||
**Table of Contents**
|
**Table of Contents**
|
||||||
|
|
||||||
|
- [Structure of this Repository](#structure-of-this-repository)
|
||||||
- [Usage](#usage)
|
- [Usage](#usage)
|
||||||
- [Dependencies](#dependencies)
|
- [Using Snowflake with Tor](#using-snowflake-with-tor)
|
||||||
- [More Info](#more-info)
|
- [Running a Snowflake Proxy](#running-a-snowflake-proxy)
|
||||||
- [Building](#building)
|
- [Using the Snowflake Library with Other Applications](#using-the-snowflake-library-with-other-applications)
|
||||||
- [Test Environment](#test-environment)
|
- [Test Environment](#test-environment)
|
||||||
- [FAQ](#faq)
|
- [FAQ](#faq)
|
||||||
- [Appendix](#appendix)
|
- [More info and links](#more-info-and-links)
|
||||||
- [-- Testing with Standalone Proxy --](#---testing-with-standalone-proxy---)
|
|
||||||
|
|
||||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||||
|
|
||||||
|
### Structure of this Repository
|
||||||
|
|
||||||
|
- `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
|
||||||
|
|
||||||
### Usage
|
### Usage
|
||||||
|
|
||||||
```
|
Snowflake is currently deployed as a pluggable transport for Tor.
|
||||||
cd client/
|
|
||||||
go get
|
|
||||||
go build
|
|
||||||
tor -f torrc
|
|
||||||
```
|
|
||||||
This should start the client plugin, bootstrapping to 100% using WebRTC.
|
|
||||||
|
|
||||||
#### Dependencies
|
#### Using Snowflake with Tor
|
||||||
|
|
||||||
Client:
|
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.
|
||||||
- [pion/webrtc](https://github.com/pion/webrtc)
|
|
||||||
- Go 1.13+
|
|
||||||
|
|
||||||
---
|
#### Running a Snowflake Proxy
|
||||||
|
|
||||||
#### More Info
|
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.
|
||||||
|
|
||||||
Tor can plug in the Snowflake client via a correctly configured `torrc`.
|
#### Using the Snowflake Library with Other Applications
|
||||||
For example:
|
|
||||||
|
|
||||||
```
|
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).
|
||||||
ClientTransportPlugin snowflake exec ./client \
|
|
||||||
-url https://snowflake-broker.azureedge.net/ \
|
|
||||||
-front ajax.aspnetcdn.com \
|
|
||||||
-ice stun:stun.l.google.com:19302
|
|
||||||
-max 3
|
|
||||||
```
|
|
||||||
|
|
||||||
The flags `-url` and `-front` allow the Snowflake client to speak to the Broker,
|
### Test Environment
|
||||||
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.
|
|
||||||
|
|
||||||
For logging, run `tail -F snowflake.log` in a second terminal.
|
|
||||||
|
|
||||||
You can modify the `torrc` to use your own broker:
|
|
||||||
|
|
||||||
```
|
|
||||||
ClientTransportPlugin snowflake exec ./client --meek
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
#### Test Environment
|
|
||||||
|
|
||||||
There is a Docker-based test environment at https://github.com/cohosh/snowbox.
|
There is a Docker-based test environment at https://github.com/cohosh/snowbox.
|
||||||
|
|
||||||
|
|
||||||
### FAQ
|
### FAQ
|
||||||
|
|
||||||
**Q: How does it work?**
|
**Q: How does it work?**
|
||||||
|
|
@ -103,17 +84,6 @@ manual port forwarding!
|
||||||
It utilizes the "ICE" negotiation via WebRTC, and also involves a great
|
It utilizes the "ICE" negotiation via WebRTC, and also involves a great
|
||||||
abundance of ephemeral and short-lived (and special!) volunteer proxies...
|
abundance of ephemeral and short-lived (and special!) volunteer proxies...
|
||||||
|
|
||||||
### Appendix
|
### More info and links
|
||||||
|
|
||||||
##### -- Testing with Standalone Proxy --
|
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/.
|
||||||
|
|
||||||
```
|
|
||||||
cd proxy
|
|
||||||
go build
|
|
||||||
./proxy
|
|
||||||
```
|
|
||||||
|
|
||||||
More documentation on the way.
|
|
||||||
|
|
||||||
Also available at:
|
|
||||||
[torproject.org/pluggable-transports/snowflake](https://gitweb.torproject.org/pluggable-transports/snowflake.git/)
|
|
||||||
|
|
|
||||||
|
|
@ -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.
|
This is the Broker component of Snowflake.
|
||||||
|
|
||||||
### Overview
|
### Overview
|
||||||
|
|
|
||||||
|
|
@ -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.
|
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.
|
||||||
|
|
||||||
### Flags
|
|
||||||
|
|
||||||
The client uses these following `torrc` options by default:
|
### 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:
|
||||||
|
|
||||||
```
|
```
|
||||||
|
go get
|
||||||
|
go build
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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 \
|
ClientTransportPlugin snowflake exec ./client \
|
||||||
-url https://snowflake-broker.azureedge.net/ \
|
-url https://snowflake-broker.torproject.net.global.prod.fastly.net/ \
|
||||||
-front ajax.aspnetcdn.com \
|
-front cdn.sstatic.net \
|
||||||
-ice stun:stun.l.google.com:19302
|
-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
|
`-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.
|
||||||
servers.
|
|
||||||
|
To bootstrap Tor, run:
|
||||||
|
```
|
||||||
|
tor -f torrc
|
||||||
|
```
|
||||||
|
This should start the client plugin, bootstrapping to 100% using WebRTC.
|
||||||
|
|
|
||||||
|
|
@ -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.
|
This is code for a remote probe test component of Snowflake.
|
||||||
|
|
||||||
### Overview
|
### Overview
|
||||||
|
|
|
||||||
|
|
@ -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/).
|
||||||
|
|
|
||||||
|
|
@ -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.
|
This is the server transport plugin for Snowflake.
|
||||||
The actual transport protocol it uses is
|
The actual transport protocol it uses is
|
||||||
[WebSocket](https://tools.ietf.org/html/rfc6455).
|
[WebSocket](https://tools.ietf.org/html/rfc6455).
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue