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 -->
|
||||
**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 -->
|
||||
|
||||
### 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
|
||||
|
||||
```
|
||||
cd client/
|
||||
go get
|
||||
go build
|
||||
tor -f torrc
|
||||
```
|
||||
This should start the client plugin, bootstrapping to 100% using WebRTC.
|
||||
Snowflake is currently deployed as a pluggable transport for Tor.
|
||||
|
||||
#### Dependencies
|
||||
#### Using Snowflake with Tor
|
||||
|
||||
Client:
|
||||
- [pion/webrtc](https://github.com/pion/webrtc)
|
||||
- Go 1.13+
|
||||
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.
|
||||
|
||||
---
|
||||
#### 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`.
|
||||
For example:
|
||||
#### Using the Snowflake Library with Other Applications
|
||||
|
||||
```
|
||||
ClientTransportPlugin snowflake exec ./client \
|
||||
-url https://snowflake-broker.azureedge.net/ \
|
||||
-front ajax.aspnetcdn.com \
|
||||
-ice stun:stun.l.google.com:19302
|
||||
-max 3
|
||||
```
|
||||
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).
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
### 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
|
||||
### More info and links
|
||||
|
||||
##### -- Testing with Standalone Proxy --
|
||||
|
||||
```
|
||||
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/)
|
||||
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/.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
### 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 \
|
||||
-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.
|
||||
`-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.
|
||||
|
||||
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.
|
||||
|
||||
### 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.
|
||||
The actual transport protocol it uses is
|
||||
[WebSocket](https://tools.ietf.org/html/rfc6455).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue