mirror of
https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/snowflake.git
synced 2025-10-13 11:11:30 -04:00
114 lines
3.9 KiB
Markdown
114 lines
3.9 KiB
Markdown
<!-- 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).
|
|
In Snowflake, the client connects to the proxy using WebRTC,
|
|
and the proxy connects to the server (this program) using WebSocket.
|
|
|
|
|
|
# Setup
|
|
|
|
The server needs to be able to listen on port 80
|
|
in order to generate its TLS certificates.
|
|
On Linux, use the `setcap` program to enable
|
|
the server to listen on port 80 without running as root:
|
|
```
|
|
setcap 'cap_net_bind_service=+ep' /usr/local/bin/snowflake-server
|
|
```
|
|
|
|
Here is a short example of configuring your torrc file
|
|
to run the Snowflake server under Tor:
|
|
```
|
|
SocksPort 0
|
|
ORPort 9001
|
|
ExtORPort auto
|
|
BridgeRelay 1
|
|
|
|
ServerTransportListenAddr snowflake 0.0.0.0:443
|
|
ServerTransportPlugin snowflake exec ./server --acme-hostnames snowflake.example --acme-email admin@snowflake.example --log /var/log/tor/snowflake-server.log
|
|
```
|
|
The domain names given to the `--acme-hostnames` option
|
|
should resolve to the IP address of the server.
|
|
You can give more than one, separated by commas.
|
|
|
|
|
|
# TLS
|
|
|
|
The server uses TLS WebSockets by default: wss:// not ws://.
|
|
There is a `--disable-tls` option for testing purposes,
|
|
but you should use TLS in production.
|
|
|
|
The server automatically fetches certificates
|
|
from [Let's Encrypt](https://en.wikipedia.org/wiki/Let's_Encrypt) as needed.
|
|
Use the `--acme-hostnames` option to tell the server
|
|
what hostnames it may request certificates for.
|
|
You can optionally provide a contact email address,
|
|
using the `--acme-email` option,
|
|
so that Let's Encrypt can inform you of any problems.
|
|
The server will cache TLS certificate data in the directory
|
|
`pt_state/snowflake-certificate-cache` inside the tor state directory.
|
|
|
|
In order to fetch certificates automatically,
|
|
the server needs to listen on port 80,
|
|
in addition to whatever ports it is listening on
|
|
for WebSocket connections.
|
|
This is a requirement of the ACME protocol used by Let's Encrypt.
|
|
The program will exit if it can't bind to port 80.
|
|
On Linux, you can use the `setcap` program,
|
|
part of libcap2, to enable the server to bind to low-numbered ports
|
|
without having to run as root:
|
|
```
|
|
setcap 'cap_net_bind_service=+ep' /usr/local/bin/snowflake-server
|
|
```
|
|
|
|
|
|
# Multiple KCP state machines
|
|
|
|
The server internally uses a network protocol called KCP
|
|
to manage and persist client sessions.
|
|
Each KCP scheduler runs on a single thread.
|
|
When there are many simultaneous users (thousands),
|
|
a single KCP scheduler can be a bottleneck.
|
|
The `num-turbotunnel` pluggable transport option
|
|
lets you control the number of KCP instances,
|
|
which can help with CPU scaling:
|
|
https://bugs.torproject.org/tpo/anti-censorship/pluggable-transports/snowflake/40200
|
|
|
|
There is currently no way to set this option automatically.
|
|
You have to tune it manually.
|
|
|
|
```
|
|
ServerTransportOptions snowflake num-turbotunnel=2
|
|
```
|
|
|
|
|
|
# Controlling source addresses
|
|
|
|
Use the `orport-srcaddr` pluggable transport option to control what source addresses
|
|
are used when connecting to the upstream Tor ExtORPort or ORPort.
|
|
The value of the option may be a single IP address (e.g. "127.0.0.2")
|
|
or a CIDR range (e.g. "127.0.2.0/24"). If a range is given,
|
|
an IP address from the range is randomly chosen for each new connection.
|
|
|
|
Use `ServerTransportOptions` in torrc to set the option:
|
|
```
|
|
ServerTransportOptions snowflake orport-srcaddr=127.0.2.0/24
|
|
```
|
|
|
|
You can combine it with other options:
|
|
```
|
|
ServerTransportOptions snowflake num-turbotunnel=2 orport-srcaddr=127.0.2.0/24
|
|
```
|
|
|
|
Specifying a source address range other than the default 127.0.0.1
|
|
can help with conserving localhost ephemeral ports on servers
|
|
that receive a lot of connections:
|
|
https://bugs.torproject.org/tpo/anti-censorship/pluggable-transports/snowflake/40198
|